Creating and Managing Beneficiaries

Creating beneficiaries is an effective way to enhance your payout process and ensure a smooth payout experience for your customers. We have created an API for you to create and manage recipients’ and their account details securely.

You can easily:

Create: Add a new beneficiary's bank details.
Retrieve: Get the details of a single beneficiary.
Fetch history: View all the beneficiaries you have saved.

Creating a beneficiary

To create a beneficiary, make a POST request to the Create Beneficiary endpoint:

{{baseurl}}/api/v1/payouts/beneficiaries

The request body should have the following parameters:

Field	Data Type	Required?	Description
`reference`	String	True	This is the unique reference used to identify the payout.
`destination.type`	String	True	This is the type of destination to which the payout is to be made (e.g., `bank_account`).
`destination.currency`	String	True	This is the currency of the beneficiary account (e.g., `USD`).
`destination.customer.name`	String	True	This the full name of the beneficiary/customer.
`destination.customer.email`	String	True	This is the email of the beneficiary/customer.
`bank_account.account`	String	True	This is the bank account number.
`bank_account.account_name`	String	True	This is the name on the bank account.
`bank_account.bank_name`	String	True	This is the name of the bank.
`bank_account.beneficiary_type`	String	True	This is the type of the beneficiary. It can either be `individual` or `business`.
`bank_account.first_name`	String	True	This is the beneficiary's first name.
`bank_account.last_name`	String	True	This is the beneficiary's last name.
`bank_account.account_type`	String	True	This is the account type - `savings` or `checking`.
`bank_account.account_number_type`	String	True	This is the format of the account number - `account_number` (for regular account numbers) or `iban` (for international bank account numbers).
`address_information.country`	String	True	This is the country code for the beneficiary's address. E.g, `US`.
`address_information.state`	String	True	This is the state or region for the beneficiary's address.
`address_information.city`	String	True	This is the city of residence for the beneficiary.
`address_information.zip_code`	String	True	This is the postal or ZIP code for the beneficiary's address.
`address_information.street`	String	True	This is the street name for the beneficiary's address.
`address_information.full_address`	String	True	This is the complete address line for the beneficiary, in one string.
`bank_account.payment_method`	String	True	This is the payment method - `AbaRouting` or `BicSwift`.
`bank_account.routing_number`	String	True	This is the routing number used for US bank transfers.
`bank_account.intermediary_routing_number`	String	True	This is required if `.payment_method` is `BicSwift` (SWIFT routing).

The request body could look like this:

{
    "reference": "sample-reference-from-merchant",
    "destination": {
        "type": "bank_account",
        "currency": "USD",
        "customer": {
            "name": "Jane Doe",
            "email": "[email protected]"
        },
        "bank_account": {
            "account": "1234567890",
            "account_name": "Demo Account Name",
            "bank_name": "MID-CENTRAL NATIONAL BANK",
            "beneficiary_type": "individual", // individual  or  corporate
            "first_name": "Jane",
            "last_name": "Doe",
            "account_type": "savings", //  savings or checking
            "account_number_type": "account_number", //account_number or iban
            "address_information": {
                "country": "US",
                "state": "California",
                "city": "Los Angeles",
                "zip_code": "90001",
                "street": "123 Main St",
                "full_address": "123 Main St, Los Angeles, CA 90001"
            },
            "payment_method": "AbaRouting", //  AbaRouting or BicSwift
            "routing_number": "091271660"
        }
    }
}

Here's an example of a response to this request:

{
    "status": true,
    "message": "Payout Bank account beneficiary created successfully",
    "data": {
        "reference": "sample-reference-from-merchant",
        "destination": {
            "type": "bank_account",
            "currency": "USD",
            "customer": {
                "name": "Jane Doe",
                "email": "[email protected]"
            },
            "bank_account": {
                "bank": "091271660",
                "account": "1234567890",
                "account_name": "Demo Account Name",
                "bank_name": "MID-CENTRAL NATIONAL BANK",
                "beneficiary_type": "individual",
                "first_name": "Jane",
                "last_name": "Doe",
                "business_name": null,
                "account_type": "savings",
                "account_number_type": "account_number"
                "currency": "USD",
                "routing_number": "091271660",
                "payment_method": "AbaRouting",
                "address_information": {
                    "country": "US",
                    "state": "California",
                    "city": "Los Angeles",
                    "zip_code": "90001",
                    "street": "123 Main St",
                    "full_address": "123 Main St, Los Angeles, CA 90001"
                }
            }
        }
    }
}
}

Retrieving a saved beneficiary

You can retrieve a saved beneficiary to make a payout to by using the beneficiary reference. To do this, make a GET request to the Query endpoint:

{{baseurl}}/api/v1/payouts/beneficiaries/:reference

The required parameter(s) for this request include:

Field	Data Type	Required	Description
`reference`	String	True	This is the reference of the saved beneficiary

Here's how the response to the request could look like:

{
    "status": true,
    "message": "Payout beneficiary retrieved successfully",
    "data": {
        "reference": "sample-reference-from-merchant",
        "destination": {
            "type": "bank_account",
            "currency": "USD",
            "customer": {
                "name": "John Doe",
                "email": "[email protected]"
            },
            "bank_account": {
                "bank": "083006102",
                "account": "1234567000",
                "account_name": "Test Account Name",
                "bank_name": "JP MORGAN CHASE BANK, NA",
                "beneficiary_type": "individual",
                "first_name": "John",
                "last_name": "Doe",
                "business_name": null,
                "account_type": "savings",
                "account_number_type": "account_number",
                "intermediary_routing_number": null,
                "currency": "USD",
                "routing_number": "083006102",
                "payment_method": "AbaRouting",
                "address_information": {
                    "country": "US",
                    "state": "California",
                    "city": "Los Angeles",
                    "zip_code": "90001",
                    "street": "123 Main St",
                    "full_address": "123 Main St, Los Angeles, CA 90001"
                }
            }
        }
    }
}

Fetching beneficiaries' history

You can retrieve the history of all saved beneficiaries for a period using the beneficiary History API. To do this, make a GET request to the Beneficiary history endpoint with the desired period:

{{baseurl}}/api/v1/payouts/beneficiaries

This request should have the following parameters:

Field	Data Type	Required	Description
`limit`	Number	False	This is the number of logs to return (Default value: `10` , Maximum Value: `50`).
`page`	Number	False	This is the page number of the requested page (Default value: `1`).

The response to this request would look like this:

{
    "status": true,
    "message": "Payout beneficiaries retrieved successfully",
    "data": {
        "data": [
            {
                "reference": "sample-reference-from-merchant",
                "destination": {
                    "type": "bank_account",
                    "currency": "USD",
                    "customer": {
                        "name": "John Doe",
                        "email": "[email protected]"
                    },
                    "bank_account": {
                        "bank": "00956",
                        "account": "99999999993",
                        "account_name": "Ghaju",
                        "bank_name": "JP Morgan",
                        "beneficiary_type": "individual",
                        "first_name": "John",
                        "last_name": "Doe",
                        "business_name": null,
                        "account_type": "savings",
                        "account_number_type": "account_number",
                        "intermediary_routing_number": null,
                        "currency": "USD",
                        "routing_number": "00956",
                        "payment_method": "AbaRouting",
                        "address_information": {
                            "country": "US",
                            "state": "California",
                            "city": "Los Angeles",
                            "zip_code": "90001",
                            "street": "123 Main St",
                            "full_address": "123 Main St, Los Angeles, CA 90001"
                        }
                    }
                }
            }
        ],
        "meta": {
            "total": 4,
            "page": 1,
            "limit": 10,
            "totalPages": 1
        }
    }
}