/api/v1/beneficiaries/addBeneficiary

Save a recipient

curl --request POST \
  --url https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-signature: <x-signature>' \
  --header 'x-timestamp: <x-timestamp>' \
  --data '
{
  "country_code": "NG",
  "currency_code": "NGN",
  "payment_method": "bank_local",
  "recipient_details": {},
  "nickname": "<string>",
  "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary"

payload = {
    "country_code": "NG",
    "currency_code": "NGN",
    "payment_method": "bank_local",
    "recipient_details": {},
    "nickname": "<string>",
    "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "x-timestamp": "<x-timestamp>",
    "x-signature": "<x-signature>",
    "x-api-key": "<api-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-timestamp': '<x-timestamp>',
    'x-signature': '<x-signature>',
    'x-api-key': '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    country_code: 'NG',
    currency_code: 'NGN',
    payment_method: 'bank_local',
    recipient_details: {},
    nickname: '<string>',
    idempotency_key: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary', 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.pontisglobe.com/api/v1/beneficiaries/addBeneficiary",
  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([
    'country_code' => 'NG',
    'currency_code' => 'NGN',
    'payment_method' => 'bank_local',
    'recipient_details' => [
        
    ],
    'nickname' => '<string>',
    'idempotency_key' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-api-key: <api-key>",
    "x-signature: <x-signature>",
    "x-timestamp: <x-timestamp>"
  ],
]);

$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.pontisglobe.com/api/v1/beneficiaries/addBeneficiary"

	payload := strings.NewReader("{\n  \"country_code\": \"NG\",\n  \"currency_code\": \"NGN\",\n  \"payment_method\": \"bank_local\",\n  \"recipient_details\": {},\n  \"nickname\": \"<string>\",\n  \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

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

	req.Header.Add("x-timestamp", "<x-timestamp>")
	req.Header.Add("x-signature", "<x-signature>")
	req.Header.Add("x-api-key", "<api-key>")
	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.pontisglobe.com/api/v1/beneficiaries/addBeneficiary")
  .header("x-timestamp", "<x-timestamp>")
  .header("x-signature", "<x-signature>")
  .header("x-api-key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_code\": \"NG\",\n  \"currency_code\": \"NGN\",\n  \"payment_method\": \"bank_local\",\n  \"recipient_details\": {},\n  \"nickname\": \"<string>\",\n  \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary")

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

request = Net::HTTP::Post.new(url)
request["x-timestamp"] = '<x-timestamp>'
request["x-signature"] = '<x-signature>'
request["x-api-key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_code\": \"NG\",\n  \"currency_code\": \"NGN\",\n  \"payment_method\": \"bank_local\",\n  \"recipient_details\": {},\n  \"nickname\": \"<string>\",\n  \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

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

{
  "ok": true,
  "data": {
    "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "active"
  }
}

{
  "ok": true,
  "data": {
    "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "active"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

POST

api

beneficiaries

addBeneficiary

Save a recipient

curl --request POST \
  --url https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-signature: <x-signature>' \
  --header 'x-timestamp: <x-timestamp>' \
  --data '
{
  "country_code": "NG",
  "currency_code": "NGN",
  "payment_method": "bank_local",
  "recipient_details": {},
  "nickname": "<string>",
  "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary"

payload = {
    "country_code": "NG",
    "currency_code": "NGN",
    "payment_method": "bank_local",
    "recipient_details": {},
    "nickname": "<string>",
    "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "x-timestamp": "<x-timestamp>",
    "x-signature": "<x-signature>",
    "x-api-key": "<api-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-timestamp': '<x-timestamp>',
    'x-signature': '<x-signature>',
    'x-api-key': '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    country_code: 'NG',
    currency_code: 'NGN',
    payment_method: 'bank_local',
    recipient_details: {},
    nickname: '<string>',
    idempotency_key: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary', 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.pontisglobe.com/api/v1/beneficiaries/addBeneficiary",
  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([
    'country_code' => 'NG',
    'currency_code' => 'NGN',
    'payment_method' => 'bank_local',
    'recipient_details' => [
        
    ],
    'nickname' => '<string>',
    'idempotency_key' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-api-key: <api-key>",
    "x-signature: <x-signature>",
    "x-timestamp: <x-timestamp>"
  ],
]);

$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.pontisglobe.com/api/v1/beneficiaries/addBeneficiary"

	payload := strings.NewReader("{\n  \"country_code\": \"NG\",\n  \"currency_code\": \"NGN\",\n  \"payment_method\": \"bank_local\",\n  \"recipient_details\": {},\n  \"nickname\": \"<string>\",\n  \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

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

	req.Header.Add("x-timestamp", "<x-timestamp>")
	req.Header.Add("x-signature", "<x-signature>")
	req.Header.Add("x-api-key", "<api-key>")
	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.pontisglobe.com/api/v1/beneficiaries/addBeneficiary")
  .header("x-timestamp", "<x-timestamp>")
  .header("x-signature", "<x-signature>")
  .header("x-api-key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_code\": \"NG\",\n  \"currency_code\": \"NGN\",\n  \"payment_method\": \"bank_local\",\n  \"recipient_details\": {},\n  \"nickname\": \"<string>\",\n  \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary")

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

request = Net::HTTP::Post.new(url)
request["x-timestamp"] = '<x-timestamp>'
request["x-signature"] = '<x-signature>'
request["x-api-key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_code\": \"NG\",\n  \"currency_code\": \"NGN\",\n  \"payment_method\": \"bank_local\",\n  \"recipient_details\": {},\n  \"nickname\": \"<string>\",\n  \"idempotency_key\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

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

{
  "ok": true,
  "data": {
    "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "active"
  }
}

{
  "ok": true,
  "data": {
    "beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "active"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

Creates a saved recipient for one corridor (country_code + currency_code). Pass the returned beneficiary_id to sendPayoutRequest instead of repeating the full recipient details on every payout. See Beneficiaries for how the flow fits together.

The fields above are what you encrypt, not what goes on the wire. The body is always { "data": "<aes-256-gcm ciphertext>" } — see Authentication.

A JWT is required, same as every payout endpoint — beneficiaries are part of the payout product. Log in first via /api/v1/user/login.

Every corridor requires recipient_details.name. The remaining fields differ per destination and are validated at create time, not at payout time — which is the point of saving a beneficiary. See corridor requirements.

Idempotency

Reusing an idempotency_key — or posting identical details — returns the beneficiary that already exists rather than creating a duplicate. A retry after a network timeout is safe. The status code is how you tell the two apart: 201 means you just created it, 200 means you are getting the existing one back.

Example request

const res = await call(
  '/api/v1/beneficiaries/addBeneficiary',
  {
    country_code: 'NG',
    currency_code: 'NGN',
    payment_method: 'bank_local',
    nickname: 'Payroll — Ada',
    recipient_details: {
      name: 'Ada Okafor',
      account_number: '0123456789',
      branch_code: '058',
    },
  },
  jwt,
)

const { beneficiary_id } = res.data

status, body = call('/api/v1/beneficiaries/addBeneficiary', {
    'country_code': 'NG',
    'currency_code': 'NGN',
    'payment_method': 'bank_local',
    'nickname': 'Payroll — Ada',
    'recipient_details': {
        'name': 'Ada Okafor',
        'account_number': '0123456789',
        'branch_code': '058',
    },
}, jwt)

beneficiary_id = body['data']['beneficiary_id']

curl -X POST "https://api.pontisglobe.com/api/v1/beneficiaries/addBeneficiary" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-timestamp: 1748023400" \
  -H "x-signature: 2f8a9b…" \
  -H "authorization: Bearer eyJhbGciOi…" \
  -d '{"data":"<encrypted blob>"}'

Errors

Status	Code	Meaning
400	`validation_error`	A field failed validation — the message names it
400	`bad_request`	Bad envelope: missing or skewed `x-timestamp`, or a body we could not decrypt
401	`unauthorized`	Missing or invalid API key, signature or JWT
403	`forbidden`	Your IP is not allow-listed, or your account does not hold the payout product
429	`rate_limited`	Too many requests — back off and retry

See Errors for the envelope shape shared by every endpoint.

Authorizations

x-api-key

string

header

required

Identifies your account. Issued from Developer Tools in the dashboard.

Authorization

string

header

required

Short-lived token from /api/v1/user/login, bound to your account and mode. Expires in 900 seconds.

Headers

x-timestamp

integer<int64>

required

Unix epoch in seconds — not milliseconds. Must be within ±5 minutes of our clock, which is what makes a captured request unusable later. Keep your client's clock NTP-synced.

Example:

1748023400

x-signature

string

required

HMAC-SHA256 over the signing string, hex encoded. The timestamp is part of what is signed, so a replayed body cannot be re-dated. See https://docs.pontisglobe.com/authentication for how it is built.

Example:

"2f8a9b4c1d7e0a3f6b8c2d5e9f1a4b7c0d3e6f9a2b5c8d1e4f7a0b3c6d9e2f5a"

Body

application/json

country_code

string

required

Required string length: 2

Example:

"NG"

currency_code

string

required

Required string length: 2 - 8

Example:

"NGN"

payment_method

string

required

Required string length: 1 - 32

Example:

"bank_local"

recipient_details

object

required

Per-corridor fields, plus name. Mobile-money corridors carry their network here as payment_network — unlike a payout, it is not a top-level field on this endpoint, and one sent at the top level is stripped rather than saved.

nickname

string

Maximum string length: 80

idempotency_key

string<uuid>

Response

Already existed — the same beneficiary, returned again.

enum<boolean>

Available options:

true

data

object

Show child attributes

​Idempotency

​Example request

​Errors

Authorizations

Headers

Body

Response

Idempotency

Example request

Errors