Beneficiary Operations

The Beneficiary Operations section covers all API endpoints related to managing and verifying beneficiaries. These operations allow institutions to:

Validate a Bank Account – Verify a Nigerian bank account before adding it as a beneficiary.
List Beneficiaries – Retrieve all beneficiaries associated with an institution.
Supported Countries
Supported Banks
Payment Options

1. Validate a Bank Account

Overview

Before adding a beneficiary, this endpoint allows you to validate a Nigerian bank account by checking the account number and NIP code (bank identifier) for validity.

Request Parameters

Parameter	Type	Required	Description
`account_number`	string	✅ Yes	The bank account number to validate.
`nip_code`	string	✅ Yes	The NIP code (bank identifier) associated with the account.

Example Request

GET http://api.sandbox.waza.co/lync/data/ngn/validate-account?account_number=0123456789&nip_code=000013

Example Response

{
    "data": {
        "nip_code": "000013",
        "account_name": "John Doe",
        "account_number": "0123456789",
        "bank_name": "GTBank"
    }
}

Response Fields

Field	Type	Description
`nip_code`	string	The NIP code associated with the account.
`account_name`	string	The name attached to the account.
`account_number`	string	The validated bank account number.
`bank_name`	string	The name of the bank associated with the account.

Error Responses

400 Bad Request (Invalid Account or NIP Code)

{
    "error": {
        "message": "Invalid account number or NIP code",
        "code": "400"
    }
}

403 Forbidden (Unauthorized Access)


{
    "error": {
        "message": "Unauthorized access",
        "code": "403"
    }
}

2. List Beneficiaries

Overview

This endpoint retrieves a paginated list of beneficiaries associated with an institution. Each beneficiary contains details required for processing transactions, including bank details, country, and currency.

Query Parameters (Optional)

Parameter	Type	Required	Description
`page`	integer	No	The page number for pagination. Default: `0`.
`limit`	integer	No	The number of results per page. Default: `10`.

Example Request

GET http://api.sandbox.waza.co/lync/beneficiaries?page=1&limit=10

Example Response

{
    "data": {
        "items": [
            {
                "id": "ben_12345",
                "name": "Alice Johnson",
                "kind": "INDIVIDUAL",
                "country": "NG",
                "currency": "NGN",
                "method": {
                    "type": "NUBAN",
                    "details": {
                        "account_number": "0123456789",
                        "bank_code": "058",
                        "bank_name": "GTBank"
                    }
                }
            }
        ],
        "page": 1,
        "limit": 10,
        "total_items": 100,
        "total_pages": 10
    }
}

Response Fields

Field	Type	Description
`data.items`	array	A list of beneficiaries linked to the institution.
`id`	string	The unique identifier of the beneficiary.
`name`	string	The full name of the beneficiary.
`kind`	string	The type of beneficiary (`INDIVIDUAL` or `BUSINESS`).
`country`	string	The country of the beneficiary.
`currency`	string	The currency in which transactions occur.
`method.type`	string	The payment method type (e.g., `NUBAN`).
`method.details.account_number`	string	The bank account number of the beneficiary.
`method.details.bank_code`	string	The bank code associated with the account.
`method.details.bank_name`	string	The name of the bank associated with the account.
`page`	integer	The current page number of the results.
`limit`	integer	The number of results per page.
`total_items`	integer	The total number of beneficiaries found.
`total_pages`	integer	The total number of pages available.

Error Responses

403 Forbidden (Unauthorized Access)

{
    "error": {
        "message": "Unauthorized access",
        "code": "403"
    }
}

404 Not Found (No Beneficiaries Found)

{
    "error": {
        "message": "No beneficiaries found",
        "code": "404"
    }
}

3. Supported Countries

The Supported Countries API retrieves a list of countries, their supported currencies, and available payment methods for beneficiaries. This helps users understand which payment options are available for different countries.

Example Request

curl --location 'http://api.sandbox.waza.co/lync/banking/v2/beneficiaries/supported-country-methods'

The response provides a list of supported countries, their country codes, available currencies, and payment methods.

Example Response

