Single and Bulk Payout Implementation with Recurring Flow Updates

This document provides an overview of our single and bulk payout functionalities, including the recurring flow for updating their statuses.

Payout Options

Our system supports two payout options via the External API:

1. Single Payout: Send funds electronically to one recipient at a time.
2. Bulk Payout: Send funds electronically to multiple recipients in a single API call.

Single Payout Flow

1. Initiate Payout: A request is sent via the API endpoint specifying recipient details (bank account information, amount, currency), and an optional reference ID.
2. Process Payout: The system validates the request and initiates the transfer of funds to the recipient's account.

Bulk Payout Flow

1. Prepare Recipient List: A list containing recipient details for each payout (bank account information, amount, currency) is prepared.
2. Submit Bulk Payout: The recipient list and any additional information (total payout amount, currency) are sent via the dedicated bulk payout API endpoint.
3. Process Individual Payouts: The system validates the request, initiates individual transfers for each recipient, and provides individual status updates for each payout within the response.

Transaction Status and Finality

Each payout transaction moves through one or more statuses as it is processed. It is important to understand that not all statuses are final.

Final statuses:

Completed — the payout has been successfully delivered to the recipient.
Reversed — the payout was returned and will not be retried.

Non-final statuses:

All other statuses, including but not limited to Pending, Processing, and Failed, are not final and should not be treated as the end state of a transaction.

This is because our system may automatically retry a transaction on your behalf, including routing it through a fallback provider, if it does not succeed with the initial provider. A transaction showing Failed may therefore still change to Completed or Reversed as retries take place.

What this means for integrators:

• Do not treat Failed (or any status other than Completed/Reversed) as a terminal outcome.
• Do not independently retry or resubmit a transaction based on a non-final status, as we may already be retrying it with a fallback provider on our end. Doing so could result in duplicate payouts.
• Use the Get Payout by ID endpoint, or listen for webhook status updates, to track a payout until it reaches a final status.
• Only treat a payout as concluded once it reflects Completed or Reversed.

API Documentation

The API documentation provides detailed information on:

• Specific API endpoints for single and bulk payouts.
• Data format requirements for recipient information and payout details.

The following endpoints are available for Payouts:

• Initiate Payout with File:
  Upload a file to initiate multiple payouts in bulk. This endpoint processes a file containing details for each transaction, supporting efficient batch payouts
• Initiate Payout to Existing Beneficiary
  Create a payout for an existing beneficiary using their unique identifier. This endpoint enables seamless payments to previously registered recipients without re-entering details.
• Initiate Direct Payout
  Make an immediate payout to a specified account without the need for a pre-registered beneficiary. Ideal for one-time payments to new recipients.
• Cancel a Payout
  Cancel a Pending payout before completion. This endpoint allows you to stop a scheduled or pending payment, preventing the transfer from finalizing.
• Get Payout by ID
  Retrieve detailed information for a specific payout using its unique ID. This endpoint provides status, transaction details, and history for individual payout tracking.
• Get Payouts
  Fetch a list of all payouts, with optional filters for date or status of the Payout transaction. This endpoint allows for easy access to payout history and helps track multiple transactions.
• Update Payout Account
  Modify account details for an existing payout before it’s processed. Use this endpoint to change payout account information, ensuring accuracy in transactions.
• Get Payout Document Template
  Download a standardized document template required for bulk or specific types of payouts. This endpoint helps ensure compliance with required formats for file-based payouts.
• Get Payout Configuration
  Retrieve configuration settings for payout operations, including supported currencies, payout limits, and fees.

Please refer to the API documentation for comprehensive instructions and code samples for integrating single and bulk payouts into your application.