Skip to main content
POST
/
integrations
/
vertofx
/
beneficiaries
Create Beneficiary
curl --request POST \
  --url https://api.royalti.io/integrations/vertofx/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "[email protected]",
  "bankName": "<string>",
  "accountNumber": "<string>",
  "currency": "<string>",
  "beneficiaryCountryCode": "<string>",
  "beneficiaryAddress": "<string>",
  "beneficiaryCity": "<string>",
  "beneficiaryEntityType": "individual",
  "beneficiaryPostcode": "<string>",
  "beneficiaryCompanyName": "<string>"
}
'
{
  "success": true,
  "message": "Beneficiary created successfully",
  "data": {
    "id": 4755,
    "reference": "RP-12122024-007"
  }
}
This endpoint requires authentication. Include your Bearer token in the Authorization header.

​
Description

Description:
The /integrations/vertofx/beneficiaries endpoint allows creation of new beneficiaries in the VertoFX system. Method: POST Request Payload:
ParameterTypeDescription
firstNamestringFirst name of the beneficiary
lastNamestringLast name of the beneficiary
emailstringEmail address of the beneficiary
bankNamestringName of the beneficiary’s bank
accountNumberstringBank account number
currencystringCurrency code (e.g., USD, EUR, NGN)
beneficiaryCountryCodestringCountry code of the beneficiary
beneficiaryAddressstringAddress of the beneficiary
beneficiaryCitystringCity of the beneficiary
beneficiaryPostcodestringPostal code of the beneficiary
beneficiaryEntityTypestringType of entity (individual, company)

​
Code Examples

const response = await fetch('https://api.royalti.io/integrations/vertofx/beneficiaries', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "firstName": "sample-firstName",
    "lastName": "sample-lastName",
    "email": "sample-email",
    "bankName": "sample-bankName",
    "accountNumber": "sample-accountNumber",
    "currency": "sample-currency",
    "beneficiaryCountryCode": "sample-beneficiaryCountryCode",
    "beneficiaryAddress": "sample-beneficiaryAddress",
    "beneficiaryCity": "sample-beneficiaryCity",
    "beneficiaryPostcode": "sample-beneficiaryPostcode",
    "beneficiaryEntityType": "sample-beneficiaryEntityType",
    "beneficiaryCompanyName": "sample-beneficiaryCompanyName"
  })
});

const data = await response.json();
console.log(data);

Authorizations

​
Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Body

application/json
​
firstName
string
required

First name of the beneficiary

​
lastName
string
required

Last name of the beneficiary

​
email
string<email>
required

Email address of the beneficiary

​
bankName
string
required

Name of the beneficiary's bank

​
accountNumber
string
required

Bank account number

​
currency
string
required

Currency code (e.g., USD, EUR, NGN)

​
beneficiaryCountryCode
string
required

Country code of the beneficiary

​
beneficiaryAddress
string
required

Address of the beneficiary

​
beneficiaryCity
string
required

City of the beneficiary

​
beneficiaryEntityType
enum<string>
required

Type of entity

Available options:
individual,
company
​
beneficiaryPostcode
string

Postal code of the beneficiary

​
beneficiaryCompanyName
string

Company name (if entity type is company)

Response

Success

​
success
boolean
​
data
object
​
message
string