Skip to main content

Refunds

A refund returns funds to the customer for a transaction that has already been captured. You can refund either the full amount or a partial amount. For step-by-step instructions, see Refund a transaction.

Refund lifecycle​

When a transaction is refundable​

A transaction is refundable once it has been captured, such as a sale or an authorize that you have since captured. The response field refundableAmount shows how much can still be refunded:

  • amount: The original transaction amount.
  • refundAmount: The total amount already refunded.
  • refundableAmount: The remaining amount available to refund.

A transaction that has not been captured (with a status of waiting) cannot be refunded because there are no settled funds to return.

Full vs partial refunds​

The refund request body carries a single optional field, amount:

  • Omit amount (send an empty or missing body) to refund the full refundableAmount.
  • Set amount to refund a portion of it. The value must be greater than zero and no larger than refundableAmount.

After a partial refund, the transaction status updates to partially-refunded and refundableAmount decreases. Once you refund the full amount, the status updates to refunded.

Endpoint​

POST /v1/public-api/organizations/{organizationId}/transactions/{transactionId}/refund

{transactionId} is the ID returned when you created the transaction. The endpoint returns a new Transaction object linked to the original transaction. See Refund a transaction.

Errors​

CodeWhenWhat to do
409The transaction's state does not allow a refund. This occurs if it is already fully refunded, not refundable, or a refund is in progress. The body has no details field.Treat as "cannot refund in the current state." Perform a GET request on the transaction to read its status and refundableAmount.
422The requested values cannot be processed. This happens when amount is greater than refundableAmount, less than or equal to zero, or has invalid precision. The body includes a details field.Parse the details field, correct the amount, and retry the request.

See Errors for the full error reference.

Webhooks​

There is no dedicated transaction-refunded event. A refund is a distinct Transaction object where type is "refund", meaning it triggers the same webhook events as other transactions:

  • transaction-processed: Fires when the refund completes successfully on the gateway side. Inspect the payload's type field ("refund") to distinguish a refund from a sale or authorization.
  • transaction-declined: Fires if the gateway declines the refund (rare, but possible if the underlying account is closed).

The original transaction's status updates to partially-refunded or refunded once the refund settles. To react to refunds specifically, subscribe to transaction-processed and filter for type === "refund" in your handler. See Subscription webhooks for the full event list.