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 following table outlines important considerations for some request parameters. The complete list of parameters and their details are provided in the API reference.

Cancellation response

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