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.