Skip to navigation

Issue a refund

Return funds to a customer for a charge, a payment intent, or a paid invoice — in full or in part.

View as Markdown

A refund returns what a customer paid: cash captured by the processor, customer credit that settled an invoice, or both. You can refund a charge by its payment intent or by the invoice it paid, refund the full amount or only part of it, and record refunds that were already processed outside PaymentKit.

Create a refund

A refund targets either a single succeeded charge or a paid invoice. You identify it in one of two ways:

  • payment_intent_id — refund the latest succeeded charge on a payment intent.
  • invoice_id — refund a paid invoice. PaymentKit resolves the charge that paid it, and, when the invoice was settled from the customer’s credit balance, returns that credit. (If the invoice was paid by more than one payment intent, refund by payment_intent_id instead.)

Provide at least one of these. If you supply both, payment_intent_id takes precedence.

  1. Open the Payment or Invoice you want to refund
  2. Click Refund
  3. Enter a full or partial amount and choose a reason
  4. Click Refund to send it to the processor

The refund appears immediately with a Pending status and updates to Succeeded once the processor confirms it (a refund that returns credit only is Succeeded right away). The Refund action on a paid invoice uses the by-invoice endpoint described on this page, so it handles cash and credit automatically.

Request fields

FieldTypeDescription
payment_intent_idstringThe payment intent to refund. Required unless invoice_id is provided.
invoice_idstringA paid invoice to refund. PaymentKit resolves the charge that paid it, or returns the credit that settled it. Required unless payment_intent_id is provided.
amount_atomintegerTotal value to return, in the smallest currency unit (e.g. cents). Must be greater than 0. Omit it for a full refund of the cash on the charge — that is what it has always meant. State it to refund an invoice settled partly from customer credit for more than its cash leg, which returns the credit too — and once that cash is gone, stating it is the only way to get the credit back: an omitted amount is refused with RFR14. An invoice settled entirely from credit has no charge, so there omitting it returns all the credit still applied. See Refunding an invoice paid with credit.
currencystringCurrency code (e.g. USD). Defaults to the charge’s currency; if provided, it must match the charge’s currency, or the invoice’s when the refund returns credit only.
reasonstringOne of manual, duplicate, fraudulent, requested_by_customer, expired_uncaptured_charge, manual_out_of_band. Defaults to manual.
refunded_out_of_bandbooleanSet true to record a refund you already processed elsewhere (e.g. in the processor’s dashboard). No processor call is made and the refund is marked succeeded immediately. Defaults to false. Not allowed when the refund would return credit only, since no processor money moved — the call fails with RFR21.
metadataobjectFree-form JSON, up to 10 KB.

Send an Idempotency-Key header on every create request. If the call is retried with the same key, PaymentKit returns the original refund instead of issuing a duplicate.

The refund object

{
"id": "re_prod_0a1b2c3d4e5f6g7h",
"account_id": "acc_prod_...",
"charge_id": "pa_prod_...",
"invoice_id": "in_prod_...",
"amount_atom": 1500,
"credit_restored_atom": 0,
"currency": "USD",
"status": "succeeded",
"reason": "requested_by_customer",
"processor_refund_id": "re_3Nz...",
"failure_code": null,
"failure_message": null,
"acquirer_reference_number": null,
"processed_at": "2026-06-17T14:05:00Z",
"metadata": null,
"created_at": "2026-06-17T14:04:58Z",
"updated_at": "2026-06-17T14:05:00Z"
}
FieldDescription
idRefund identifier, prefixed re_.
charge_idThe charge that was refunded. null for a refund that returned credit only — there is no charge behind it. Such a refund carries invoice_id instead; one of the two is always set.
invoice_idThe invoice you refunded, when the request named an invoice_id. null for a refund by payment_intent_id. When the payment behind that invoice settled several invoices, the credit leg is restored across all of them oldest invoice (lowest id) first, so the credit may have come back on a sibling invoice rather than this one.
amount_atom / currencyThe cash refunded at the payment processor, and its currency. 0 for a refund that returned credit only.
credit_restored_atomCustomer credit returned to the balance by this refund. 0 unless the invoice was settled partly or entirely from credit and the refund reached past its cash leg. Add it to amount_atom for the total value the customer got back.
statusLifecycle status — see below.
reasonThe reason supplied at creation, if any.
processor_refund_idThe processor’s own refund ID. null for out-of-band refunds, for refunds that returned credit only, or while still pending.
failure_code / failure_messagePopulated when status is failed.
acquirer_reference_numberThe refund’s own Acquirer Reference Number (ARN), the number the cardholder’s bank uses to trace the refund. Different from the original charge’s ARN. Card refunds only (cards, and Apple Pay, Google Pay and Link paid by card). null until the processor publishes it, often days after the refund succeeds. For Stripe, PayPal, Airwallex and Checkout.com, PaymentKit checks once a day for 14 days after the refund and sends a refund.updated event when it arrives. For Adyen, turn on Include ARN on your webhook before the refund: the ARN comes only with the refund notification. Always null for other processors and for refunds of other payment methods.
processed_atWhen the processor finished the refund. null while pending.