{
  "data": [
    {
      "code": "AL",
      "name": "Albania",
      "methods": [
        {
          "currency": "USD",
          "payment_methods": [
            "SWIFT"
          ]
        },
        {
          "currency": "GBP",
          "payment_methods": [
            "SWIFT"
          ]
        },
        {
          "currency": "EUR",
          "payment_methods": [
            "SWIFT"
          ]
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
`data`	`array`	List of supported countries and their payment details.
`data[].code`	`string`	The two-letter country code (ISO 3166-1 alpha-2 format).
`data[].name`	`string`	Full country name.
`data[].methods`	`array`	List of supported payment methods and currencies.
`data[].methods[].currency`	`string`	Currency supported for transactions in this country.
`data[].methods[].payment_methods`	`array`	List of payment methods available for the specified currency.

4. Supported Banks

The Supported Banks API retrieves a list of banks in Nigeria, including their unique bank codes and NIP (Nigeria Interbank Payment) codes. This information is essential for identifying banks when creating beneficiaries for transactions.

Example Request

curl --location 'http://api.sandbox.waza.co/lync/banks'

The response provides a list of banks, their bank codes, and NIP codes.

Example Response

{
  "data": [
    {
      "bank_code": "090113",
      "name": "MICROVIS MICROFINANCE BANK",
      "nip_code": "090113"
    },
    {
      "bank_code": "090377",
      "name": "ISALEOYO MICROFINANCE BANK",
      "nip_code": "090377"
    },
    {
      "bank_code": "120001",
      "name": "9 PAYMENT SOLUTIONS BANK",
      "nip_code": "120001"
    },
    {
      "bank_code": "100033",
      "name": "PALMPAY",
      "nip_code": "100033"
    }
  ]
}

Response Fields

Field	Type	Description
`data`	`array`	List of supported banks.
`data[].bank_code`	`string`	Unique identifier for the bank.
`data[].name`	`string`	Name of the bank.
`data[].nip_code`	`string`	NIP (Nigeria Interbank Payment) code for the bank.

5. Payment Options

The Payment Options API provides a list of supported payment methods for beneficiaries, along with the required fields for each method. This helps users understand what information is needed to process payments through different channels.

Example Request

curl --location 'http://api.sandbox.waza.co/lync/beneficiaries/supported-payment-methods'

The response provides a list of payment methods and the required fields for each method.

Example Response

{
  "data": [
    {
      "type": "ACH",
      "description": "US ACH",
      "requirements": [
        "account_number",
        "routing_number",
        "account_type",
        "bank_address",
        "bank_name"
      ]
    },
    {
      "type": "FED_WIRE",
      "description": "US Domestic Wire",
      "requirements": [
        "account_number",
        "routing_number",
        "bank_address",
        "bank_name"
      ]
    },
    {
      "type": "SWIFT",
      "description": "International Wire / Swift",
      "requirements": [
        "account_number",
        "bank_name",
        "bank_address",
        "swift_bic",
        "intermediary_bank"
      ]
    },
    {
      "type": "SEPA",
      "description": "SEPA",
      "requirements": [
        "iban",
        "bic_swift",
        "bank_name"
      ]
    },
    {
      "type": "FASTER_PAYMENTS",
      "description": "Faster Payments",
      "requirements": [
        "account_number",
        "sort_code",
        "bank_name"
      ]
    }
  ]
}

Response Fields

Field	Type	Description
`data`	`array`	List of supported payment methods.
`data[].type`	`string`	Payment method type (e.g., `ACH`, `SWIFT`).
`data[].description`	`string`	Description of the payment method.
`data[].requirements`	`array`	List of required fields for processing payments.

Supported Payment Methods

Type	Description	Required Fields
`ACH`	US ACH Transfers	`account_number`, `routing_number`, `account_type`, `bank_address`, `bank_name`
`FED_WIRE`	US Domestic Wire Transfers	`account_number`, `routing_number`, `bank_address`, `bank_name`
`SWIFT`	International Wire / SWIFT Transfers	`account_number`, `bank_name`, `bank_address`, `swift_bic`, `intermediary_bank`
`SEPA`	SEPA Transfers	`iban`, `bic_swift`, `bank_name`
`FASTER_PAYMENTS`	UK Faster Payments	`account_number`, `sort_code`, `bank_name`
`NUBAN`	Nigerian Transfers	`account_number`, `bank_code`
`MOBILE_MONEY`	Kenyan Phone Number	`phone_number`
`MOBILE_MONEY`	Kenyan Till	`till_number`
`MOBILE_MONEY`	Kenyan Paybill	`account_number` , `paybill_number`