Issue a refund
Return funds to a customer for a charge, a payment intent, or a paid invoice — in full or in part.
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 bypayment_intent_idinstead.)
Provide at least one of these. If you supply both, payment_intent_id takes precedence.
Dashboard
API
- Open the Payment or Invoice you want to refund
- Click Refund
- Enter a full or partial amount and choose a reason
- 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
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
Refund statuses
A refund that returns credit only never waits on a processor, so it is created as succeeded.
Look up refunds
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
succeededstate. An invoice settled entirely from credit has no charge; refund it byinvoice_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_idwith a statedamount_atomfor 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_idhas 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 withRFR14, even if credit is still applied to the invoice. The error message tells you to refund byinvoice_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 20 of credit was applied and the card paid $30:
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 — 30.
Preview the split
To see the split before you ask, read it from the payment:
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:
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
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, notmetadata. The REST API renames the column; the webhook body does not.metadatain 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.