Refund statuses

StatusMeaning
pendingCreated and awaiting the processor’s response.
succeededFunds returned to the customer (or recorded out-of-band). Terminal.
failedThe processor rejected the refund. See failure_code / failure_message. Terminal.
requires_actionAdditional action is required before the refund can complete (rare). Non-terminal.
cancelledCancelled before completion — from pending or requires_action. Terminal.

A refund that returns credit only never waits on a processor, so it is created as succeeded.

Look up refunds

MethodPathReturns
GET/api/{account_id}/payments/refunds/Every refund in the account (paginated)
GET/api/{account_id}/payments/refunds/{refund_id}A single refund
GET/api/{account_id}/payments/refunds/by_charge/{charge_id}All refunds for a charge (paginated)
GET/api/{account_id}/payments/refunds/by_intent/{payment_intent_id}All refunds for a payment intent (paginated)
curl https://app.paymentkit.com/api/{account_id}/payments/refunds/by_intent/pi_abc123 \
-H "Authorization: Bearer sk_live_..."

A refund that returned credit only has no charge and no payment intent, so it does not appear under by_charge or by_intent. Fetch it by its own id, or from the account-wide list.

Rules and limits

  • The charge must have succeeded. You can only refund a charge in the succeeded state. An invoice settled entirely from credit has no charge; refund it by invoice_id.
  • You cannot refund more than the refundable amount — the captured amount, minus any refunds that have already succeeded, minus any refund still pending settlement, plus any customer credit still applied to the invoice. An invoice with no cash left and no credit still applied has nothing left to refund.
  • Partial refunds are allowed as long as the running total stays within the refundable amount. Issue several partial refunds against the same charge until its cash is fully reversed. For an invoice settled partly from credit, asking for the full amount in one call is the simplest path, but a later call by invoice_id with a stated amount_atom for the remaining credit also works — see below.
  • Refunding an invoice payment reduces the paid amount on the linked invoice(s) accordingly. A refund that returns credit only leaves the invoice’s paid amount as it is: no cash moved.
  • A refund by payment_intent_id has to move cash. Once a charge has no cash left to reverse — fully refunded, or held by a refund still pending settlement — further refunds addressed to the payment intent are refused with RFR14, even if credit is still applied to the invoice. The error message tells you to refund by invoice_id, which returns that credit.

Refunding an invoice paid with credit

An invoice can be settled by a card payment, by the customer’s credit balance, or by both. When both, a stated amount_atom is the total value to return, and PaymentKit fills it cash first: money goes back to the card before any credit does, and credit is returned only for the part the cash could not cover.

Returning credit is a second kind of money movement, so you have to ask for it. Omitting amount_atom refunds the cash on the charge and leaves the customer’s balance untouched, exactly as it did before this existed.

For a 50invoicewhere50 invoice where 20 of credit was applied and the card paid $30:

amount_atomBack to the card (amount_atom on the response)Back to the balance (credit_restored_atom)
300030000
400030001000
500030002000

So a partial refund the cash leg covers behaves exactly as it always has, and asking for the whole invoice makes the customer whole.

The refundable amount for such an invoice is the cash still on the charge plus the credit still applied to it — 50intheexampleabove,not50 in the example above, not 30.

Preview the split

To see the split before you ask, read it from the payment:

curl https://app.paymentkit.com/api/{account_id}/payments/refunds/by_intent/{payment_intent_id}/refundable \
-H "Authorization: Bearer sk_live_..."
{
"payment_intent_id": "pi_prod_...",
"currency": "usd",
"cash_refundable_atom": 3000,
"credit_refundable_atom": 2000,
"total_refundable_atom": 5000
}

Or read it from the invoice. The response has the same shape, plus an invoice_id; its payment_intent_id is null when the invoice has no charge behind it. This is the preview for an invoice settled entirely from $20 of credit:

curl https://app.paymentkit.com/api/{account_id}/payments/refunds/by_invoice/{invoice_id}/refundable \
-H "Authorization: Bearer sk_live_..."
{
"payment_intent_id": null,
"invoice_id": "in_prod_...",
"currency": "usd",
"cash_refundable_atom": 0,
"credit_refundable_atom": 2000,
"total_refundable_atom": 2000
}

