Creating a Beneficiary

Request Body

POST /v2/beneficiaries

Parameter	Type	Required	Description
country	string	✅	ISO 2-letter country code of the beneficiary.
address	object	❌	Physical address of the beneficiary (required for most non-NGN beneficiaries).
kind	enum	✅	Kind of beneficiary: "INDIVIDUAL" or "BUSINESS".
name	string	✅	Account holder name of the beneficiary.
friendly_name	string	❌	Optional custom name for easier identification.
currency	string	✅	Currency code the beneficiary can receive (ISO 4217).
email	string	❌	Email address of the beneficiary (required for most non-NGN beneficiaries).
is_own_account	boolean	❌	Whether this beneficiary is your own account (default: false).
client_reference	string	❌	Your custom reference for this beneficiary.
method	object	✅	Payment method details (see "Method Object" below).

Method Object

Parameter	Type	Required	Description
type	string	✅	Type of payment method (NUBAN, SWIFT, ACH, FED_WIRE, SEPA, FASTER_PAYMENTS, MOBILE_MONEY, GENERIC).
details	object	✅	Specific details for the payment method type (see examples below).

The details object varies based on the type field. Please refer to the examples below for the specific structure required for each method type.

Example Requests

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "name": "Alan Turing",
    "kind": "INDIVIDUAL",
    "currency": "NGN",
    "is_own_account": false,
    "client_reference": "customer-123",
    "method": {
      "type": "NUBAN",
      "details": {
        "account_number": "0123456789",
        "bank_code": "033",
        "account_name": "Alan Turing"
      }
    }
  }'

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "name": "Global Tech Inc.",
    "kind": "BUSINESS",
    "currency": "USD",
    "email": "[email protected]",
    "address": {
      "line_1": "123 Main Street",
      "line_2": "Suite 500",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "is_own_account": false,
    "method": {
      "type": "SWIFT",
      "details": {
        "swift_bic": "CHASUS33",
        "account_number": "000123456789",
        "bank_name": "JPMorgan Chase Bank",
        "bank_address": {
          "line_1": "270 Park Avenue",
          "city": "New York",
          "state": "NY",
          "postal_code": "10017",
          "country": "US"
        }
      }
    }
  }'

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "name": "Alice Johnson",
    "kind": "INDIVIDUAL",
    "currency": "USD",
    "email": "[email protected]",
    "address": {
      "line_1": "456 Oak Street",
      "city": "Boston",
      "state": "MA",
      "postal_code": "02108",
      "country": "US"
    },
    "method": {
      "type": "ACH",
      "details": {
        "account_number": "12345678901",
        "routing_number": "021000021",
        "bank_name": "Bank of America",
        "account_type": "checking",
        "bank_address": {
          "line_1": "100 Federal Street",
          "city": "Boston",
          "state": "MA",
          "postal_code": "02110",
          "country": "US"
        }
      }
    }
  }'

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "DE",
    "name": "Heinz Schmidt",
    "kind": "INDIVIDUAL",
    "currency": "EUR",
    "email": "[email protected]",
    "address": {
      "line_1": "Unter den Linden 10",
      "city": "Berlin",
      "postal_code": "10117",
      "country": "DE"
    },
    "method": {
      "type": "SEPA",
      "details": {
        "iban": "DE89370400440532013000",
        "bic_swift": "DEUTDEFF",
        "bank_name": "Deutsche Bank"
      }
    }
  }'

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "name": "James Miriuki",
    "kind": "INDIVIDUAL",
    "currency": "KES",
    "is_own_account": false,
    "client_reference": "kes-customer-1",
    "method": {
      "type": "MOBILE_MONEY",
      "details": {
        "type": "PHONE",
        "phone_number": "+254700700000",
      }
    }
  }'

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "name": "James Miriuki",
    "kind": "INDIVIDUAL",
    "currency": "KES",
    "is_own_account": false,
    "client_reference": "kes-customer-1",
    "method": {
      "type": "MOBILE_MONEY",
      "details": {
        "type": "TILL",
        "till_number": "423432"
      }
    }
  }'

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "name": "James Miriuki",
    "kind": "INDIVIDUAL",
    "currency": "KES",
    "is_own_account": false,
    "client_reference": "kes-customer-1",
    "method": {
      "type": "MOBILE_MONEY",
      "details": {
        "type": "PAYBILL",
          "paybill_number": "4130023",  
					"account_number": "272701222"

      }
    }
  }'

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "name": "John Jima",
    "kind": "INDIVIDUAL",
    "currency": "KES",
    "method": {
        "type": "BANK_ACCOUNT",
        "details": {
            "bank_name": "Absa Bank Kenya Plc",
            "account_name": "John Doe",
            "account_number": "22362174",
            "bank_code":"03",
            "country_code":"KE"
        }
    }
}'

