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 the payments/v1/payments endpoint is different from performing a cancellation transaction with the payments/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.

📘

• 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:

1. Identify the original transfer either by its tracking_id or the authorization_id.
2. In the cancellation request, pass the following required fields to the payments/v2/cancel endpoint.
   • either the original_tracking_id or the authorization_id to identify the original transfer.
   • the amount to be canceled.

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