Cancel Payout

The Cancel Payout API enables cancelling single or multiple payment requests in one call. In cases where a problem is identified with the payment method or payment information is incorrect, this API provides the provision to cancel the payment.

A payment can only be cancelled if the transaction status is one of the following:

Email Sent — Recipient onboarding email has been sent.

Email Opened — Recipient onboarding email has been opened.

Payment Not Initiated — Payment processing has not yet begun.

Important Behavior:

If the payment method is already saved for an existing recipient, no email is triggered and the payout is initiated upon receiving and validating the initiate payment request. If the payment is already in process, cancellation cannot be done.

Once the API is executed, the respective payout status will turn "Void". A new payment request can be sent thereafter.

Supports both single and bulk cancel operations in a single call.

Field: `actionCode`

The actionCode field indicates the overall result of the bulk cancel operation:

Code	Result	Description
00	All Success	All transactions in the batch were cancelled successfully.
01	Partial Success	Mix of successful cancellations, failures, and/or errors in the batch.
02	All Failed	All transactions in the batch failed to cancel.

Field: `statusCode`

Code	Status	Description
200	Success	API body was correct and all payments cancelled successfully.
207	Partial Success	API body was correct; mix of success, fail, and/or error responses.
400	Bad Request	One or more required fields are missing or all transactions failed validation.
401	Unauthorized	API session key at header was incorrect.
404	Not Found	A referenced entity was not found (see `message` for details).
500	Server Error	Internal server error.

curl --location --request PUT 'https://staginggateway.fintainium.com/gateway/api/payouts/batch/cancel' \ --header 'sessionKey: YOUR_API_KEY_HERE' \ --header 'Content-Type: application/json' \ --data-raw '{ "businessId": 217819, "recipients": [ { "recipientInternalId": "379", "transactionId": "1231", "recipientEmailAddress": "abc@xyz.com" }, { "recipientInternalId": "380", "transactionId": "1232", "recipientEmailAddress": "abc2@xyz.com" }, { "recipientInternalId": "381", "transactionId": "1233", "recipientEmailAddress": "abc3@xyz.com" } ] }'

{ "statusCode": 200, "actionCode": "00", "message": "3 Payment cancelled successfully", "failedCount": 0, "failedMessageList": [], "successCount": 3, "transactions": [ { "transactionId": "1231", "status": "cancelled" }, { "transactionId": "1232", "status": "cancelled" }, { "transactionId": "1233", "status": "cancelled" } ], "transmissionDateTime": "2023-08-30T06:10:13.505+00:00" }

Field: actionCode#

Field: statusCode#

Request

Responses

Field: `actionCode`

Field: `statusCode`