total_refundable_atom is the most amount_atom may ask for, and the two legs are computed the same way POST /refunds validates them, so a pending refund is already subtracted from both: the cash it still holds, and the credit leg it will itself return when it settles. An unknown or unpaid invoice returns 404 with RFR20. An invoice with nothing left to return is not an error: you get 200 with every amount at 0. This is what the business portal’s refund form reads to offer a full refund and show where each part goes. One caveat: for an invoice that still has cash, the by-invoice preview counts that invoice’s credit only, while POST /refunds by invoice_id accepts up to the cash plus the credit still applied across every invoice the same payment settled, so total_refundable_atom can under-state what a refund may ask for when one payment settled several invoices.

State amount_atom explicitly to get the credit leg back, in one call. Omitting it still means what it always has — reverse the cash on the charge — so a full refund with no amount returns cash only and leaves the balance alone. If you do that and the customer still has credit applied to the invoice, make a second call with the same invoice_id and a stated amount_atom: it returns the remaining credit as a credit-only refund (below). A second call with the amount omitted again fails with RFR14 — that is what lets an integration retry “refund the invoice” until it sees RFR14 without ever draining the customer’s credit by accident — and so does a second call addressed to the payment_intent_id, because the charge has no cash left to move.

The credit half is recorded on the ledger as a refund_reversal credit note carrying meta.refund_id, so you can tie it back to this refund, and meta.restored_from_credit_note when the credit went back on an expiring grant. See Credit notes for how it is split across expiring grants.

Invoices settled entirely from credit

An invoice settled entirely from credit has no charge behind it. Refund it by invoice_id, as you would any other invoice. There is no processor to wait for, so the refund is succeeded as soon as it is created, and refund.created and refund.succeeded fire as usual.

The refund object tells you what happened: charge_id is null, invoice_id is the invoice you named, amount_atom is 0, and credit_restored_atom is the credit that went back to the customer’s balance. Omit amount_atom to return everything still applied, or state a smaller amount for a partial refund and come back for the rest later. On the ledger the refund is a refund_reversal credit note carrying meta.refund_id, exactly like the credit half of a mixed refund. The invoice stays paid.

This path replaces the RFR24 error. Callers that handled RFR24 can drop that branch; the code stays reserved and is no longer returned.

POST /customers/{customer_id}/credit-balance/increase is still the way to grant credit that was never tied to an invoice — goodwill, for example. It is not a way to refund an invoice: it adds credit without touching the invoice, and gives you no refund object to reconcile against.

Webhook events

EventTrigger
refund.createdA refund was created.
refund.updatedA refund field changed. Not sent for the transition to failed, and not reliably sent for the transition to succeeded — reconcile settlements on refund.succeeded.
refund.succeededThe refund settled.
refund.failedThe refund was rejected. Carries failure_code and failure_message.

Subscribe to refund.succeeded to reconcile completed refunds. It is the positive signal for a refund reaching a terminal successful state, and it fires on every path a refund can settle through — including refunds that settle asynchronously, hours after they were created, and refunds that returned credit only, which settle the moment they are created.

refund.succeeded does not replace refund.updated — nothing was removed, so an integration watching refund.updated keeps behaving exactly as it does today. If you do receive both for the same refund, treat them as the same fact rather than two refunds. Reconcile on refund.succeeded: it is the event that fires on every settlement path.

refund.failed is different: it replaces refund.updated for the failure transition, and you will not receive both.

Once refund.succeeded fires, the refund is terminal for every ordinary flow and the charge’s refundable amount is reduced in the same transaction as the event. An administrative correction can still move a settled refund back to failed afterwards, which emits refund.failed.

What the payload carries

The webhook body’s data.object carries the refund’s stored columns, including amount_atom, currency, status, charge_id, processor_refund_id, reason, failure_code, failure_message, processed_at, created_at, updated_at.

Two differences from the REST response shown above are worth knowing before you parse it:

  • Your own metadata arrives as meta, not metadata. The REST API renames the column; the webhook body does not. metadata in a webhook body is never the refund’s metadata.
  • Keys are never omitted. A field with no value arrives as null, so a refund recorded out of band — which has no processor reference — arrives as "processor_refund_id": null, and a refund that returned credit only arrives as "charge_id": null. Branch on the value, not on whether the key exists.

The same event is also retrievable from GET /api/{account_id}/events/, where it carries a separate metadata object describing the transition — including amount_atom, currency, from_state, to_state, and processor_refund_id when there is one. That object is not part of the webhook body, and it is unrelated to the refund’s own meta.