Create Beneficiary Guide

CROSSFX API · BENEFICIARIES

Create a recipient once. Reuse them across transfers.

Register a bank account or mobile money recipient, validate their payout details, and receive the beneficiary identifier used throughout the transaction flow.

Beneficiaries are reusable resources. CrossFX validates the payout data and screens the beneficiary before any record is created.

BANKMMOReusableValidatedSanctions screened

How beneficiary creation works

Create the beneficiary before generating a quote. CrossFX validates the submitted payout details, screens the beneficiary identity, then returns the stored resource and its reusable identifier.

01

Choose type

BANK or MMO

→

02

Validate payout data

Country · bank · branch

→

03

Screen identity

Sanctions screening

→

04

Store beneficiary

Receive identifier

→

05

Reuse

Generate quotes

Two payout types

Bank or mobile money

Use `BANK` for bank accounts and `MMO` for mobile wallets.

Reusable resource

Create once

Store the returned beneficiary `identifier` and reuse it across future transfers.

Validated

Reference data is checked

Bank, branch and country values are validated against the CrossFX catalogue before the record is written.

Screened

Before creation

Sanctions screening runs before any beneficiary record exists.

Before you start

Authentication

Use a valid bearer token

See the [Authentication Guide](/authentication-guide-2385173m0).

Supported country

Use a configured country_code

The beneficiary's country must be supported by the platform.

Bank reference data

Required for BANK beneficiaries

Get `bank_code` from the [Fetching Banks List Guide](/fetching-banks-list-guide-2167564m0).

If `branch_details_required` is `true`, also get `branch_code` from the [Fetching Bank Branches Guide](/fetching-bank-branches-guide-2167565m0).

Create a beneficiary

Create Beneficiary

Register a reusable payout recipient

`POST /api/v1/beneficiaries`

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

REQUEST & RESPONSE

Send the recipient's identity together with an account_details object.

The response returns the stored beneficiary, including the identifier used by downstream API calls.

BANK vs MMO

The beneficiary type controls which payout details are required.

TYPE = BANK

Bank account beneficiary

REQUIRED ACCOUNT DETAILS

phone_number
account_number
bank_code

branch_code is conditional. Send it only when the selected bank requires branch details.

TYPE = MMO

Mobile money beneficiary

REQUIRED ACCOUNT DETAIL

phone_number

account_details.phone_number is required for every beneficiary, including both BANK and MMO.

PHONE NUMBER

Use a valid E.164 number.

The phone number must include the dial prefix appropriate for the beneficiary's country_code.

Bank and branch selection

For BANK beneficiaries, use CrossFX reference data rather than deriving or hard-coding payout codes.

01

Select country

country_code

→

02

Fetch banks

Choose bank_code

→

03

Check branch rule

branch_details_required

→

04

Fetch branch

Only if required

→

05

Create beneficiary

Submit exact codes

Bank code

Use the returned code verbatim

`bank_code` must come from the bank catalogue for the beneficiary's own `country_code`.

A valid bank code from another market is rejected.

Branch code

Let the bank decide

The schema does not always require `branch_code`.

If `branch_details_required` is `true`, use a real branch returned for that bank.

If the bank has no branches, sending any branch code is rejected.

Store the beneficiary identifier

The most important value returned after successful creation is identifier.

DOWNSTREAM IDENTIFIER

identifier

Store this value when the beneficiary is created. Generate Quote and downstream calls expect this beneficiary identifier.

Beneficiaries are reusable. Create the recipient once, then quote against the same saved beneficiary as often as needed.

Stored and returned fields

The beneficiary record preserves the submitted recipient data, with two important exceptions.

ROUND-TRIP FIELDS

Returned as submitted

first_name
last_name
email

A create-then-read round trip is faithful for these values.

ACCEPTED, NOT RETURNED

Keep your own copy

entity_type
date_of_birth

The API accepts these fields but does not return them on the stored beneficiary response.

Sanctions screening

Beneficiary screening runs before the record is written.

SCREENING PASSES

Beneficiary is created

The normal create response is returned, including the beneficiary identifier.

SANCTIONS HIT

No beneficiary is created

A high-confidence match returns 422 SANCTIONS_HIT. There is no beneficiary record to roll back or retry against.

For screening behaviour and testing, see the Sanctions Screening documentation. Do not retry the same identity after SANCTIONS_HIT.

Business rules

IDENTIFIER

Store identifier

This is the beneficiary value required by Generate Quote and downstream calls.

PHONE

Required for every type

account_details.phone_number is required for both BANK and MMO.

BRANCH

Let the bank decide

Use branch_details_required to determine whether branch_code should be submitted.

COUNTRY

Bank must match market

bank_code must belong to the beneficiary's country_code.

Errors

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

SUPPORT IDENTIFIER

Keep the error_id

Quote the returned error_id when contacting CrossFX support so the request can be located in platform logs.

HTTP	`code`	Trigger	What you do
422	`VALIDATION_FAILED`	A required field is missing, null, or the wrong type, or an enum value is not allowed	Read `error.json` for the offending field. `type` must be `BANK` or `MMO`, `entity_type` must be `individual` or `entity`.
422	`VALIDATION_FAILED`	The body carries a field the endpoint does not accept	Read `error.json` for the field name and remove it.
422	`VALIDATION_FAILED`	`account_details.phone_number` is not a valid number	Send E.164 with the dial prefix for `country_code`.
422	`VALIDATION_FAILED`	`date_of_birth` is not `YYYY-MM-DD`	Reformat the date.
404	`NOT_FOUND`	`country_code` is not configured	Use a supported country.
400	`BAD_REQUEST`	`bank_code` belongs to a different country than `country_code`	Pick a bank from the beneficiary's own country.
404	`NOT_FOUND`	`bank_code` or `branch_code` is not in the catalogue	Take both from the lookup endpoints.
422	`SANCTIONS_HIT`	Screening returned a high-confidence match	Send to compliance review. Do not retry the same identity.
503	`SCREENING_UNAVAILABLE`	Screening could not be reached	Retry with backoff.
401	—	The `Authorization` header is missing, malformed, or the token has expired	Request a new token and retry. The body is `{ "message": "Unauthorized" }`.

Generate Quote Guide

Use the beneficiary

Generate a quote against the beneficiary `identifier` returned by this endpoint.

Fetching Banks List Guide

Get bank codes

Retrieve the valid `bank_code` values and determine whether a branch is required.

Fetching Bank Branches Guide

Get branch codes

Retrieve a valid `branch_code` for banks whose `branch_details_required` value is `true`.

How beneficiary creation works#

Before you start#

Create a beneficiary#

BANK vs MMO#

Bank and branch selection#

Store the beneficiary identifier#

Stored and returned fields#

Sanctions screening#

Business rules#

Errors#

Related#

How beneficiary creation works

Before you start

Create a beneficiary

BANK vs MMO

Bank and branch selection

Store the beneficiary identifier

Stored and returned fields

Sanctions screening

Business rules

Errors

Related