FX Payout API

The FX Payout API allows you to convert funds from one currency to another and disburse to the recipient's bank account, without needing to hold a balance in the target currency.

This is useful for cross-border payout scenarios where you want to send funds in a supported source currency and have the recipient receive funds in the target currency.

Supported Currency Pairs

The following currency pairs are currently supported:

From	To
XUSD	IDR
USD	IDR
XSGD (coming soon)	IDR
SGD (coming soon)	IDR

Prerequisites

Before initiating an FX payout, you need to create a payout recipient. This recipient represents the beneficiary who will receive the disbursed funds.

Call the Create a payout recipient endpoint with the recipient's bank account details (e.g. bank name, account number, account holder name). The returned recipientId will be used in the payout request.

On behalf of a customer profile: Include the initiator object with mode: onBehalfOf and customerProfileId. The recipient will be created under that customer profile.
Direct user payout: Omit the initiator object. The recipient will be created under your account directly (self mode).

You can also retrieve existing recipients using the Get a list of payout recipients endpoint.

How It Works

The FX Payout flow consists of three steps: get a quote, create a payout, and track the payout status.

Step 1: Request an FX Quote

Call the Create an FX quote endpoint to get a rate for your desired currency pair and amount. You specify the source currency, target currency, the amount, and the tenor (instant).

📘
Note:
Either from.amount or to.amount must be provided in the request, but not both. If to.amount is provided instead of from.amount, the quote is computed in reverse.

Each quote returned has an expiry time. You must execute the quote before it expires.

Step 2: Create a Payout

While the quote is still valid, call the Create a payout endpoint with the quote ID to initiate the FX conversion and payout. You will need to provide:

The payout details including the payout type (fxPayout), recipient ID, FX quote ID, and an optional references (internalReference for your own tracking, externalReference visible to the recipient)
(Optional) The initiator details (mode: onBehalfOf and customerProfileId) to execute the payout on behalf of a customer profile. If omitted, the payout is executed directly under your account (self mode).

Once the payout is created, it will be in pending status while the FX conversion and disbursement are being processed.

Step 3: Track Payout Status

You can track the status of your payout in two ways:

Polling: Call the Get a payout or Get a list of payouts endpoints to check the current status.
Webhooks: Register a callback URL to receive webhook notifications when the payout status changes.
1. cpFxPayoutStatusUpdated — for customer profile payouts
2. userFxPayoutStatusUpdated — for direct user payouts

Transaction Statuses

Status	Description
`pending`	Transaction has been created and is being processed.
`completed`	FX conversion completed successfully. Funds delivered to the recipient.
`failed`	Transaction failed or was cancelled before completion.

The possible status transitions are:

pending → completed
pending → failed

Sandbox Testing

In the sandbox environment, you can manually update a payout's status using the Update payout status (Sandbox) endpoint. This allows you to simulate the completed or cancelled status transitions for testing your integration.

Related API Endpoints

FX Quotes (Foreign Exchange)

Create an FX quote — Request a quote for an FX conversion.
Get an FX quote — Retrieve an existing quote by ID.

Payouts

Create a payout — Execute an FX quote to initiate a cross-border payout.
Get a list of payouts — Retrieve a paginated list of payouts.
Get a payout — Retrieve a single payout by ID.
Update payout status (Sandbox) — Manually update payout status in sandbox.