v1.5.0 - Cross-Border FX Payouts and API Enhancements
Overview
This release introduces the FX Payout API for cross-border payouts, along with new attributes for user withdrawals and customer profiles, and documentation improvements.
FX Payout API
We're excited to introduce the FX Payout API — our first cross-border payout capability. You can now convert funds and disburse directly to the recipient's bank account in a single API flow, without needing to hold a balance in the target currency.
Supported currency pairs:
- XUSD → IDR
- USD → IDR
- XSGD → IDR (coming soon)
- SGD → IDR (coming soon)
Key capabilities:
- Request and retrieve real-time FX conversion quotes.
- Execute a quote and initiate a cross-border payout in a single flow.
- Track payout status via polling or webhooks (
cpFxPayoutStatusUpdated/userFxPayoutStatusUpdated). - Sandbox support: manually update payout status to
completedorcancelledfor integration testing.
New API endpoints:
- Create an FX quote — Request a quote for an FX conversion.
- Get an FX quote — Retrieve an existing quote by ID.
- Create a payout — Execute a FX quote to initiate a cross-border payout.
- Get a payout — Retrieve a single payout by ID.
- Get a list of payouts — Retrieve a paginated list of payouts.
- Update payout status (Sandbox) — Simulate payout status transitions in sandbox.
New guide:
- Guides > Integration Model > FX Payout API
- Step-by-step integration guide covering the end-to-end FX payout flow, supported currency pairs, prerequisites, and transaction statuses.
API Enhancements
1. Transaction Remarks for User Withdrawal
You can now include a transactionRemarks field when creating a user withdrawal. This allows you to attach an external reference that will be visible to the recipient.
Affected endpoints:
- Create a user withdrawal (request + response)
- Get a user withdrawal (response)
- Callback for Dashboard Withdrawal Status Update
Field | Type | Description |
|---|---|---|
| string (optional) | External transaction reference which will be seen by the recipient.
|
2. Trading Name for Business Customer Profiles
You can now provide a tradingName when creating or updating a business customer profile. If your business operates under a brand name that differs from the legal entity name, this field allows you to specify it. When provided, the trading name will be used for PayNow registration.
Affected endpoints:
- Create a business customer profile (request + response)
- Create a business customer profile+ (request + response)
- Get a customer profile (response, business only)
- Get a customer profile+ (response, business only)
- Update a business customer profile (request + response)
- Customer Profile Verification Status Update Webhook (business only)
Field | Type | Description |
|---|---|---|
| string (optional) | The brand or trading name of the business, if different from the legal entity name ( Note: If provided, this name will be used for PayNow registration instead of the legal entity name. If absent, the PayNow registration falls back to |
3. SWIFT Code in Supported Banks
The Get a list of supported banks API now returns the swift_code for each bank, making it easier to look up SWIFT/BIC codes when setting up payout recipients or bank accounts.
| Field | Type | Description |
|---|---|---|
swift_code | string | Bank's SWIFT/BIC code. |
Documentation Updates
1. Transaction Status Guide
- Updated the Transaction Status guide to include blockchain activity statuses for blockchain deposit and withdrawal transactions.
- Added explanation for the
expiredpayment status.