Beneficiaries

The beneficiaries API allows you to manage the beneficiaries of your payouts.

Create

post

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

apikey-header-Authentication

AuthenticationstringRequired

Body

application/json

namestringRequired

The name of this beneficiary

emailstringRequired

The email address of this beneficiary

Responses

201Success

application/json

post

/v1/payouts/beneficiaries

HTTPcURLJavaScriptPython

POST /v1/payouts/beneficiaries HTTP/1.1
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"
          }
        }
      }
    ]
  }
}

List

get

This endpoint lists all the beneficiaries in a business

Authorizations

apikey-header-Authentication

AuthenticationstringRequired

Responses

200Success

application/json

get

/v1/payouts/beneficiaries

HTTPcURLJavaScriptPython

GET /v1/payouts/beneficiaries HTTP/1.1
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"
            }
          }
        }
      ]
    }
  ]
}

Fetch

get

This endpoint fetches a single beneficiary by the UUID

Authorizations

apikey-header-Authentication

AuthenticationstringRequired

Path parameters

BeneficiaryUUIDstringRequired

The UUID of the beneficiary you want to fetch

Responses

200Success

application/json

get

/v1/payouts/beneficiaries/{BeneficiaryUUID}

HTTPcURLJavaScriptPython

GET /v1/payouts/beneficiaries/{BeneficiaryUUID} HTTP/1.1
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"
          }
        }
      }
    ]
  }
}

Add NUBAN Account

post

This endpoint adds a NUBAN account as a peyment method for a beneficairy.

Beneficiaries can have multiple payment methods of different types.

Authorizations

apikey-header-Authentication

AuthenticationstringRequired

Body

application/json

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 · nullableOptional

The payment channel to verify the account details with

Responses

201Success

application/json

post

/v1/payouts/beneficiaries/add-nuban-account

HTTPcURLJavaScriptPython

POST /v1/payouts/beneficiaries/add-nuban-account HTTP/1.1
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"
        }
      }
    ]
  }
}