Beneficiaries
The beneficiaries API allows you to manage the beneficiaries of your payouts.
This endpoint creates a beneficiary.
Beneficiaries are entities that you can peform a payout to. Beneficiaries can have multiple payment methods for receiving payouts, and all of these would be visible on your dashboard.
Authorizations
Body
namestringRequired
The name of this beneficiary
emailstringRequired
The email address of this beneficiary
payout_optionsarray | nullOptional
An array of the beneficiary's payment methods
Responses
201Success
application/json
post
POST /v1/payouts/beneficiaries HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 136
{
"name": "Nico Robin",
"email": "[email protected]",
"payout_options": [
{
"type": "nuban",
"account_number": "0690000032",
"bank_code": "044"
}
]
}201Success
{
"message": "Beneficiary created successfully",
"status": "success",
"data": {
"uuid": "f6d745eb-3a4f-11f0-ac87-92433b0171f7",
"is_one_time_beneficiary": 0,
"beneficiary_id": "AsB-4a98442391633",
"env_mode": "live",
"name": "Nico Robin",
"email": "[email protected]",
"created_at": "2025-05-26T16:39:16.000000Z",
"updated_at": "2025-05-26T16:39:16.000000Z",
"payouts_count": 0,
"payout_options_count": 1,
"payout_options": [
{
"uuid": "f7ad6dc1-3a4f-11f0-ac87-92433b0171f7",
"third_party_ids": {
"paystack": "RCP_42pfuquvktl2ttm"
},
"is_one_time_beneficiary": 0,
"env_mode": "live",
"payment_method_code": "PMC-2546648294955",
"created_at": "2025-05-26T16:39:18.000000Z",
"updated_at": "2025-05-26T16:39:18.000000Z",
"destination_type": "nuban",
"destination": {
"uuid": "f7477e46-3a4f-11f0-ac87-92433b0171f7",
"env_mode": "live",
"payment_channel_availability": {
"paystack": true
},
"bank_code": "232",
"account_number": "0090269960",
"account_name": "ERIC OBELEDATE APRIOKU",
"created_at": "2025-05-26T16:39:17.000000Z",
"updated_at": "2025-05-26T16:39:17.000000Z",
"bank": {
"uuid": "c38c8157-0482-11ef-9b04-5e7b61135574",
"bank_name": "Sterling Bank",
"bank_slug": "sterling-bank",
"bank_code": "232",
"payment_channel_availability": {
"paystack": true,
"flutterwave": true
},
"payment_channel_bank_codes": null,
"created_at": "2024-04-27T10:41:54.000000Z",
"updated_at": "2024-04-27T10:41:54.000000Z"
}
}
}
]
}
}This endpoint lists all the beneficiaries in a business
Authorizations
Responses
200Success
application/json
get
GET /v1/payouts/beneficiaries HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Accept: */*
200Success
{
"message": "Beneficiaries retrieved successfully",
"status": "success",
"data": [
{
"uuid": "f6d745eb-3a4f-11f0-ac87-92433b0171f7",
"is_one_time_beneficiary": 0,
"beneficiary_id": "AsB-4a98442391633",
"env_mode": "live",
"name": "Nico Robin",
"email": "[email protected]",
"created_at": "2025-05-26T16:39:16.000000Z",
"updated_at": "2025-05-26T16:39:16.000000Z",
"payouts_count": 0,
"payout_options_count": 1,
"payout_options": [
{
"uuid": "f7ad6dc1-3a4f-11f0-ac87-92433b0171f7",
"third_party_ids": {
"paystack": "RCP_42pfuquvktl2ttm"
},
"is_one_time_beneficiary": 0,
"env_mode": "live",
"payment_method_code": "PMC-2546648294955",
"created_at": "2025-05-26T16:39:18.000000Z",
"updated_at": "2025-05-26T16:39:18.000000Z",
"destination_type": "nuban",
"destination": {
"uuid": "f7477e46-3a4f-11f0-ac87-92433b0171f7",
"env_mode": "live",
"payment_channel_availability": {
"paystack": true
},
"bank_code": "232",
"account_number": "0090269960",
"account_name": "ERIC OBELEDATE APRIOKU",
"created_at": "2025-05-26T16:39:17.000000Z",
"updated_at": "2025-05-26T16:39:17.000000Z",
"bank": {
"uuid": "c38c8157-0482-11ef-9b04-5e7b61135574",
"bank_name": "Sterling Bank",
"bank_slug": "sterling-bank",
"bank_code": "232",
"payment_channel_availability": {
"paystack": true,
"flutterwave": true
},
"payment_channel_bank_codes": null,
"created_at": "2024-04-27T10:41:54.000000Z",
"updated_at": "2024-04-27T10:41:54.000000Z"
}
}
}
]
},
{
"uuid": "26d46ead-3a50-11f0-ac87-92433b0171f7",
"is_one_time_beneficiary": 0,
"beneficiary_id": "AsB-9b33385639695",
"env_mode": "live",
"name": "God Usopp",
"email": "[email protected]",
"created_at": "2025-05-26T16:40:37.000000Z",
"updated_at": "2025-05-26T16:40:37.000000Z",
"payouts_count": 0,
"payout_options_count": 1,
"payout_options": [
{
"uuid": "60f933a3-3a50-11f0-ac87-92433b0171f7",
"third_party_ids": {
"paystack": "RCP_ohloo4svzcx80yx"
},
"is_one_time_beneficiary": 0,
"env_mode": "live",
"payment_method_code": "PMC-c96c66625d6e0",
"created_at": "2025-05-26T16:42:14.000000Z",
"updated_at": "2025-05-26T16:42:14.000000Z",
"destination_type": "nuban",
"destination": {
"uuid": "29252100-3874-11f0-ac87-92433b0171f7",
"env_mode": "live",
"payment_channel_availability": {
"paystack": true
},
"bank_code": "044",
"account_number": "0690000032",
"account_name": "SHERIFAT BOLANLE IYANDA",
"created_at": "2025-05-24T07:53:20.000000Z",
"updated_at": "2025-05-24T07:53:20.000000Z",
"bank": {
"uuid": "c31c2120-0482-11ef-9b04-5e7b61135574",
"bank_name": "Access Bank",
"bank_slug": "access-bank",
"bank_code": "044",
"payment_channel_availability": {
"paystack": true,
"flutterwave": true
},
"payment_channel_bank_codes": null,
"created_at": "2024-04-27T10:41:53.000000Z",
"updated_at": "2024-04-27T10:41:55.000000Z"
}
}
}
]
}
]
}This endpoint fetches a single beneficiary by the UUID
Authorizations
Path parameters
BeneficiaryUUIDstringRequired
The UUID of the beneficiary you want to fetch
Responses
200Success
application/json
get
GET /v1/payouts/beneficiaries/{BeneficiaryUUID} HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Accept: */*
200Success
{
"message": "Beneficiary fetched successfully",
"status": "success",
"data": {
"uuid": "26d46ead-3a50-11f0-ac87-92433b0171f7",
"is_one_time_beneficiary": 0,
"beneficiary_id": "AsB-9b33385639695",
"env_mode": "live",
"name": "God Usopp",
"email": "[email protected]",
"created_at": "2025-05-26T16:40:37.000000Z",
"updated_at": "2025-05-26T16:40:37.000000Z",
"payouts_count": 0,
"payout_options_count": 1,
"payout_options": [
{
"uuid": "60f933a3-3a50-11f0-ac87-92433b0171f7",
"third_party_ids": {
"paystack": "RCP_ohloo4svzcx80yx"
},
"is_one_time_beneficiary": 0,
"env_mode": "live",
"payment_method_code": "PMC-c96c66625d6e0",
"created_at": "2025-05-26T16:42:14.000000Z",
"updated_at": "2025-05-26T16:42:14.000000Z",
"destination_type": "nuban",
"destination": {
"uuid": "29252100-3874-11f0-ac87-92433b0171f7",
"env_mode": "live",
"payment_channel_availability": {
"paystack": true
},
"bank_code": "044",
"account_number": "0690000032",
"account_name": "SHERIFAT BOLANLE IYANDA",
"created_at": "2025-05-24T07:53:20.000000Z",
"updated_at": "2025-05-24T07:53:20.000000Z",
"bank": {
"uuid": "c31c2120-0482-11ef-9b04-5e7b61135574",
"bank_name": "Access Bank",
"bank_slug": "access-bank",
"bank_code": "044",
"payment_channel_availability": {
"paystack": true,
"flutterwave": true
},
"payment_channel_bank_codes": null,
"created_at": "2024-04-27T10:41:53.000000Z",
"updated_at": "2024-04-27T10:41:55.000000Z"
}
}
}
]
}
}This endpoint adds a NUBAN account as a peyment method for a beneficairy.
Beneficiaries can have multiple payment methods of different types.
Authorizations
Body
beneficiary_uuidstringRequired
The UUID of the beneficiary we want to add a NUBAN account to
account_numberstringRequired
The new bank account number (NUBAN)
bank_codestringRequired
The bank code of the bank
payment_channelstring | nullOptional
The payment channel to verify the account details with
Responses
201Success
application/json
post
POST /v1/payouts/beneficiaries/add-nuban-account HTTP/1.1
Host:
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 107
{
"beneficiary_uuid": "6297f13d-388d-11f0-992c-0242ac120006",
"account_number": "0690000033",
"bank_code": "044"
}201Success
{
"message": "Nuban account added successfully",
"status": "success",
"data": {
"uuid": "c89a780f-392c-11f0-ac87-92433b0171f7",
"is_one_time_beneficiary": 0,
"beneficiary_id": "AsB-11330533a2636",
"env_mode": "live",
"name": "God Usopp",
"email": "[email protected]",
"created_at": "2025-05-25T05:54:55.000000Z",
"updated_at": "2025-05-25T05:54:55.000000Z",
"deleted_at": null,
"payouts_count": 0,
"payment_methods_count": 2,
"nuban_accounts": [
{
"uuid": "1053e5df-0880-11f0-9129-321c73038b14",
"env_mode": "live",
"payment_channel_availability": {
"paystack": true
},
"bank_code": "50211",
"account_number": "2003841673",
"account_name": "Eric Obeleoate Aprioku",
"created_at": "2025-03-24T07:17:37.000000Z",
"updated_at": "2025-03-24T07:17:37.000000Z",
"deleted_at": null,
"bank": {
"uuid": "c35e8d5f-0482-11ef-9b04-5e7b61135574",
"bank_name": "Kuda Bank",
"bank_slug": "kuda-bank",
"bank_code": "50211",
"payment_channel_availability": {
"paystack": true,
"flutterwave": false
},
"payment_channel_bank_codes": null,
"created_at": "2024-04-27T10:41:54.000000Z",
"updated_at": "2024-04-27T10:41:54.000000Z"
}
},
{
"uuid": "29252100-3874-11f0-ac87-92433b0171f7",
"env_mode": "live",
"payment_channel_availability": {
"paystack": true
},
"bank_code": "044",
"account_number": "0690000032",
"account_name": "SHERIFAT BOLANLE IYANDA",
"created_at": "2025-05-24T07:53:20.000000Z",
"updated_at": "2025-05-24T07:53:20.000000Z",
"deleted_at": null,
"bank": {
"uuid": "c31c2120-0482-11ef-9b04-5e7b61135574",
"bank_name": "Access Bank",
"bank_slug": "access-bank",
"bank_code": "044",
"payment_channel_availability": {
"paystack": true,
"flutterwave": true
},
"payment_channel_bank_codes": null,
"created_at": "2024-04-27T10:41:53.000000Z",
"updated_at": "2024-04-27T10:41:55.000000Z"
}
}
]
}
}Last updated