Manage batch transfers
Learn in this section about how you can use the corresponding API endpoints to manage different scenarios.
Handle failed batch transfer items
There are two types of failures for batch transfer items: validation and booking failures. Please find below the instructions on how to handle failed batch transfer items.
Validation failure
After adding items to the batch, if a batch transfer item fails the schema validation, the item status will transition to VALIDATION_FAILED. See Batch transfer item statuses to learn more details. You can call List all items within a batch API to find VALIDATION_FAILED transfer items. Please refer to Batch transfer item errors to identify failure reasons. Next, you can edit the batch transfer by calling Delete items within a batch API to delete invalid items and Add items to a batch API to add transfer items with the correct information.
Booking failure
If a batch transfer item fails to be booked, the item status will transition to BOOKING_FAILED. See Batch transfer item statuses to learn more details. You can call List all items within a batch API to find BOOKING_FAILED transfer items. Please refer to Batch transfer item errors to identify failure reasons and resubmit a new batch transfer with the correct information.
Delete a batch transfer
Before submitting a batch transfer (DRAFTING status only), you can call Delete a batch transfer API to delete/discard a draft batch by specifying the batch transfer id.
Example request
If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.
Example response
Cancel a batch transfer
Once a batch transfer is submitted, the processing begins where transfer items will be booked accordingly as payouts, and it cannot be cancelled via API (See Batch transfer statuses to learn more about status transitions):
- If a batch transfer is not funded beyond the transfer date (status is
OVERDUE), you can contact our customer support team or your account manager for cancellation. Note that an FX delta may apply. - If the status of a batch transfer is
BOOKEDorPARTIALLY_BOOKED, you can only cancel individually-booked transfer items (See Cancel a payout).
Refund and Fees
How the refund is processed depends on the batch transfer status:
If a batch transfer is
CANCELLED, the batch transfer amount (less any applicable fees) will be refunded to your Wallet.If a batch is
PARTIALLY_BOOKED, batch items that failed to be booked will be refunded to your Wallet.If a batch transfer is
BOOKED, which means all batch items have been successfully booked as single transfers, you should refer to Handle failed transfers to learn how transfers are refunded. Please note that failed transfers booked by a batch transfer will be refunded to the funding source, either Wallet or Linked Account.
FX cancellation delta fee
FX cancellation delta fee is applicable in the event that the market rate has moved from the rate of the original conversion. Upon the batch transfer cancellation, this fee will be separately deducted from your Wallet.