Create Beneficiary
curl --request POST \
--url https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <x-auth-token>' \
--header 'platform: <platform>' \
--header 'uuid: <uuid>' \
--data '
{
"senderCode": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"beneficiaryName": "<string>",
"type": "INDIVIDUAL",
"phone": "<string>",
"address": {}
}
'import requests
url = "https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary"
payload = {
"senderCode": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"beneficiaryName": "<string>",
"type": "INDIVIDUAL",
"phone": "<string>",
"address": {}
}
headers = {
"platform": "<platform>",
"uuid": "<uuid>",
"X-Auth-Token": "<x-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
platform: '<platform>',
uuid: '<uuid>',
'X-Auth-Token': '<x-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
senderCode: '<string>',
firstName: '<string>',
lastName: '<string>',
beneficiaryName: '<string>',
type: 'INDIVIDUAL',
phone: '<string>',
address: {}
})
};
fetch('https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary', 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://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary",
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([
'senderCode' => '<string>',
'firstName' => '<string>',
'lastName' => '<string>',
'beneficiaryName' => '<string>',
'type' => 'INDIVIDUAL',
'phone' => '<string>',
'address' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Auth-Token: <x-auth-token>",
"platform: <platform>",
"uuid: <uuid>"
],
]);
$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://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary"
payload := strings.NewReader("{\n \"senderCode\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"beneficiaryName\": \"<string>\",\n \"type\": \"INDIVIDUAL\",\n \"phone\": \"<string>\",\n \"address\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("platform", "<platform>")
req.Header.Add("uuid", "<uuid>")
req.Header.Add("X-Auth-Token", "<x-auth-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://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary")
.header("platform", "<platform>")
.header("uuid", "<uuid>")
.header("X-Auth-Token", "<x-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"senderCode\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"beneficiaryName\": \"<string>\",\n \"type\": \"INDIVIDUAL\",\n \"phone\": \"<string>\",\n \"address\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["platform"] = '<platform>'
request["uuid"] = '<uuid>'
request["X-Auth-Token"] = '<x-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"senderCode\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"beneficiaryName\": \"<string>\",\n \"type\": \"INDIVIDUAL\",\n \"phone\": \"<string>\",\n \"address\": {}\n}"
response = http.request(request)
puts response.read_bodyAPI Endpoints
Create Beneficiary
Creates a new beneficiary (recipient) profile linked to a sender.
POST
/
usermanagement
/
new-beneficiary
Create Beneficiary
curl --request POST \
--url https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <x-auth-token>' \
--header 'platform: <platform>' \
--header 'uuid: <uuid>' \
--data '
{
"senderCode": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"beneficiaryName": "<string>",
"type": "INDIVIDUAL",
"phone": "<string>",
"address": {}
}
'import requests
url = "https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary"
payload = {
"senderCode": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"beneficiaryName": "<string>",
"type": "INDIVIDUAL",
"phone": "<string>",
"address": {}
}
headers = {
"platform": "<platform>",
"uuid": "<uuid>",
"X-Auth-Token": "<x-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
platform: '<platform>',
uuid: '<uuid>',
'X-Auth-Token': '<x-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
senderCode: '<string>',
firstName: '<string>',
lastName: '<string>',
beneficiaryName: '<string>',
type: 'INDIVIDUAL',
phone: '<string>',
address: {}
})
};
fetch('https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary', 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://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary",
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([
'senderCode' => '<string>',
'firstName' => '<string>',
'lastName' => '<string>',
'beneficiaryName' => '<string>',
'type' => 'INDIVIDUAL',
'phone' => '<string>',
'address' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Auth-Token: <x-auth-token>",
"platform: <platform>",
"uuid: <uuid>"
],
]);
$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://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary"
payload := strings.NewReader("{\n \"senderCode\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"beneficiaryName\": \"<string>\",\n \"type\": \"INDIVIDUAL\",\n \"phone\": \"<string>\",\n \"address\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("platform", "<platform>")
req.Header.Add("uuid", "<uuid>")
req.Header.Add("X-Auth-Token", "<x-auth-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://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary")
.header("platform", "<platform>")
.header("uuid", "<uuid>")
.header("X-Auth-Token", "<x-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"senderCode\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"beneficiaryName\": \"<string>\",\n \"type\": \"INDIVIDUAL\",\n \"phone\": \"<string>\",\n \"address\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["platform"] = '<platform>'
request["uuid"] = '<uuid>'
request["X-Auth-Token"] = '<x-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"senderCode\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"beneficiaryName\": \"<string>\",\n \"type\": \"INDIVIDUAL\",\n \"phone\": \"<string>\",\n \"address\": {}\n}"
response = http.request(request)
puts response.read_bodyCreates a new beneficiary profile. For bank transfers, call this after validating the account with Validate Recipient Account. Once created, add bank account details with Add Bank Details.
Requires an authenticated
REGISTERED_CUSTOMER, MANAGER, or AGENTS token.
Request Headers
string
required
JWT Access Token of the authenticated user.
string
default:"fincode"
required
Platform identifier. Use
fincode.string
default:"200"
required
Unique request identifier.
Request Body
string
required
The customer code of the sender this beneficiary belongs to (e.g.
VJJGVE).string
required
Beneficiary first name.
string
Beneficiary last name.
string
Beneficiary middle name.
string
required
Customer type:
INDIVIDUAL or COMPANY.string
Beneficiary email address.
string
Beneficiary phone number.
string
Date of birth in ISO format (e.g.
1990-05-15T00:00:00+01:00).string
Company name — required when
type is COMPANY.string
Company registration number — for
COMPANY type.string
Sender’s relationship to the beneficiary (e.g.
SPOUSE, PARENT, FRIEND).object
object
Additional dynamic fields specific to your configuration. Pass an empty object
{} if not applicable.Code Example
cURL
curl -X POST 'https://{your-domain}.fincode.software/api/v6/services/usermanagement/new-beneficiary' \
--header 'X-Auth-Token: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--header 'platform: fincode' \
--header 'uuid: 200' \
--data '{
"senderCode": "VJJGVE",
"firstName": "Ada",
"lastName": "Okonkwo",
"type": "INDIVIDUAL",
"email": "ada.okonkwo@example.com",
"phone": "+2348012345678",
"dob": "1988-03-22T00:00:00+01:00",
"relationShip": "FRIEND",
"address": {
"address1": "12 Victoria Island",
"countryIso3": "NGA",
"postcode": "101241"
},
"dynamicFields": {}
}'
Headers
Body
application/json
Response
200
Beneficiary created