Response

Upon successful creation, the API returns a 201 Created status and the details of the created beneficiary:

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "state": "ACTIVE",
    "created_date": "2023-05-14T10:30:45Z",
    "updated_date": "2023-05-14T10:30:45Z",
    "type": "FIAT",
    "country": "NG",
    "kind": "INDIVIDUAL",
    "name": "Alan Turing",
    "currency": "NGN",
    "is_own_account": false,
    "client_reference": "customer-123",
    "method": {
      "type": "NUBAN",
      "details": {
        "account_number": "0123456789",
        "bank_code": "033",
        "account_name": "Alan Turing"
      }
    }
  }
}

Nigerian Account Validation

Before creating a NUBAN beneficiary, you can validate Nigerian bank accounts using our API. This process involves two steps:

Retrieving a list of supported Nigerian banks
Validating the account number with a specific bank

This validation ensures that the account exists and helps retrieve the correct account holder name, reducing errors in transfers.

Step 1: Get Nigerian Banks List

Retrieve a list of all supported Nigerian banks. This endpoint returns bank names, codes, and NIP codes required for account validation. This can be skipped if you already have the bank code saved

Banks List Response

The /v2/data/ngn/banks endpoint returns a list of all supported Nigerian banks. Below is the structure of the response:

Field	Type	Description
data	array	An array of bank objects

Bank Object Structure

Each bank object in the data array has the following structure:

Field	Type	Description
bank_code	string	The bank code used for NUBAN accounts (3-6 digits)
name	string	The official name of the bank
nip_code	string	The Nigerian Inter-bank Payment (NIP) code used for account validation (3-6 digits)

Endpoint

curl -X GET "https://api.sandbox.waza.co/lync/banking/v2/data/ngn/banks" \
  -H "x-waza-api-key: your_api_key_here"

Example Response

{
  "data": [
    {
      "bank_code": "033",
      "name": "United Bank for Africa",
      "nip_code": "033"
    },
    {
      "bank_code": "044",
      "name": "Access Bank",
      "nip_code": "044"
    },
    {
      "bank_code": "050",
      "name": "EcoBank",
      "nip_code": "050"
    },
    {
      "bank_code": "058",
      "name": "Guaranty Trust Bank",
      "nip_code": "058"
    },
    {
      "bank_code": "011",
      "name": "First Bank of Nigeria",
      "nip_code": "011"
    }
    // Additional banks...
  ]
}

Step 2: Validate Nigerian Account

After obtaining the bank's NIP code, you can validate a specific account number using this endpoint.

Query Parameters

Parameter	Type	Required	Description
account_number	string	✅	10-digit NUBAN account number
nip_code	string	✅	NIP code of the bank (obtained from the banks list)

Account Validation Response

The /v2/data/ngn/validate-account endpoint validates a Nigerian bank account and returns the account holder's details. Below is the structure of the response:

Field	Type	Description
data	object	The validated account information

Validated Account Object Structure

The data object contains the following fields:

Field	Type	Description
nip_code	string	The NIP code of the bank used for the validation
bank_code	string	The bank code for the validated account
account_name	string	The official account holder name as registered with the bank
account_number	string	The validated 10-digit account number
bank_name	string	The official name of the bank

Example Request

curl -X GET "https://api.sandbox.waza.co/lync/banking/v2/data/ngn/validate-account?account_number=0123456789&nip_code=044" \
  -H "x-waza-api-key: your_api_key_here"

Example Response

{
  "data": {
    "nip_code": "044",
    "bank_code": "044",
    "account_name": "ALAN TURING",
    "account_number": "0123456789",
    "bank_name": "Access Bank"
  }
}

Step 3: Create Beneficiary Using Validated Data

Once you've validated the account, you can create a NUBAN beneficiary using the returned data.

Example: Creating a Beneficiary with Validated Data

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "name": "ALAN TURING",
    "kind": "INDIVIDUAL",
    "currency": "NGN",
    "is_own_account": false,
    "client_reference": "customer-123",
    "method": {
      "type": "NUBAN",
      "details": {
        "account_number": "0123456789",
        "bank_code": "044",
        "account_name": "ALAN TURING"
      }
    }
  }'

