Update a beneficiary
curl --request POST \
--url https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary \
--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 '
{
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"recipient_details": {},
"nickname": "<string>"
}
'import requests
url = "https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary"
payload = {
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"recipient_details": {},
"nickname": "<string>"
}
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({
beneficiary_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
recipient_details: {},
nickname: '<string>'
})
};
fetch('https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary', 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/updateBeneficiary",
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([
'beneficiary_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'recipient_details' => [
],
'nickname' => '<string>'
]),
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/updateBeneficiary"
payload := strings.NewReader("{\n \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"recipient_details\": {},\n \"nickname\": \"<string>\"\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/updateBeneficiary")
.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 \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"recipient_details\": {},\n \"nickname\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary")
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 \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"recipient_details\": {},\n \"nickname\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"ok": true,
"data": {
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "active",
"country_code": "NG",
"currency_code": "NGN",
"payment_method": "bank_local",
"recipient_name": "<string>",
"recipient_details": {},
"created_at": "2023-11-07T05:31:56Z",
"payment_network": "<string>",
"nickname": "<string>",
"last_used_at": "2023-11-07T05:31:56Z"
}
}{
"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"
}
}{
"ok": false,
"request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
"error": {
"code": "insufficient_funds",
"message": "Insufficient available balance. Available: 5.00 USDT"
}
}Payouts
/api/v1/beneficiaries/updateBeneficiary
Change a saved recipient’s details or nickname.
POST
/
api
/
v1
/
beneficiaries
/
updateBeneficiary
Update a beneficiary
curl --request POST \
--url https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary \
--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 '
{
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"recipient_details": {},
"nickname": "<string>"
}
'import requests
url = "https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary"
payload = {
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"recipient_details": {},
"nickname": "<string>"
}
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({
beneficiary_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
recipient_details: {},
nickname: '<string>'
})
};
fetch('https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary', 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/updateBeneficiary",
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([
'beneficiary_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'recipient_details' => [
],
'nickname' => '<string>'
]),
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/updateBeneficiary"
payload := strings.NewReader("{\n \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"recipient_details\": {},\n \"nickname\": \"<string>\"\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/updateBeneficiary")
.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 \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"recipient_details\": {},\n \"nickname\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary")
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 \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"recipient_details\": {},\n \"nickname\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"ok": true,
"data": {
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "active",
"country_code": "NG",
"currency_code": "NGN",
"payment_method": "bank_local",
"recipient_name": "<string>",
"recipient_details": {},
"created_at": "2023-11-07T05:31:56Z",
"payment_network": "<string>",
"nickname": "<string>",
"last_used_at": "2023-11-07T05:31:56Z"
}
}{
"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"
}
}{
"ok": false,
"request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
"error": {
"code": "insufficient_funds",
"message": "Insufficient available balance. Available: 5.00 USDT"
}
}The fields above are what you encrypt, not what goes on the wire. The body is always
{ "data": "<aes-256-gcm ciphertext>" } — see Authentication.Send at least one of
recipient_details or nickname — a body carrying neither is rejected
with validation_error.recipient_details is replaced, not merged
The object you send becomes the whole set of corridor fields, and it is revalidated against the corridor before it is saved.Because reads come back masked, you cannot fetch a beneficiary and send its
recipient_details straight back — the masked account number would be saved as the real one.
Build the replacement from your own records.beneficiary_invalid means the details no longer satisfy the corridor’s requirements, usually
because the corridor’s requirements changed after the record was first saved.
Payouts already in flight are unaffected
A payout snapshots the recipient details at the moment it is created, so editing a beneficiary never alters a payment that is already on its way.Example request
The snippets assume you have already encrypted the body and signed the request — see the
Quickstart for the full helper in Node and Python.
const updated = await call(
'/api/v1/beneficiaries/updateBeneficiary',
{
beneficiary_id: 'b7c1e2a4-9d3e-4a71-b6c8-5e2f0a7d1934',
recipient_details: {
name: 'Ada Okafor',
account_number: '0123456789',
branch_code: '058',
},
nickname: 'Payroll — Ada',
},
jwt,
)
status, body = call('/api/v1/beneficiaries/updateBeneficiary', {
'beneficiary_id': 'b7c1e2a4-9d3e-4a71-b6c8-5e2f0a7d1934',
'recipient_details': {
'name': 'Ada Okafor',
'account_number': '0123456789',
'branch_code': '058',
},
'nickname': 'Payroll — Ada',
}, jwt)
curl -X POST "https://api.pontisglobe.com/api/v1/beneficiaries/updateBeneficiary" \
-H "content-type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1748023400" \
-H "x-signature: 2f8a9b…" \
-H "authorization: Bearer YOUR_JWT" \
-d '{"data":"<encrypted blob>"}'
Authorizations
Identifies your account. Issued from Developer Tools in the dashboard.
Short-lived token from /api/v1/user/login, bound to your account and
mode. Expires in 900 seconds.
Headers
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
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
⌘I