Cancel a 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 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.

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

  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.

Field

Type

Description

original_tracking_id

string

The tracking_id returned in the response of the original transfer. Either this field or the authorization_id field is required to identify the original transfer that needs to be canceled with this request.

authorization_id

integer

The authorization_ids.credit or authorization_ids.debit returned in the response of the original transfer. Either this field or the original_tracking_id field is required to identify the original transfer that needs to be canceled with this request.

amount

float

This required field indicates the full or partial amount to cancel, which cannot be more than the original transaction amount.

tracking_id

string

A unique 36-char identifier of the pending cancellation. If not provided, the Pismo platform generates the UUID randomly. This field is useful for tracking and searching transaction information.
This field needs to be sent to guarantee the idempotence of the request. Requests that use the same tracking_id are considered the same. If tracking_id is not received, each request is treated as a new one.

processing_code

object

This optional field identifies the processing codes to be used in the cancellation operation. Depending on the type of transaction you want to cancel, this object can contain only one subfield of string type: credit or debit. If no processing codes are specified, the platform uses the processing codes that correspond to the original authorization.

metadata

key-value object

This optional field can be used with external operations to add customized supplementary information for the payment. The Pismo platform passes this object on to the acquirer in transactions involving the call to the acquirer and sends it in the events related to the stream of data produced at the end of the request.
The Pismo platform accepts any object of the key-value type (JSON). The platform only receives and passes this information on to the acquirer and does not perform any validation or processing on this field.

descriptor

string

This optional field provides a complementary cancellation description. This field is passed on to the acquirer in transactions involving calls to the acquirer.

Cancellation response

Field

Type

Description

tracking_id

string

Represents the provided tracking_id or the identifier automatically generated by the Pismo platform.

authorization_ids

object

Object containing the identifications of credit and debit authorizations generated at the end of the cancellation process.

authorization_ids.credit

integer

Identification of the credit authorization, where applicable.

authorization_ids.debit

integer

Identification of debit authorization, where applicable.

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


Did this page help you?