📘

For any new deployments, the recommendation is to use the enhanced Payment methods API instead of the Cancel transfer endpoint described in this guide. All new feature developments will be available only in the Payment methods API. For more information, contact your Pismo representative.

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.

Cancel transfer payload request

To cancel a previously authorized transfer that was made with the Transfer funds (payments/v1/payments) endpoint, use the Cancel transfer (payments/v2/cancel) endpoint.

POST <URL>payments/v2/cancel

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 Cancel transfer 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
}

By default, if there are any fees associated with the original transfer, when you perform a total cancellation, the Pismo platform cancels the fees automatically (cancel_fees field is true). If you don't want the fees to be cancelled, set the cancel_fees field to false.

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. The Pismo platform 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.

By default, if there are any fees associated with the original transfer, when you perform a partial cancellation, the Pismo platform does not cancel the fees automatically (cancel_fees field is false). If you want the fees to be cancelled, set the cancel_fees field to true.

Example

The following example shows how to perform a partial cancellation of the original cash-in transfer and to cancel any associated fees.

Original cash-in request

The request to Transfer funds (payments/v1/payments) identifies the amount of the original cash-in transfer as $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

The original cash-in transfer response from the Transfer funds (payments/v1/payments) provides the tracking_id that you can use in the subsequent cancellation request.

{
   "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

To cancel $50 of the original cash-in transfer and all associated fees, provide the following in the request to the Cancel transfer (payments/v2/cancel) endpoint:

• original_tracking_id, which contains tracking_id returned by the original cash-in response
• partial cancellation value of $50 in the amount field
• cancel_fees field set to true

{
  "original_tracking_id": "6c078af3-4510-4511-b60d-502db9a6c0c9",
  "amount": 50,
  "cancel_fees": true
}

Partial cancellation response

{
  "tracking_id": "08bcbccc-4dae-4c0b-8a67-1b0cf245ab44",
  "authorization_datetime": "2023-01-02T15:04:05.000Z",
  "authorization_ids": {
    "credit": 0,
    "debit": 16647083
  },
  "metadata": {
    "my-custom-key": "my-custom-value"
  }
}