Create and Manage Recipients

Recipients are pre-defined payment accounts (such as bank accounts, mobile money wallets, or crypto addresses) that act as destinations for your payouts via the Busha API. By creating and managing recipients, you streamline your off-ramp processes, ensuring funds are sent to verified and correct destinations quickly and efficiently.

What You’ll Achieve:

Understand what recipients are and why they are necessary for payouts.
Learn how to dynamically fetch the required fields for creating a recipient based on country and currency.

PrerequisitesCopied!

Before you begin, ensure you have:

A Busha Business Account and Secret API Key (from the Quick Start Tutorial).
An understanding of API Environments (Sandbox vs. Production) and their base URLs (from the Make Your First Request Guide).
A conceptual understanding of Payouts/Off-Ramp processes (from the How to Make Payouts Guide)

Step 1: Understanding Recipient RequirementsCopied!

Before you can create a recipient, it’s crucial to know exactly what information Busha requires for that specific payment method and region. Busha provides a dedicated API endpoint /v1/recipient-requirements) that allows you to fetch these unnecessary fields and parameters dynamically. This is particularly useful for building dynamic user interfaces that adapt to different payout methods and countries.

The specific payment method and its requirements for a recipient are determined by passing the country_id and currency_id as query parameters to the recipient requirements API.

To fetch the recipient's requirements:

Open your terminal or command prompt.
Construct a GET request to the /v1/recipient-requirements endpoint.
Include the country_id (e.g., NG for Nigeria) and currency_id (e.g., NGN for Naira) as query parameters.
Replace YOUR_BASE_URL and YOUR_TOKEN_HERE with your base URL and Secret API Key.

Recipients are payment accounts mostly used as a destination for payouts via the Busha

$ curl -i -X GET \
  'https://YOUR_BASE_URL/v1/recipient-requirements?country_id=NG&currency_id=NGN' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'

The request above, targeting Nigeria (NG) and Nigerian Naira (NGN), will typically result in requirements for a bank_transfer payment type, as bank accounts are the primary means of Naira payment in Nigeria.

Expected Response (Example for NGN Bank Transfer):

You will receive a response containing an array of recipient requirement objects. Each object describes a specific payment method's requirements, including its name, type, and a fields array that lists all the parameters you'll need to collect when creating a recipient for that method.

 {
  "status": "success",
  "message": "RecipientRequirements retrieved successfully",
  "data": [
    {
      "id": "61e00b392899a2c7173306f0",
      "name": "Bank Transfer",
      "type": "ngn_bank_transfer",
      "active": true,
      "country_id": "NG",
      "currency_id": "NGN",
      "description": "",
      "created_at": "2022-01-13T11:21:29.117Z",
      "fields": [
        {
          "description": "",
          "display_name": "Bank Code",
          "hint_word": "passed by app",
          "is_copyable": false,
          "is_visible": false,
          "message": "must be 10 digits",
          "name": "bank_code",
          "options": [],
          "order": 3,
          "populate_from": "",
          "populate_from_value": "",
          "populate_target": [],
          "required": true,
          "requires_url_validation": false,
          "type": "string",
          "unique": false,
          "validator": "^\\d{3,10}$"
        },
        {
          "description": "",
          "display_name": "Bank Name",
          "hint_word": "Enter bank name",
          "is_copyable": false,
          "is_visible": true,
          "message": "length must be in range between 2 and 50",
          "name": "bank_name",
          "options": [],
          "order": 2,
          "populate_from": "",
          "populate_from_value": "",
          "populate_target": [],
          "required": true,
          "requires_url_validation": false,
          "type": "string",
          "unique": false,
          "validator": ".{2,100}"
        },
        {
          "description": "",
          "display_name": "Account Name",
          "hint_word": "Enter account name",
          "is_copyable": true,
          "is_visible": true,
          "message": "length must be in range between 2 and 100",
          "name": "account_name",
          "options": [],
          "order": 0,
          "populate_from": "",
          "populate_from_value": "",
          "populate_target": [],
          "required": true,
          "requires_url_validation": false,
          "type": "string",
          "unique": false,
          "validator": ".{2,100}"
        },
        {
          "description": "",
          "display_name": "Account Number",
          "hint_word": "Enter account number",
          "is_copyable": true,
          "is_visible": true,
          "message": "must be 10 digits",
          "name": "account_number",
          "options": [],
          "order": 1,
          "populate_from": "",
          "populate_from_value": "",
          "populate_target": [],
          "required": true,
          "requires_url_validation": false,
          "type": "string",
          "unique": false,
          "validator": "^\\d{10}$"
        }
      ]
    }
  ]
}

You can use the response of this recipient requirements API to dynamically build your user interface for collecting the information needed to create a recipient, ensuring you ask for all necessary and valid details.

Step 2: Create a RecipientCopied!

Once you have identified the required fields from Step 1, you can proceed to create the recipient by sending a POST request to the /v1/recipients endpoint. The payload of your request must exactly match the name and value for all required fields identified in the recipient requirements for that specific payment method.

Currently, only Nigerian Banks are supported for the.

To create a recipient:

