Skip to main content
Sometimes you need to send money back — a duplicate invoice, a returned order, an overcharge. One endpoint handles it, but when you call it changes what happens: refund quickly enough and Nickel cancels the original charge outright (a void, with no processing fee); refund after the charge has settled and the money is sent back as a true refund. This guide walks through both.
In the API, an invoice is a payment link — the endpoints and field names below say paymentLink. Same thing; this guide says “invoice” because that’s what your customer sees.
Before you start: You need a payment in the SUCCEEDED state — only successful payments can be refunded. Follow Send an Invoice and Get Paid to create one in the sandbox.
1

Refund the payment

Call POST /payment/{paymentId}/refund with the amount to give back. For a full refund, pass the payment’s full amountInCents; for a partial refund, pass less. The reason is optional and shows up in your records:
curl -X POST https://rest.staging.nickel.com/payment/cmr9zvqgk000csf025pyi3qfi/refund \
  -H "Authorization: Bearer $NICKEL_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 12055, "reason": "Duplicate invoice"}'
The response is the updated payment:
{
  "id": "cmr9zvqgk000csf025pyi3qfi",
  "status": "REFUNDED",
  "amountInCents": 12055,
  "chargedAmountInCents": 12230,
  "fees": [{ "type": "CREDIT_CARD_FEE", "amountInCents": 350 }],
  "refunds": [
    {
      "id": "cmr9zwf4s000rsf02qxi7es8s",
      "amountCents": 12055,
      "refundDate": "2026-07-07T01:53:47.933Z",
      "voided": false
    }
  ],
  ...
}
amountCents is in cents, and the refund amount can’t exceed what’s refundable on the payment. Any refund — even a partial one — moves the payment’s status to REFUNDED.
2

Check whether it voided

Look at refunds[].voided in the response:
  • "voided": true — the original charge was cancelled before it settled. The money movement never completes, and no processing fee applies. This is possible within minutes to a few hours of the payment, while the card charge hasn’t been submitted for settlement (or the ACH debit hasn’t been sent to the network).
  • "voided": false — the charge already settled, so this is a true refund: the money travels back to your customer. For card payments the original processing fee still applies, because the card networks charged it when the payment was made.
You can’t choose which happens — Nickel voids automatically whenever it still can, because that’s the better outcome for you.
3

Watch for the webhook

Your webhook subscription receives payment.voided when the charge was cancelled, or payment.refunded for a true refund. Either way, fetch the payment with GET /payment/{paymentId} for the current state — see Webhook Events.
4

Know what happens to the invoice

A fully refunded payment reopens its invoice: the invoice’s status returns to ACTIVE and the amount becomes payable again, so your customer can re-pay the corrected version. If you don’t want that, delete the invoice with DELETE /paymentLink/{paymentLinkId} or leave it to expire.

​
Don’t confuse refunds with ACH returns

A refund is something you initiate. An ACH return is initiated by your customer’s bank — insufficient funds, a closed account, or a disputed debit — and moves the payment to FAILED, not REFUNDED. Returns can arrive up to 60 days after the payment. How Payments Work covers what happens to the money in each case.

​
Where to go next

Track your payouts

What refunds and returns mean for the money that reaches your bank.

Webhook events

Subscribe to payment.refunded and payment.voided.