Create new beneficiary

post

https://api-beneficiary-sandbox.vertofx.com/recipients

Create a new beneficiary account with banking details, address information, and payment preferences

📘
Check your base URL
Each Verto service has its own host. Use the base URL shown in the endpoint definition on this page — do not reuse a host from another service.
Sandbox hosts end in -sandbox.vertofx.com; the matching production host replaces sandbox with beta. Sending a request to the wrong environment returns 403.
See URLs (Sandbox vs Production) for the full service-by-service list.

Bank Code for most markets will be the BIC code of the bank.

For the following markets local bank IDs are accepted, for some markets Verto uses it's own IDs because no local standardised format is in place:

United Kingdom (and FasterPayments zone) - Sort Code
Nigeria, Tanzania and Kenya Verto Codes here. You can also read the guide on Beneficiary Bank Codes

Obtain currencyId from the guide on Currency Codes Mapping

Body Params

Bank beneficiary (non-international). Requires bank details and companyName.
Do not send stablecoin/crypto fields.

Set paymentMode to the payout rail:
LOCAL (domestic bank), MOBILE_MONEY (KES/TZS wallets), or
HK_BANK (CNY paid to a Hong Kong bank).
beneficiaryAddress is required for some currencies (e.g. USD on LOCAL) but not others (e.g. GBP on LOCAL).

currencyId

integer

required

Currency id for this beneficiary. Obtain currencyId from the guide on Currency Codes Mapping.

beneficiaryType

string

enum

required

Allowed:

paymentMode

string

enum

required

How the payout is delivered (non-international). Choose based on the rail:

LOCAL — Domestic bank transfer in the beneficiary's market.
Use a normal bank account number plus the local bank identifier
(sort code, local bank code, or SWIFT/BIC as required for the currency).
Example: GBP Faster Payments (bankCode = sort code, accountNumber = 8-digit account).
MOBILE_MONEY — Mobile-wallet payout (not a bank account).
Available for KES and TZS only.
Put the phone number in accountNumber (e.g. +254-712345678) and the
wallet provider in bankCode / bankName (e.g. M-PESA).
HK_BANK — Pay CNY into a Hong Kong bank account
(bankAddress.countryCode: HK, 3-digit Hong Kong bankCode).
For HKD domestic payouts use LOCAL, not HK_BANK.

Which values a currency accepts is enforced at runtime — see named examples.

Allowed:

companyName

string

required

Company / business name.

accountNumber

string

required

^[0-9a-zA-Z\s\-+./'"]*$

Required for non-stablecoin payment modes.
Allowed characters at schema level: alphanumeric and -+./'".
Exact per-currency / payment-mode format is enforced at runtime
(e.g. TZS/KES MOBILE_MONEY accept +/-; SWIFT_STANDARD allows /).

bankCode

string

required

Bank / rail identifier for the chosen paymentMode:

LOCAL — sort code, local bank code, or SWIFT/BIC (see bank-code notes)
MOBILE_MONEY — wallet provider code (e.g. M-PESA)
HK_BANK — 3-digit Hong Kong bank code (e.g. 004)

bankName

string

required

^.+$

Bank or wallet-provider name matching bankCode
(e.g. bank name for LOCAL / HK_BANK, or M-PESA for mobile money).

bankAddress

object

required

Bank location. Send countryCode (bank country, ISO-2). Other sub-fields are optional.

beneficiaryAddress

object

Optional for most currencies on LOCAL, MOBILE_MONEY, and
HK_BANK payment modes, but required for some (e.g. USD on
LOCAL requires it; GBP on LOCAL does not). Beneficiary
person/company address, not the bank's.

isSelfAccount

boolean | null

Optional. Whether this beneficiary is an account you (the client) own rather than a third party — sets partyType to First_Party when true, Third_Party otherwise. Set true for your own company's accounts (e.g. treasury/OPEX transfers); leave false/omit for third-party payees.

altNationalId

string | null

Optional. A secondary identifier for the beneficiary account where accountNumber/bankCode alone isn't enough — for example a mobile money provider (M-PESA) or an alternate national/bank identifier used in some markets. Not required for any beneficiaryType or currency.

customReferenceLabel

string | null

Optional. Label for your own reconciliation.

nestedType

string | null

enum

Relationship of this beneficiary to your company, when your company
has been approved as a nested/downstream client (company category
financial services or crypto).

Required on every beneficiary you create for as long as your
company is approved for downstream/nested use — not just for some
beneficiaries. Send one of:

OPEX — Your own operational / operating-expense account
NESTED_CUSTOMER — An end-customer of yours
NESTED_PAYEE — A payee of your nested customer

Not applicable (omit, or send null) if your company has not been
approved as a nested/downstream client.

Allowed:

documentDetails

array of objects | null

Optional. Supporting documents for this beneficiary.

Use only after the 3-step upload flow on
Upload beneficiary documents:

POST /uploadDocuments → receive items[].link and items[].key
PUT file bytes to items[].link (expires in 15 minutes)
Send { "key": "<items[].key>", "name": "<fileName>" } here

Omit this field, or send [], unless Verto asks for supporting documents.

documentDetails

copVerification

string | null

Optional. Confirmation of Payee (CoP) / name-check outcome.

Pass this only if you have already called POST /confirm-payee
for this account (mainly UK GBP local payouts) and want that
result stored on the beneficiary. Use the value from the CoP
response (status.detailedStatusIdentifier), for example
MATCH_PERSONAL, CLOSE_MATCH, or NO_ACCOUNT.

Omit if you have not run CoP — create does not require this
field.

Responses

200Successfully created new beneficiary

400Validation failed

401Unauthorized

404Related configuration not found

500Server error