Open your terminal or command prompt.
Construct s POST request to the /v1/recipients endpoint.
In the request body, include the country_id, currency_id, the type of the recipient (e.g., ngn_bank_transfer), and a fields array containing all the necessary recipient details collected from your user, adhering to the requirements fetched in Step 1.
Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.

$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/recipients \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'X-BU-PROFILE-ID: BUS_tg6yujbZ3nMu5BLQkPGGO' \
  -d '{
    "country_id": "NG",
    "currency_id": "NGN",
    "type": "ngn_bank_transfer",
    "fields": [
      {
        "name": "account_name",
        "value": "SOSANYA DICKSON OLUMIDE"
      },
      {
        "name": "account_number",
        "value": "2109328188"
      },
      {
        "name": "bank_name",
        "value": "UNITED BANK FOR AFRICA"
      },
      {
        "name": "bank_code",
        "value": "033"
      }
    ]
  }'

Expected Response (Successful Recipient Creation):

Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.

{
  "status": "success",
  "message": "message for success",
  "data": {
    "object": "recipient",
    "id": "platform_123456", // This is the crucial recipient ID
    "user_id": "platform_123456",
    "profile_id": "platform_123456",
    "currency_id": "NGN",
    "country_id": "NG",
    "type": "ngn_bank_transfer",
    "legal_entity_type": "business",
    "owned_by_customer": true,
    "active": true,
    "created_at": "2024-05-16T13:06:31.409336+01:00",
    "updated_at": "2024-05-16T13:06:31.409336+01:00",
    "fields": [
      {
        "value": "Access Bank Nigeria",
        "display_name": "Bank Name",
        "name": "bank_name",
        "is_copyable": false,
        "is_visible": true,
        "required": true
      }
    ]
  }
}

The most important value returned after creating a recipient is the data.id (e.g., platform_123456). This recipient_id is crucial and will be reused in several cases, especially when making a payout into that specific payment account, as demonstrated in the How to Make Payouts Guide. The fields array in the response allows you to know how to display each field on a UI.

Step 3: Retrieve and List RecipientsCopied!

After creating recipients, you'll often need to retrieve their details or get a list of all recipients associated with your profile. This allows you to manage your payout destinations and ensure you're using the correct recipient_id for transactions.

Retrieve a Specific Recipient

You can fetch the details of a single recipient if you know its unique id.

To retrieve a specific recipient:

Open your terminal or command prompt.
Construct a GET request to the /v1/recipients/{id} endpoint, replacing {id} with the actual recipient ID.
Ensure your Authorization and YOUR_SECRET_TOKEN headers are included.
Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN.

$ curl -i -X GET \
  'https://api.busha.co/v1/recipients/{id}' \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'

Expected Response:

A successful response will return a single recipient object, identical in structure to the one received during creation, containing all its details.

{
  "status": "success",
  "message": "Recipient retrieved successfully",
  "data": {
    "object": "recipient",
    "id": "platform_123456",
    "user_id": "platform_123456",
    "profile_id": "platform_123456",
    "currency_id": "NGN",
    "country_id": "NG",
    "type": "ngn_bank_transfer",
    "legal_entity_type": "business",
    "owned_by_customer": true,
    "active": true,
    "created_at": "2024-05-16T13:06:31.409336+01:00",
    "updated_at": "2024-05-16T13:06:31.409336+01:00",
    "fields": [
      {
        "value": "Access Bank Nigeria",
        "display_name": "Bank Name",
        "name": "bank_name",
        "is_copyable": false,
        "is_visible": true,
        "required": true
      }
    ]
  }
}

List All Recipients

To get an overview of all the recipients you have created, you can make a GET request to the /v1/recipients endpoint without specifying an ID.

To list all recipients:

Open your terminal or command prompt.
Construct a GET request to the /v1/recipients endpoint.
Ensure your Authorization and X-BU-PROFILE-ID headers are included.
Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN.

$ curl -i -X GET 'https://api.busha.co/v1/recipients' \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'

Expected Response:

A successful response will return a list (an array) of all recipient objects associated with your profile. This allows you to programmatically manage your available payout destinations.

{
  "status": "success",
  "message": "Recipients retrieved successfully",
  "data": [
    {
      "object": "recipient",
      "id": "platform_123456",
      "profile_id": "platform_123456",
      "currency_id": "NGN",
      "country_id": "NG",
      "type": "ngn_bank_transfer",
      "created_at": "2024-05-16T13:06:31.409336+01:00",
      "fields": [
        {"name": "account_name", "value": "SOSANYA DICKSON OLUMIDE"},
        {"name": "account_number", "value": "2109328188"},
        {"name": "bank_name", "value": "UNITED BANK FOR AFRICA"}
      ]
    },
    {
      "object": "recipient",
      "id": "another_recipient_id",
      "profile_id": "platform_123456",
      "currency_id": "KES",
      "country_id": "KE",
      "type": "kes_mobile_money",
      "created_at": "2024-06-01T10:00:00.000000+01:00",
      "fields": [
        {"name": "mobile_money_number", "value": "+254712345678"},
        {"name": "mobile_money_provider", "value": "MPESA"}
      ]
    }
  ]
}

What’s Next?Copied!

Now that you know how to create, retrieve, and list recipients, you can use them in your transaction flows:

How to Process Payouts to Recipients
Recipients API Reference: For full details on all available fields and endpoints.