Skip to main content
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:
  1. Understand what recipients are and why they are necessary for payouts.
  2. Learn how to dynamically fetch the required fields for creating a recipient based on country and currency.

​
Prerequisites

Before you begin, ensure you have:

​
Recipient Types

Busha operates a multi-currency account system and accomodate recipients for each currency type. Currently, Busha supports the creation of recipients for:
  • Nigerian bank accounts
  • US bank accounts
  • UK bank accounts
  • M-Pesa mobile money (Kenya)
  • MTN Mobile Money
  • Cryptocurrency addresses
The recipient type is an important field in the request body object. Each recipient type have their unique fields outlined in the table below.
TypeCategoryDescriptionRequired Fields
ngn_bankbankNigerian bank accountbank_name, bank_code, account_number, account_name
usd_bankbankUS bank accountentity_type, transfer_type, account_name, bank_name + routing fields
gbp_bankbankUK bank accountentity_type, account_name, bank_name, sort_code, account_number
mpesa_mobile_moneymobile_moneyM-Pesa (Kenya)phone_number, account_name
mtn_mobile_moneymobile_moneyMTN Mobile Moneyphone_number, account_name
cryptocryptoCryptocurrency walletnetwork, crypto_address, account_name, optional memo
The recipient’s request body varies from type to type. That is, the request body for a Nigerian bank account ngn_bank, will be different from that of a US bank account usd_bank. In the following sections, we will create a recipient for each type and outline the required fields for each.

​
Nigerian Bank Account

Nigerian bank account recipients require a bank_code field. You can retrieve your bank’s code by sending a GET request to the /banks endpoint”:
The request body required to create a Nigerian bank account recipient is:
To create a recipient:
  1. Open your terminal or command prompt.
  2. Construct a POST request to the /v1/recipients endpoint.
  3. In the request body, update the following fields with your recipient’s details:
    • bank_name
    • bank_code
    • account_number
    • account_name
  4. Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.
Expected Response Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.
This 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.

​
US Bank Account (ACH)

The request body required to create a US bank account (usd_bank) recipient with a transfer type ach is:
To create a recipient:
  1. Open your terminal or command prompt.
  2. Construct a POST request to the /v1/recipients endpoint.
  3. In the request body, update the following fields with your recipient’s details:
    • entity_type : This can be personal or business depending on the recipient’s bank entity type.
    • account_number
    • bank_name
    • routing_number
    • account_name
  4. Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.
Expected Response Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.
This 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.

​
US Bank Account (Wire)

The request body required to create a US bank account (usd_bank) recipient with a transfer type wire is:
To create a recipient:
  1. Open your terminal or command prompt.
  2. Construct a POST request to the /v1/recipients endpoint.
  3. In the request body, update the following fields with your recipient’s details:
    • entity_type : This can be personal or business depending on the recipient’s bank entity type.
    • account_number
    • bank_name
    • routing_number
    • account_name
    • swift_code
  4. Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.
Expected Response Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.
This 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.

​
US Bank Account (SWIFT)

The request body required to create a US bank account (usd_bank) recipient with a transfer type of swift is:
To create a recipient:
  1. Open your terminal or command prompt.
  2. Construct a POST request to the /v1/recipients endpoint.
  3. In the request body, update the following fields with your recipient’s details:
    • entity_type : This can be personal or business depending on the recipient’s bank entity type.
    • account_name
    • iban
    • swift_code
    • bank_name
    • recipient_address
    • intermediary_bank_name
    • intermediary_bank_address
    • intermediary_swift_code
  4. Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.
Expected Response Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.
This 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.

​
M-Pesa Mobile Money

The request body required to create an M-Pesa mobile money (mpesa_mobile_money) recipient is:
To create a recipient:
  1. Open your terminal or command prompt.
  2. Construct a POST request to the /v1/recipients endpoint.
  3. In the request body, update the following fields with your recipient’s details:
    • account_name
    • phone_number
  4. Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.
Expected Response Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.
This 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.

​
Bitcoin

The request body required to create a cryptocurrency recipient on the Bitcoin network:
To create a recipient:
  1. Open your terminal or command prompt.
  2. Construct a POST request to the /v1/recipients endpoint.
  3. In the request body, update the following fields with your recipient’s details:
    • account_name : The name to identify the Bitcoin address stored.
    • address
  4. Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.
Expected Response Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.
This 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.

​
USDT (ETH)

The request body required to create a cryptocurrency recipient (USDT) on the Ethereum network:
To create a recipient:
  1. Open your terminal or command prompt.
  2. Construct a POST request to the /v1/recipients endpoint.
  3. In the request body, update the following fields with your recipient’s details:
    • account_name : The name to identify the USDT address stored.
    • address
  4. Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.
Expected Response Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.
This 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.

​
STELLAR LUMENS

The request body required to create a cryptocurrency recipient on the XLM network:
To create a recipient:
  1. Open your terminal or command prompt.
  2. Construct a POST request to the /v1/recipients endpoint.
  3. In the request body, update the following fields with your recipient’s details:
    • account_name : The identifier for the recipient details.
    • address
    • memo
  4. Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.
Expected Response Upon successful creation, the API will return a response containing the details of the newly created recipient, including its unique id.
This 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.

​
Retrieve and List Recipients

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:
  1. Open your terminal or command prompt.
  2. Construct a GET request to the /v1/recipients/{id} endpoint, replacing {id} with the actual recipient ID.
  3. Ensure your Authorization and YOUR_SECRET_TOKEN headers are included.
  4. Replace placeholders like YOUR_BASE_URL and 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.
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:
  1. Open your terminal or command prompt.
  2. Construct a GET request to the /v1/recipients endpoint.
  3. Ensure your Authorization header is included.
  4. Replace placeholders like YOUR_BASE_URL and 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.

​
What’s Next?

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