Creates a new beneficiary. A beneficiary is an individual or business entity that is able to receive a payment.
Introduction
Beneficiary creation is optional when you would like to manage them within Orbital. An approved beneficiary can then be the receiving party when making an outbound payment, simply by providing the beneficiary ID as part of the payment request. You can link your own internal beneficiary record to your Orbital beneficiary by using the beneficiaryReference field.
To meet regulatory obligations, Orbital will screen a beneficiary before allowing it to receive a payment. Approval will be communicated via either the BeneficiaryRejected or BeneficiaryApproved webhooks.
For this release of the Global Payments API, it is mandatory to specify a previously created beneficiary as described in this page when making a payment. In a future release, you will be able to provide full beneficiary details within a payment itself. Orbital will then create a beneficiary automatically and screen it as part of the payment processing flow, or use an existing beneficiary if a match is found. See Payments Overview.
Creating a Beneficiary
High Level Flow
The Orbital flow for creating a beneficiary is in two main parts
- Synchronous processing: Orbital will validate the request. The validation error will be detailed in the HTTP response.
- Asynchronous processing: Orbital will screen the beneficiary and send you a webhook notification to let you know of the status
Specifying the Correct Fields for Accounts and Wallets
When you create a beneficiary, you must ensure that the correct accountDetails fields are being used depending on the bank country and currency. Similarly, crypto wallets require certain fields depending on the blockchain. The tables below summarises the possible scenarios each for fiat and crypto currencies.
Fiat currencies
Bank Country & Currency | Fields to Use | Sample Request |
|---|---|---|
UK domestic, GBP |
| |
IBAN, any currency |
| |
Non-IBAN country, any currency |
| |
US Domestic, USD |
| |
Stablecoins
Cryptocurrency | Fields to use | Sample Request |
|---|---|---|
Stablecoins (USDT, USDC) |
| |
Non-stablecoins (ETH, BTC, LTC, BCH) |
| |
BeneficiaryStatus
The table below summarises various beneficiary status codes, depending on where they are in the creation flow.
| Status | Description | Payments |
|---|---|---|
new | The beneficiary is yet to be reviewed by Orbital. | If a payment is made to a beneficiary with the status of new, those payments will be held and queued until the outcome of our internal screening processes. Those outcomes are approved or rejected status updates below. |
approved | The beneficiary has passed our screening process and any previously held payments will be processed. | Payments are processed immediately for beneficiaries with approved status. Any held payments for beneficiaries that have transitioned from new to approved will be processed. |
rejected | The beneficiary has failed our screening process. Any previously held payments to this beneficiary will be automatically cancelled, and funds returned to your source account. | Payments are rejected for beneficiaries with rejected status. Any held payments for beneficiaries that have transitioned from new to rejected will be cancelled and funds returned to the source account. |
Related Webhook Notifications
Full Sample Request
Below is a full sample of a request to create a beneficiary. Be mindful that fields are conditional depending on bank country and currency. Refer to the sections above for these rules.
{
"accountdetails": {
/*
• Required
• Type of beneficiary. Values: Business | Individual.
*/
"type": "string",
/*
• Required
• Name on account.
*/
"nameOnAccount": "string",
/*
• Required
• Currency for bank account. Together with bankCountry, used to
deterine the structure for account fields.
*/
"currency": "string",
/*
• Required
• ISO alpha-2 code of the bank country. This field is used, together with currency,
to determine required account fields (bic/bankAccount/iban, etc)
*/
"bankCountry": "string",
/*
• Conditional: required for bank accounts that don't use BIC/IBAN
• UK sortcode, US routing number, bank/branch code for other countries requiring this
*/
"bankCode": "string",
/*
• Conditional: required for bank accounts that don't use IBAN
• Account Number for non-IBAN bank accounts
*/
"accountNumber": "string",
/*
• Conditional: required for bank accounts that don't use bankCode.
• BIC/SWIFT code Account Number for non-IBAN bank accounts
*/
"bic": "string",
/*
• Optional
• Intermediary BIC for beneficiaries who this defined
*/
"intermediaryBic": "string",
/*
• Conditional: BIC will also be required.
• IBAN, used by banks within the EU and those who support IBAN
• Maps to pc-beneficiary.accountdetails.iban
*/
"iban": "string",
/*
• Conditional: Required for crypto currencies and stablecoins
• Values: ETH | TRX
• Defines the blockchain network
*/
"blockChain": "string",
/*
• Conditional: Required for crypto currencies and stablecoins
• Defines the crypto wallet address
*/
"walletAddress": "string"
},
"address": {
/*
• Required
• Address line for building number
*/
"buildingNumber": "string",
/*
• Required
• Address line for street
*/
"street": "string",
/*
• Required
• Address line for state or province
*/
"stateOrProvince": "string",
/*
• Required
• Address line for city
*/
"city": "string",
/*
• Required
• Address line for ZIP/Postal code
*/
"zipOrPostalCode": "string",
/*
• Required
• Address line for Country. Must be ISO alpha-2 code
*/
"country": "string"
}
}