Return funds from the merchant to the customer after a transaction has been processed (batched)
The Refund Transaction endpoint allows you to return funds from the merchant to the customer after a transaction has been processed (batched). Refunds can be full or partial, giving you flexibility in handling returns or adjustments.
Key Points:
Transaction Must Be Settled: Refunds can only be processed on transactions that have been batched.
Partial Refunds Supported: You can refund any amount between $0.01 and the total remaining refundable amount of the transaction.
Child Transactions: A refund creates a child transaction with type = refund, linked to the original transaction via the reference_id.
Settlement Tokenization Considerations:
If your merchant account has Settlement Tokenization enabled and the transaction is not yet available for refund via API, this endpoint will return a status code 422 with the message:
This transaction is not yet available to be refunded via API. You can still complete this transaction through the card present flow.
In such cases, you may use the POST /terminal/void-or-refund endpoint instead.
Usage Notes
Refund Eligibility: Use the is_refundable flag on the transaction object to determine if the transaction can be refunded.
Calculating Refund Amounts: The total amount refunded across all refund transactions cannot exceed the original transaction amount.
Multiple Refunds: You can issue multiple partial refunds as long as the cumulative total does not exceed the original transaction amount.
Child Transactions: Each refund action creates a child transaction linked to the original transaction for tracking purposes.
Error Handling: Attempting to refund more than the remaining refundable amount will result in an error.
Response Structure
| Code | Response | Reason |
|---|---|---|
| 200 | Success | Returns the original transaction object with an added child transaction of type = refund. |
| 400 | Bad Request | Invalid request parameters. |
| 401 | Unauthorized | Authentication failed. |
| 404 | Not Found | Transaction ID does not exist. |
| 422 | Unprocessable Entity | The transaction cannot be refunded (e.g., amount exceeds refundable total). |
| 500 | Internal Server Error | An unexpected error occurred on the server. |
Important Considerations
Refund Timing: Refunds may take several business days to process, depending on the customer's bank.
Customer Notification: It's good practice to notify the customer when a refund has been initiated.
Refunding Terminal Transactions: If you are refunding a transaction that was processed through a terminal, and Settlement Tokenization is not enabled or the transaction is not yet available for refund via API, you may need to process the refund directly through the terminal.
Testing Environment Notes
- In a sandbox account, transactions are not refundable until 12 am EST.
- Certain behaviors in the testing environment may differ from production; plan accordingly.