Notes

The address object is required for most beneficiaries except for NUBAN (Nigerian) and Kenyan accounts
Validation rules vary by payment method type and country
Use client_reference for idempotency and to retrieve beneficiaries later easily
Different beneficiary types require different fields in their respective details objects
Once created, a beneficiary ID can be used in the transfer creation API to initiate payments

For country-specific payment method requirements, use the /v2/beneficiaries/data/supported-country-methods endpoint to get the most up-to-date information.

Kenyan Beneficiaries

For Kenyan beneficiaries, you have multiple options depending on your preferred payment method and the recipient's banking setup. Kenya supports both traditional banking and mobile money services, giving you flexibility in how you send funds.

Kenyan Bank Accounts

To create a Kenyan Bank Account beneficiary, use the BANK_ACCOUNT Payment method.

Step 1: Get Kenyan Banks List

Get a list of all supported Kenyan banks. This endpoint returns bank names and bank codes.

Banks List Response

The /v2/data/kes/banks endpoint returns a list of all supported Kenyan banks. Below is the structure of the response:

Field	Type	Description
data	array	An array of bank objects

Bank Object Structure

Each bank object in the data array has the following structure:

Field	Type	Description
bank_code	string	The bank code used for the Kenyan account
bank_name	string	The official name of the bank

Endpoint

curl -X GET "https://api.sandbox.waza.co/lync/banking/v2/data/kes/banks" \
  -H "x-waza-api-key: your_api_key_here"

Example Response

[
    {
        "bank_name": "Absa Bank Kenya Plc",
        "bank_code": "0003"
    },
    {
        "bank_name": "Access Bank Kenya PLC",
        "bank_code": "0026"
    },
    {
        "bank_name": "African Banking Corporation Limited",
        "bank_code": "0035"
    }
		// Additional banks
]

Step 2: Create a beneficiary with the details retrieved

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "name": "John Jima",
    "kind": "INDIVIDUAL",
    "currency": "KES",
    "method": {
        "type": "BANK_ACCOUNT",
        "details": {
            "bank_name": "Absa Bank Kenya Plc",
            "account_name": "John Doe",
            "account_number": "22362174",
            "bank_code":"03",
            "country_code":"KE"
        }
    }
}'

Bank Account Fields

Parameter	Type	Required	Description
`account_number`	string	✅	Account number of beneficiary
`account_name`	string	✅	Name of beneficiary
`bank_name`	string	✅	The beneficiary bank name
`bank_code`	string	✅	The beneficiary bank code
`country_code`	string	✅	The country code of the account created

Mobile Money (M-Pesa)

B2C and Business payments are classified under mobile money. The options include PHONE, TILL and PAYBILL

Phone (B2C)

Send money directly to personal M-Pesa wallets using the beneficiary's mobile phone number

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "name": "John Jima",
    "kind": "INDIVIDUAL",
    "currency": "KES",
    "method": {
        "type": "MOBILE_MONEY",
        "details": {
            "method": "PHONE",            
            "phone_number": "+25470070000"
        }
    }
}'

Phone Beneficiary Fields

Parameter	Type	Required	Description
`phone_number`	string	✅	A valid Kenyan phone number starting with dial code +254

Till Payments (Buy Goods and Services)

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "name": "James Miriuki",
    "kind": "INDIVIDUAL",
    "currency": "KES",
    "is_own_account": false,
    "client_reference": "kes-customer-1",
    "method": {
      "type": "MOBILE_MONEY",
      "details": {
        "type": "TILL",
        "till_number": "423432"
      }
    }
  }'

Till Beneficiary fields

Parameter	Type	Required	Description
`till_number`	string	✅	Merchant's till number

Paybill (Business Payments)

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/beneficiaries" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "name": "James Miriuki",
    "kind": "INDIVIDUAL",
    "currency": "KES",
    "is_own_account": false,
    "client_reference": "kes-customer-1",
    "method": {
        "type": "MOBILE_MONEY",
        "details": {
            "type": "PAYBILL",
            "paybill_number": "4130023",
            "account_number": "272701222"
        }
    }
}'

Paybill Beneficiary fields

Parameter	Type	Required	Description
`paybill_number`	string	✅	Business paybill number
`account_number`	string	✅	Business account number