curl --request POST \
--url https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"kind": "person",
"currency": "NGN",
"scheme": "ng_nip",
"holder_name": "Ada Okoye",
"routing": {
"bank_code": "058",
"account_number": "0123456789"
}
}
'const url = 'https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
kind: 'person',
currency: 'NGN',
scheme: 'ng_nip',
holder_name: 'Ada Okoye',
routing: {bank_code: '058', account_number: '0123456789'}
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));import requests
url = "https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries"
payload = {
"kind": "person",
"currency": "NGN",
"scheme": "ng_nip",
"holder_name": "Ada Okoye",
"routing": {
"bank_code": "058",
"account_number": "0123456789"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries"
payload := strings.NewReader("{\n \"kind\": \"person\",\n \"currency\": \"NGN\",\n \"scheme\": \"ng_nip\",\n \"holder_name\": \"Ada Okoye\",\n \"routing\": {\n \"bank_code\": \"058\",\n \"account_number\": \"0123456789\"\n }\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))
}{
"object": "beneficiary",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "person",
"name": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"business_name": "<string>",
"nickname": "<string>",
"email": "<string>",
"relationship": "<string>",
"address": {
"line_1": "<string>",
"line_2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"currency": "<string>",
"country": "<string>",
"method": "<string>",
"scheme": "<string>",
"scheme_label": "<string>",
"settlement": "<string>",
"holder_name": "<string>",
"routing": {},
"route_label": "<string>",
"status": "<string>",
"missing_fields": [
"<string>"
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"archived_at": "2023-11-07T05:31:56Z",
"livemode": true,
"environment": "live"
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}Create Beneficiary
Save a payout recipient. Scheme and routing keys must match a corridor
from GET /corridors. Emits event.beneficiary.created.
curl --request POST \
--url https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"kind": "person",
"currency": "NGN",
"scheme": "ng_nip",
"holder_name": "Ada Okoye",
"routing": {
"bank_code": "058",
"account_number": "0123456789"
}
}
'const url = 'https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
kind: 'person',
currency: 'NGN',
scheme: 'ng_nip',
holder_name: 'Ada Okoye',
routing: {bank_code: '058', account_number: '0123456789'}
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));import requests
url = "https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries"
payload = {
"kind": "person",
"currency": "NGN",
"scheme": "ng_nip",
"holder_name": "Ada Okoye",
"routing": {
"bank_code": "058",
"account_number": "0123456789"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries"
payload := strings.NewReader("{\n \"kind\": \"person\",\n \"currency\": \"NGN\",\n \"scheme\": \"ng_nip\",\n \"holder_name\": \"Ada Okoye\",\n \"routing\": {\n \"bank_code\": \"058\",\n \"account_number\": \"0123456789\"\n }\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))
}{
"object": "beneficiary",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "person",
"name": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"business_name": "<string>",
"nickname": "<string>",
"email": "<string>",
"relationship": "<string>",
"address": {
"line_1": "<string>",
"line_2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>"
},
"currency": "<string>",
"country": "<string>",
"method": "<string>",
"scheme": "<string>",
"scheme_label": "<string>",
"settlement": "<string>",
"holder_name": "<string>",
"routing": {},
"route_label": "<string>",
"status": "<string>",
"missing_fields": [
"<string>"
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"archived_at": "2023-11-07T05:31:56Z",
"livemode": true,
"environment": "live"
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}Authorizations
Secret API key from Settings → Developers → API keys.
Example: Authorization: Bearer sk_test_…
Body
Recipient type. Use person with first/last name, or business with business_name.
person, business "person"
Payout currency the recipient receives (must match the scheme).
"NGN"
Corridor scheme id from GET /corridors (e.g. ng_nip, ke_mpesa,
eu_sepa, us_ach). Determines required routing keys.
"ng_nip"
Account holder name as registered with the receiving bank or wallet.
"Ada Okoye"
Scheme-specific account identifiers. Keys depend on the corridor
(e.g. bank_code + account_number for ng_nip). See corridor
field definitions from GET /corridors.
{
"bank_code": "058",
"account_number": "0123456789"
}
Given name (required when kind is person).
"Ada"
Family name (required when kind is person).
"Okoye"
Legal business name (required when kind is business).
Optional label shown in your dashboard and lists.
Optional contact email for the recipient.
Relationship code from GET /corridors → relationships (e.g. supplier,
employee). Required for some personal corridors.
Postal address for the recipient when the corridor requires it.
Show child attributes
Show child attributes
ISO 3166-1 alpha-2 country for the corridor (e.g. NG).
"NG"
Response
Created beneficiary
Object type discriminator.
beneficiary Beneficiary id — pass as beneficiary_id on payouts.
Recipient type.
person, business Display name derived from person or business fields.
Given name when kind is person.
Family name when kind is person.
Legal name when kind is business.
Optional display label.
Contact email.
Relationship to your workspace.
Postal address for the recipient when the corridor requires it.
Show child attributes
Show child attributes
Currency the recipient is paid in.
Corridor country.
High-level rail family (bank, mobile_money, …).
Corridor scheme id.
Human-readable scheme name.
Typical settlement timing (e.g. Instant, Same day).
Account holder name on the rail.
Scheme-specific account identifiers (may be partially masked).
Short label for the destination account.
Lifecycle status (active, archived, …).
Fields still required before the beneficiary can be paid.
When the beneficiary was created (UTC).
When the beneficiary was last updated (UTC).
When archived, if applicable.
true when created with a live key.
Environment of the creating API key.
live, sandbox