Refund a captured transaction
The refund endpoint returns a full or partial amount of funds to a customer. It works for transactions that have already been captured, such as a standard sale or an authorize that you have since captured.
For a broader breakdown of the refund concept and balance limitations, see Refunds. For additional request configurations, see Refund a transaction.
Prerequisites
To initiate a refund, you need the unique transactionId of a captured transaction. The target transaction must also have a positive refundableAmount balance remaining.
Process a refund
To execute a refund, send a POST request to the refund endpoint.
curl --location --request POST \
'https://staging-api.payments.ai/v1/public-api/organizations/:organizationId/transactions/{transactionId}/refund' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey <keyValue>' \
--data '{
"amount": 10.50
}'
Parameters
amount(number, optional): The specific amount to refund. The value must be greater than zero and cannot exceed the transaction's currentrefundableAmount. If you omit this field, PaymentsAI defaults to refunding the full remainingrefundableAmount.
Response handling
On a successful request, the endpoint returns a new Transaction object linked directly to the original transaction record.
Success metrics
Upon receiving a 200 OK response, the original transaction status updates to refunded (for a full refund) or partially-refunded (for a partial refund). The corresponding refundableAmount decreases by the specified value.
Error codes
| Code | Status | Description / Resolution |
|---|---|---|
409 | Conflict | The transaction's current state does not allow a refund. This occurs if the balance is already fully refunded, the transaction type is not refundable, or a separate refund action is currently in progress. The response body contains no details field. Perform a GET request on the transaction to verify its status and refundableAmount. |
422 | Unprocessable Content | The requested amount exceeds the remaining refundableAmount, equals zero or less, or utilizes an invalid decimal precision. The response body includes a details field describing the exact validation error. |
See Errors for the complete error handling reference manual.
Transaction lifecycle reference
| Step | API Call | Resulting Status |
|---|---|---|
| Authorize | POST /transactions with type: "authorize" | waiting |
| Capture | POST /transactions with type: "sale" (using the same paymentInstrumentId) | completed |
| Partial refund | POST /transactions/{id}/refund with amount < refundableAmount | partially-refunded |
| Full or remaining refund | POST /transactions/{id}/refund with no body, or amount = refundableAmount | refunded |
Once a transaction reaches the refunded state, its refundableAmount drops to 0, and any subsequent refund calls return a 409 Conflict error. A transaction marked as partially-refunded can continue to accept multiple refund requests until the cumulative balance matches the total original transaction value.