Initiate Payout Guide

CROSSFX API · PAYOUTS

Disburse a funded transfer to its beneficiary.

Once funding has succeeded, initiate payout and let CrossFX route the transfer to the beneficiary's bank account or mobile wallet.

The transfer and beneficiary already contain the payout instructions, so no request body is required. CrossFX handles provider selection and returns the payout record for you to track.

No request bodyProvider routingBank payoutMobile money

How payout works

A transfer becomes eligible for payout once its deposit has succeeded and the parent transfer reaches pending_payout.

01

Funding succeeds

Deposit complete

→

02

Transfer ready

pending_payout

→

03

Initiate payout

No request body

→

04

Route payout

Provider + rail

→

05

Track outcome

Read payout status

No request body

Payout data already exists

The transfer and beneficiary already hold the information needed to initiate disbursement.

Provider routing

Handled by CrossFX

CrossFX selects the payout provider for the corridor and rail and handles provider failover for you.

Bank or mobile money

Beneficiary type determines the rail

The saved beneficiary's `type` determines whether funds are sent to a bank account or mobile wallet.

Payout record

Track the result

The response returns the payout record, including its status and amounts.

Before you start

Authentication

Use a valid bearer token

See the Authentication Guide.

Transfer ready for payout

Status must be pending_payout

The transfer's deposit must have succeeded before payout can be initiated.

Initiate the payout

Initiate Payout

Create the payout leg

`POST /api/v1/payments/{cbtx_tracking_id}/payouts`

Open the API Reference for the full request and response schemas and an interactive console.

REQUEST & RESPONSE

Send cbtx_tracking_id in the path.

No request body is required. A successful request creates and returns the payout record.

No payout body to build

By the time the transfer reaches pending_payout, CrossFX already has the beneficiary and transaction instructions required for disbursement.

Transfer+Beneficiary→CrossFX routing→Payout

You do not resubmit beneficiary bank or mobile money details when initiating payout.

Provider and rail selection

CrossFX handles payout routing behind the API.

BENEFICIARY TYPE = BANK

Bank payout rail

CrossFX uses the bank-account details stored on the beneficiary record and selects the appropriate provider for the requested flow.

BENEFICIARY TYPE = MMO

Mobile money rail

CrossFX uses the mobile-wallet details stored on the beneficiary record and routes the payout through the appropriate provider.

PROVIDER ROUTING

You integrate once with CrossFX.

CrossFX selects and fails over between payout providers for the corridor and rail, so your integration does not need to choose a provider in the payout request.

A 201 does not mean the beneficiary was paid

The payout record must still be inspected after the API accepts the request.

IMPORTANT

201 means the payout was created, not that settlement succeeded.

Always read the payout status returned by the endpoint and continue tracking the transaction until its actual outcome is known.

A payout can be accepted by the API and still immediately carry:

status failed

failed_at populated

paid_at null

That response still uses HTTP 201.

API RESULT

Payout record created

HTTP 201 confirms creation of the payout resource.

PAYOUT OUTCOME

Read status

Use the payout record itself to determine whether disbursement has succeeded or failed.

Transfer state requirement

Only a transfer in pending_payout can accept a payout.

DEPOSIT SUCCEEDED→pending_payout→Initiate Payout allowed

Any other transfer state returns 400 BAD_REQUEST.

When you are unsure whether the transfer is ready, read its current state using the Get Transfer Status Guide.

Failed payouts and refunds

A failed payout can cause the parent transfer to enter the refund lifecycle.

PAYOUT

Failed

→

TRANSFER

refunding

→

OUTCOME

refunded

OUTCOME

refund_failed

If payout fails, continue watching the parent transfer state rather than treating the payout record as the end of the lifecycle.

Business rules

REQUEST

No body required

Send only the transfer's cbtx_tracking_id in the endpoint path.

STATE

pending_payout only

Any other parent-transfer state is rejected with 400 BAD_REQUEST.

SUCCESS

201 = created

Inspect the returned payout status. Creation does not prove that the beneficiary was paid.

FAILURE

Watch for refund

A failed payout can move the transfer into refunding, then refunded or refund_failed.

Errors

Every error below returns the CrossFX platform error envelope, with error first and error_id last.

SUPPORT IDENTIFIER

Keep the error_id

Quote the returned error_id when contacting CrossFX support. Include the cbtx_tracking_id of the transfer being paid out.

HTTP	`code`	Trigger	What you do
404	`NOT_FOUND`	No transfer matches the `cbtx_tracking_id`	Use the exact value the quote returned.
400	`BAD_REQUEST`	The transfer is not in a state that can be paid out	Read the transfer status. Only `pending_payout` can be paid out.
404	`NOT_FOUND`	No provider is available for the requested flow, currency and rail	Retry later, and contact support if it persists.
401	—	The `Authorization` header is missing, malformed, or the token has expired	Request a new token and retry. The body is `{ "message": "Unauthorized" }`.

Get Transfer Status Guide

Track the payout

Read the payout ID, inspect the nested payout record and follow the parent transfer through any subsequent state changes.

Sandbox Data & Testing Guide

Test payout outcomes

Use the Sandbox `X-Mock-Lifecycle` values to drive a payout through each supported terminal outcome.

How payout works#

Before you start#

Initiate the payout#

No payout body to build#

Provider and rail selection#

A 201 does not mean the beneficiary was paid#

Transfer state requirement#

Failed payouts and refunds#

Business rules#

Errors#

Related#