Cancel a Pay In transaction with the API
How you cancel a pay-in transaction depends on the transaction status. If a transaction hasn’t been settled yet, you can void it. If a transaction has been settled, or settlement is pending, you can refund the transaction.
This guide explains how to void and refund transactions with the Payabli API.
Choose a method
First, choose a transaction cancellation method based on the transaction’s settlement status.
Diagram: Transaction cancellation decision flow
This flowchart shows how to choose a cancellation method for a Pay In transaction:
- Has the transaction been settled?
- No: Use Void — cancels an existing sale or captured authorization and prevents future captures for non-captured authorizations.
- Yes: Use Refund — sends money back to the accountholder after the transaction has settled.
Void
A void cancels an existing sale or captured authorization. Voiding non-captured authorizations prevents future captures. You can void unsettled transactions. If a transaction has been settled, refund it instead.
Refund
A refund sends money back to the accountholder after a transaction has been settled. If a transaction hasn’t been settled, void it instead.
Check the transaction status
Before you cancel, check the transaction’s SettlementStatus to decide which method to use. Send a GET request to the details endpoint with the transaction’s transId:
A SettlementStatus of 0 (Pending) means the transaction is still in an open batch, so you void it. A value of 1 (In Transit) or higher means settlement has begun, so you refund it instead.
For the full mapping of status codes to methods, see the Decision guide: Void vs refund.
Path parameters
When canceling a transaction via the API, you always need the transId, which is the paymentTransId for the transaction. For partial refunds, you also need the amount to refund.
Required for voids and refunds
The paymentTransId identifying the transaction. You can find this in the success response for the original transaction.
Required for partial refunds
The amount to refund from the original transaction, minus any service fee charged on the original transaction. This amount can’t be greater than the original total amount of the transaction minus the service fee. For example, if a transaction was $90 plus a $10 service fee, you can refund up to $90. For a full refund, omit the amount and call POST /v2/MoneyIn/refund/{transId}.
Void a transaction
You can void transactions that haven’t settled yet.
This example voids the transaction with a paymentTransId of 10-3ffa27df-b171-44e0-b251-e95fbfc7a723:
A successful void returns a 200 status. If you try to void a transaction that has already been voided, the API returns an error response.
Successful void response
Invalid TransStatus response
Refund a transaction
You can refund settled transactions. If you use the Enhanced Refund Flow, see the guide for information about how refunds are handled in different scenarios.
These examples show full and partial refunds.
Full refund
Partial refund
This example refunds the transaction with a paymentTransId of 10-3ffa27df-b171-44e0-b251-e95fbfc7a723 for the total amount of the transaction.
A successful refund returns a 201 status with a JSON body.
Full refund
Partial refund
This example shows a successful refund response for a full refund.
Just like sale transactions, you can void a refund transaction before the batch closes. Use the paymentTransId from the refund transaction response as the transId in the void request.
Related resources
See these related resources to help you get the most out of Payabli.
Prerequisites
- Make a sale transaction with the API - You need to make a transaction before voiding or refunding it
References
- Pay In schemas - Learn about Pay In (money in) transaction schemas
- Pay In statuses - Learn about Pay In (money in) statuses