Skip to main content
POST
Customer beneficiary
Adds a new fiat beneficiary for a payment channel/currency.

Authorizations

x-api-key
string
header
required

Requires authentication via API key and HMAC signature.

  • x-api-key: Your API key generated from your Onboard Business dashboard.
  • x-timestamp: Unix epoch timestamp (seconds) used in signature, allowed skew is 30 seconds
  • x-signature: SHA256 HMAC HEX signature calculated over t={x-timestamp}&{requestBody} using your API Secret.

Body

application/json

create beneficiary for customer

bankCode
string
required

Beneficiary bank code

Required string length: 3 - 12
accountNumber
string
required

Beneficiary account number, for international payments like SEPA, this is the IBAN, and for Mobile Money, this is the phone number.

accountName
string
required

Beneficiary account name

currency
string
required
beneficiaryType
string
required

Discriminator value for beneficiary type. Possible values are:

  • CreateLocalBankAccountBeneficiary: Local bank transfer beneficiary, maps to BeneficiaryLocalBankAccount
  • CreateSepaBankAccountBeneficiary: SEPA instant and standard transfer beneficiary. Use this for beneficiaries that will receive SEPA payments. Maps to BeneficiarySepaBankAccount
  • CreateACHBankAccountBeneficiary: ACH, FedWire and FedNow transfer beneficiary. Maps to BeneficiaryACHBankAccount
  • CreateSwiftBankAccountBeneficiary: SWIFT transfer beneficiary. Maps to BeneficiarySwiftBankAccount
  • CreateMobileWalletAccountBeneficiary: Use this for beneficiaries that will receive mobile wallet payments. Maps to BeneficiaryMobileWalletAccount.
Pattern: ^Create(LocalBank|SepaBank|ACHBank|SwiftBank|MobileWallet)AccountBeneficiary$
accountHolderType
enum<string>
required
Available options:
INDIVIDUAL,
BUSINESS
paymentChannelId
string
required

To get the payment channels available, call the /currencies endpoint. The payment channel ID to be used for transfer to this beneficiary. The payment channel ID and the beneficiaryType are mutually exclusive. For example BANK_TRANSFER_NIGERIA uses CreateLocalBankAccountBeneficiary

bankName
string

Beneficiary bank name

bankAddress
object
isThirdParty
boolean
default:false

Flag to indicate if the beneficiary is a third party

Response

Beneficiary details saved successfully

Fiat beneficiary object

bankCode
string
required

Beneficiary bank code

Required string length: 3 - 12
id
string<uuid>
required

Beneficiary identifier

accountNumber
string
required

Beneficiary account number, for international payments like SEPA, this is the IBAN

accountName
string
required

Beneficiary account name

currency
string
required
accountHolderType
enum<string>
required
Available options:
INDIVIDUAL,
BUSINESS
bankName
string

Beneficiary bank name

bankAddress
object
beneficiaryType
string

Discriminator value for beneficiary type. Allowed values include:

  • BeneficiaryLocalBankAccount
  • BeneficiarySepaBankAccount
  • BeneficiaryACHBankAccount
  • BeneficiarySwiftBankAccount
  • BeneficiaryMobileWalletAccount
isThirdParty
boolean
default:false

Flag to indicate if the beneficiary is a third party