Cancel transfer
The Payments API provides the POST payments/v2/cancel
endpoint that allows you to perform:
- a total cancellation of a previously authorized transfer, which fully reverts the transaction and restores balances of the sender and receiver accounts.
- a partial cancellation of a previously authorized transfer, which cancels a portion of the original transaction.
A cancellation operation has its own logic and internal controls that follow different flows from the operations performed on the
payments/v1/payments
endpoint. For example, performing a cash-out transaction to revert a cash-in transaction with thepayments/v1/payments
endpoint is different from performing a cancellation transaction with thepayments/v2/cancel
endpoint to cancel the original cash-in. The cash-out will be considered a new transfer that is not related to the cash-in performed previously.
(A) - from | (G) - event_date |
(B) - account id | (H) - status after cancellation |
(C) - account balance after cancellation | (I) - original transaction information |
(D) - calculated by event_date | (J) - original authorization_id |
(E) - descriptor | |
(F) - amount to cancel |
- In transactions with cards on file (COF), the platform sends the refund operation to the acquirer to reverse the transaction on the card.
- In transactions made for a merchant, the platform posts a debit to the merchant's schedule, corresponding to the original transaction.
API reference
You can cancel a transfer by using the following endpoint. For more information, go to the API reference.
POST <URL>payments/v2/cancel
Cancellation payload request
To cancel a previously authorized transfer that was made with the payments/v1/payments
endpoint:
- Identify the original transfer either by its
tracking_id
or theauthorization_id
. - In the cancellation request, pass the following required fields to the
payments/v2/cancel
endpoint.- either the
original_tracking_id
or theauthorization_id
to identify the original transfer. - the
amount
to be canceled.
- either the
The complete list of parameters and their details are provided in the API reference.
Total cancellation
To make a total cancellation of a previously authorized transfer, provide the original authorization identifier and the same value amount as in the original authorization. For example, if the original transfer amount was $100 and it generated the authorization_id
of 15301234
, pass the following parameters in the cancellation payload request:
{
"authorization_id": 15301234,
"amount": 100.0
}
Partial cancellation
To partially cancel a previously authorized transfer, provide the value amount that is less than the amount of the original authorization. For example, if the original transfer amount was $85, its tracking_id
was unique-uuid-12345
, and you'd like to make the partial cancellation of $50.00, pass the following parameters in the cancellation payload request:
{
"original_tracking_id": "unique-uuid-12345",
"amount": 50.0
}
If the above request returns a successful response, there will be $35.00 remaining that can still be canceled. Payments API controls the outstanding cancellation balance. If the sum of partial cancellations exceeds the total amount of the original transaction, the platform denies a partial cancellation attempt to ensure integrity.
Example
Original cash-in request
The original cash-in transfer request to payments/v1/payments
identifies the destination account id
and the amount
of $100.
{
"descriptor": "DESCRIPTOR CASH-IN",
"from": [
{
"custom_info": {
"type": "DEPOSIT",
"external_id": "my-external-id-test-01"
}
}
],
"to": [
{
"amount": 100,
"account": {
"id": 12387
}
}
]
}
Original cash-in response
{
"authorization_id": 31251246,
"authorization_ids": {
"credit": 31251246,
"debit": null
},
"available_credit_limit": 1403.35,
"event_date": "2022-01-19T01:11:38.783Z",
"status_code": 1,
"tracking_id": "6c078af3-4510-4511-b60d-502db9a6c0c9"
}
Partial cancellation request of the cash-in
The partial cancellation request to payments/v2/cancel
includes the original_tracking_id
, which contains tracking_id
returned by the original cash-in response, and the partial cancellation value of $50 in the amount
field.
{
"original_tracking_id": "6c078af3-4510-4511-b60d-502db9a6c0c9",
"amount": 50
}
Partial cancellation response
{
"tracking_id": "08bcbccc-4dae-4c0b-8a67-1b0cf245ab44",
"authorization_ids": {
"credit": 0,
"debit": 16647083
}
}
Related pages
Guides / Payments and transfers
API reference / Cancel transfer
Updated 5 months ago