Skip to main content
POST
/
integrations
/
vertofx
/
beneficiaries
Create Beneficiary
curl --request POST \
  --url https://server26-dot-royalti-project.uc.r.appspot.com/integrations/vertofx/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "jsmith@example.com",
  "bankName": "<string>",
  "accountNumber": "<string>",
  "currency": "<string>",
  "beneficiaryCountryCode": "<string>",
  "beneficiaryAddress": "<string>",
  "beneficiaryCity": "<string>",
  "beneficiaryPostcode": "<string>",
  "beneficiaryEntityType": "individual",
  "beneficiaryCompanyName": "<string>"
}'
{
  "success": true,
  "message": "Beneficiary created successfully",
  "data": {
    "id": 4755,
    "reference": "RP-12122024-007"
  }
}
Create VertoFX Beneficiary 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)

Authentication

This endpoint requires authentication. Include your bearer token in the Authorization header.

Request Body

Request Schema

FieldTypeRequiredDescription
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
beneficiaryCompanyNamestringCompany name (if entity type is company)

Responses

✅ 201 - Success

⚠️ 400 - Bad Request

⚠️ 401 - Unauthorized

❌ 500 - Internal Server Error

Tags

VertoFx

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
I