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": "jsmith@example.com",
  "bankName": "<string>",
  "accountNumber": "<string>",
  "currency": "<string>",
  "beneficiaryCountryCode": "<string>",
  "beneficiaryAddress": "<string>",
  "beneficiaryCity": "<string>",
  "beneficiaryPostcode": "<string>",
  "beneficiaryCompanyName": "<string>"
}
'

import requests

url = "https://api.royalti.io/integrations/vertofx/beneficiaries"

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "jsmith@example.com",
    "bankName": "<string>",
    "accountNumber": "<string>",
    "currency": "<string>",
    "beneficiaryCountryCode": "<string>",
    "beneficiaryAddress": "<string>",
    "beneficiaryCity": "<string>",
    "beneficiaryPostcode": "<string>",
    "beneficiaryCompanyName": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    email: 'jsmith@example.com',
    bankName: '<string>',
    accountNumber: '<string>',
    currency: '<string>',
    beneficiaryCountryCode: '<string>',
    beneficiaryAddress: '<string>',
    beneficiaryCity: '<string>',
    beneficiaryPostcode: '<string>',
    beneficiaryCompanyName: '<string>'
  })
};

fetch('https://api.royalti.io/integrations/vertofx/beneficiaries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.royalti.io/integrations/vertofx/beneficiaries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'email' => 'jsmith@example.com',
    'bankName' => '<string>',
    'accountNumber' => '<string>',
    'currency' => '<string>',
    'beneficiaryCountryCode' => '<string>',
    'beneficiaryAddress' => '<string>',
    'beneficiaryCity' => '<string>',
    'beneficiaryPostcode' => '<string>',
    'beneficiaryCompanyName' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.royalti.io/integrations/vertofx/beneficiaries"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"bankName\": \"<string>\",\n  \"accountNumber\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"beneficiaryCountryCode\": \"<string>\",\n  \"beneficiaryAddress\": \"<string>\",\n  \"beneficiaryCity\": \"<string>\",\n  \"beneficiaryPostcode\": \"<string>\",\n  \"beneficiaryCompanyName\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.royalti.io/integrations/vertofx/beneficiaries")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"bankName\": \"<string>\",\n  \"accountNumber\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"beneficiaryCountryCode\": \"<string>\",\n  \"beneficiaryAddress\": \"<string>\",\n  \"beneficiaryCity\": \"<string>\",\n  \"beneficiaryPostcode\": \"<string>\",\n  \"beneficiaryCompanyName\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.royalti.io/integrations/vertofx/beneficiaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"bankName\": \"<string>\",\n  \"accountNumber\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"beneficiaryCountryCode\": \"<string>\",\n  \"beneficiaryAddress\": \"<string>\",\n  \"beneficiaryCity\": \"<string>\",\n  \"beneficiaryPostcode\": \"<string>\",\n  \"beneficiaryCompanyName\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Beneficiary created successfully",
  "data": {
    "id": 4755,
    "reference": "RP-12122024-007"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

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": "jsmith@example.com",
  "bankName": "<string>",
  "accountNumber": "<string>",
  "currency": "<string>",
  "beneficiaryCountryCode": "<string>",
  "beneficiaryAddress": "<string>",
  "beneficiaryCity": "<string>",
  "beneficiaryPostcode": "<string>",
  "beneficiaryCompanyName": "<string>"
}
'

import requests

url = "https://api.royalti.io/integrations/vertofx/beneficiaries"

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "jsmith@example.com",
    "bankName": "<string>",
    "accountNumber": "<string>",
    "currency": "<string>",
    "beneficiaryCountryCode": "<string>",
    "beneficiaryAddress": "<string>",
    "beneficiaryCity": "<string>",
    "beneficiaryPostcode": "<string>",
    "beneficiaryCompanyName": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    email: 'jsmith@example.com',
    bankName: '<string>',
    accountNumber: '<string>',
    currency: '<string>',
    beneficiaryCountryCode: '<string>',
    beneficiaryAddress: '<string>',
    beneficiaryCity: '<string>',
    beneficiaryPostcode: '<string>',
    beneficiaryCompanyName: '<string>'
  })
};

fetch('https://api.royalti.io/integrations/vertofx/beneficiaries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.royalti.io/integrations/vertofx/beneficiaries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'email' => 'jsmith@example.com',
    'bankName' => '<string>',
    'accountNumber' => '<string>',
    'currency' => '<string>',
    'beneficiaryCountryCode' => '<string>',
    'beneficiaryAddress' => '<string>',
    'beneficiaryCity' => '<string>',
    'beneficiaryPostcode' => '<string>',
    'beneficiaryCompanyName' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.royalti.io/integrations/vertofx/beneficiaries"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"bankName\": \"<string>\",\n  \"accountNumber\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"beneficiaryCountryCode\": \"<string>\",\n  \"beneficiaryAddress\": \"<string>\",\n  \"beneficiaryCity\": \"<string>\",\n  \"beneficiaryPostcode\": \"<string>\",\n  \"beneficiaryCompanyName\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.royalti.io/integrations/vertofx/beneficiaries")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"bankName\": \"<string>\",\n  \"accountNumber\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"beneficiaryCountryCode\": \"<string>\",\n  \"beneficiaryAddress\": \"<string>\",\n  \"beneficiaryCity\": \"<string>\",\n  \"beneficiaryPostcode\": \"<string>\",\n  \"beneficiaryCompanyName\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.royalti.io/integrations/vertofx/beneficiaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"bankName\": \"<string>\",\n  \"accountNumber\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"beneficiaryCountryCode\": \"<string>\",\n  \"beneficiaryAddress\": \"<string>\",\n  \"beneficiaryCity\": \"<string>\",\n  \"beneficiaryPostcode\": \"<string>\",\n  \"beneficiaryCompanyName\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Beneficiary created successfully",
  "data": {
    "id": 4755,
    "reference": "RP-12122024-007"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

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. Authorization:

Required role: admin or higher

Method: POST Request Payload:

Parameter	Type	Description
firstName	string	First name of the beneficiary
lastName	string	Last name of the beneficiary
email	string	Email address of the beneficiary
bankName	string	Name of the beneficiary’s bank
accountNumber	string	Bank account number
currency	string	Currency code (e.g., USD, EUR, NGN)
beneficiaryCountryCode	string	Country code of the beneficiary
beneficiaryAddress	string	Address of the beneficiary
beneficiaryCity	string	City of the beneficiary
beneficiaryPostcode	string	Postal code of the beneficiary
beneficiaryEntityType	string	Type 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);

import requests

response = requests.post(
  'https://api.royalti.io/integrations/vertofx/beneficiaries',
  headers={
    'Authorization': f'Bearer {token}'
  },
  json={"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"}
)

data = response.json()
print(data)

curl -X POST https://api.royalti.io/integrations/vertofx/beneficiaries \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"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"}'

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

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

​Description

​Code Examples

Authorizations

Body

Response

Description

Code Examples