Create a beneficiary

post

https://sandbox-api.oneliquidity.technology/fcat/v1/beneficiary

Creates an individual or business beneficiary for future bank transfers. New beneficiaries begin in PENDING status and must be approved before they can receive a transfer.

For Nigerian accounts, use the current four-character bank code returned by List payout banks. Creating the same beneficiary more than once returns a validation error.

Body Params

Individual or business beneficiary to create.

alias

string

required

The alias to identify this beneficiary

accountBank

string

required

Bank code. For Nigerian accounts, use the four-character code returned by the payout-bank list.

accountNumber

string

The beneficiary's account number. Required when country is NG, or when ibanNumber is not provided.

swiftCode

string

The beneficiary's bank swift code. Required when country is not NG and ibanNumber is not provided.

routingNumber

string

Bank routing number (optional).

country

string

enum

required

The beneficiary's country code (e.g., "NG" for Nigeria).

beneficiaryType

string

enum

required

Identifies a business beneficiary.

Allowed:

paymentBeneficiaryType

string

enum

required

Whether the beneficiary owns the receiving account or is a third party.

Allowed:

companyName

string

required

The name of the beneficiary's company (applicable for business beneficiarys).

registrationNumber

string

The registration number of the beneficiary's business (applicable for business beneficiary).

registrationDate

date

The registration date of the beneficiary's business (applicable for business beneficiary).

state

string

The state where the beneficiary is located.

city

string

The city where the beneficiary is located.

tin

string

The beneficiary's tax identification number.

businessType

string

enum

Required for Nigerian businesses (country = NG).

Allowed:

relationship

string

required

The nature of the relationship with the beneficiary (e.g., "trade").

address

string

required

The beneficiary's address.

ibanNumber

string

International Bank Account Number

currency

string

enum

The bank account currency. Required when country is not NG.

postalCode

string

^\d{5}$

Required for Kenyan businesses (country = KE). Must be exactly 5 digits.

Responses

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Beneficiary created and awaiting review.

400Status 400 Response

401Status 401 Response

403Status 403 Response

500Status 500 Response