Beneficiary Formats

When creating a quote, you must provide beneficiary information in the correct format for the target currency. This guide shows the required format for each supported currency.

Bitcoin (BTC)

For Bitcoin payouts, you can use one of three methods: Lightning Invoice, Lightning Address, or On-Chain Address.

Lightning Invoice

{
  "beneficiary": {
    "lnInvoice": "lntbs20u1p5dmy87pp5l2pm..."
  }
}

Field	Type	Required	Description
`lnInvoice`	string	Yes	Lightning Network invoice for the payout

The invoice must be valid and not expired when the payout is processed.

Lightning Address

{
  "beneficiary": {
    "lnAddress": "user@wallet.com"
  }
}

Field	Type	Required	Description
`lnAddress`	string	Yes	Lightning address (email-like format)

On-Chain Address

For on-chain Bitcoin payouts to a standard Bitcoin address:

{
  "beneficiary": {
    "onChainAddress": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5"
  }
}

Field	Type	Required	Description
`onChainAddress`	string	Yes	Bitcoin address (legacy, P2SH, or native SegWit)

On-chain transactions have a minimum amount of 6000 SATs and require a minimum of 3 blockchain confirmations. For faster, lower-fee payments, consider using Lightning.

Nigerian Naira (NGN)

For Nigerian Naira payouts, provide complete bank account details.

{
  "beneficiary": {
    "bankAccountName": "olaolu olajide",
    "bankCode": "000013",
    "bankName": "GTBANK PLC",
    "bankAccountNumber": "0087241555"
  }
}

Fields

Field	Type	Required	Description
`bankAccountName`	string	Yes	Account holder’s name as registered with the bank
`bankCode`	string	Yes	NIP bank code (get from `/bank/bankcode?country=NG`)
`bankName`	string	Yes	Full bank name
`bankAccountNumber`	string	Yes	10-digit Nigerian bank account number

Use the Name Enquiry endpoint to validate the account details before creating a quote.

South African Rand (ZAR)

For South African Rand payouts, provide the beneficiary name and bank details.

{
  "beneficiary": {
    "name": "test merchant 1",
    "bankName": "CAPITEC BANK",
    "bankAccountNumber": "1325558779"
  }
}

Fields

Field	Type	Required	Description
`name`	string	Yes	Beneficiary’s full name
`bankName`	string	Yes	South African bank name
`bankAccountNumber`	string	Yes	South African bank account number

Bank account validation is not currently available for ZAR. Ensure account details are correct before creating a quote.

Kenyan Shilling (KES)

Kenyan payouts support mobile money (M-Pesa and Airtel) and M-Pesa paybill/till payments. There are three supported payment methods:

Pay to Phone (Mobile Money)

Send money directly to a mobile phone number on M-Pesa or Airtel Mobile Money.

{
  "beneficiary": {
    "identifierType": "paytophone",
    "identifiers": {
      "phoneNumber": "+254796980711",
      "accountName": "John Doe",
      "network": "mpesa"
    }
  }
}

Fields

Field	Type	Required	Description
`identifierType`	string	Yes	Must be `"paytophone"`
`identifiers.phoneNumber`	string	Yes	Kenyan phone number in international format (+254…)
`identifiers.accountName`	string	Yes	Name associated with the mobile money account
`identifiers.network`	string	Yes	Target telecom network: `"mpesa"` or `"airtel"`

Starting July 12, 2026, the network field is required for all pay-to-phone KES quotes.

Pay to Bill (Business Payments)

Send money to a business paybill number with an account reference.

{
  "beneficiary": {
    "identifierType": "paytobill",
    "identifiers": {
      "accountName": "vlad",
      "paybillNumber": "4141031",
      "accountNumber": "vlad"
    }
  }
}

Fields

Field	Type	Required	Description
`identifierType`	string	Yes	Must be `"paytobill"`
`accountName`	string	Yes	Account name (usually the same as the account number)
`identifiers.paybillNumber`	string	Yes	M-Pesa paybill number
`identifiers.accountNumber`	string	Yes	Account number/reference for the paybill

You can validate the paybill business name using the KES Identifier Validation endpoint. See detailed documentation below.

Pay to Till

Send money to a business till number.

{
  "beneficiary": {
    "identifierType": "paytotill",
    "accountName": "Business Name",
    "identifiers": {
      "tillNumber": "796980711"
    }
  }
}

Fields

Field	Type	Required	Description
`identifierType`	string	Yes	Must be `"paytotill"`
`accountName`	string	Yes	Name of the business
`identifiers.tillNumber`	string	Yes	M-Pesa till number

You can validate the till business name using the KES Identifier Validation endpoint. See detailed documentation below.

All Kenyan phone numbers must be in international format starting with +254.

KES Identifier Validation

For Pay to Bill and Pay to Till payment methods, you can validate the business name before creating a quote. This endpoint is only available in production.

Endpoint

POST https://api.mavapay.co/api/v1/quote/validate-kes-identifier

Headers

Header	Value
`Content-Type`	`application/json`
`x-api-key`	Your API key

Request Body

For Paybill validation:

{
  "identifier": "247247",
  "identifierType": "PayBill"
}

For Till validation:

{
  "identifier": "796980711",
  "identifierType": "Till"
}

Parameters

Field	Type	Required	Description
`identifier`	string	Yes	The paybill or till number to validate
`identifierType`	string	Yes	Either `"PayBill"` or `"Till"`

Response

{
  "status": "ok",
  "data": {
    "organization_name": "Equity Paybill Account"
  }
}

Example: Validate Paybill

curl --location 'https://api.mavapay.co/api/v1/quote/validate-kes-identifier' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your-api-key>' \
--data '{
    "identifier": "247247",
    "identifierType": "PayBill"
}'

Example: Validate Till

curl --location 'https://api.mavapay.co/api/v1/quote/validate-kes-identifier' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your-api-key>' \
--data '{
    "identifier": "796980711",
    "identifierType": "Till"
}'

This validation endpoint is only available in the production environment.

Complete Quote Examples

Example: NGN Payout

{
  "amount": "1000000",
  "sourceCurrency": "BTCSAT",
  "targetCurrency": "NGNKOBO",
  "paymentMethod": "LIGHTNING",
  "paymentCurrency": "NGNKOBO",
  "autopayout": true,
  "beneficiary": {
    "bankAccountName": "olaolu olajide",
    "bankCode": "000013",
    "bankName": "GTBANK PLC",
    "bankAccountNumber": "0087241555"
  }
}

Example: KES Payout (Pay to Phone)

{
  "amount": "100000",
  "sourceCurrency": "BTCSAT",
  "targetCurrency": "KESCENT",
  "paymentMethod": "LIGHTNING",
  "paymentCurrency": "BTCSAT",
  "autopayout": true,
  "beneficiary": {
    "identifierType": "paytophone",
    "identifiers": {
      "phoneNumber": "+254796980711",
      "accountName": "John Doe",
      "network": "mpesa"
    }
  }
}

Example: ZAR Payout

{
  "amount": "1000000",
  "sourceCurrency": "BTCSAT",
  "targetCurrency": "ZARCENT",
  "paymentMethod": "LIGHTNING",
  "paymentCurrency": "ZARCENT",
  "autopayout": true,
  "beneficiary": {
    "name": "test merchant 1",
    "bankName": "CAPITEC BANK",
    "bankAccountNumber": "1325558779"
  }
}

Example: BTC Payout (Lightning Invoice)

{
  "amount": "2000",
  "sourceCurrency": "NGNKOBO",
  "targetCurrency": "BTCSAT",
  "paymentMethod": "BANKTRANSFER",
  "paymentCurrency": "BTCSAT",
  "autopayout": true,
  "beneficiary": {
    "lnInvoice": "lntbs20u1p5dmy87pp5l2pm..."
  }
}

Example: BTC Payout (Lightning Address)

{
  "amount": "2000",
  "sourceCurrency": "NGNKOBO",
  "targetCurrency": "BTCSAT",
  "paymentMethod": "BANKTRANSFER",
  "paymentCurrency": "BTCSAT",
  "autopayout": true,
  "beneficiary": {
    "lnAddress": "user@getalby.com"
  }
}

Example: BTC Payout (On-Chain Address)

{
  "amount": "2000",
  "sourceCurrency": "NGNKOBO",
  "targetCurrency": "BTCSAT",
  "paymentMethod": "BANKTRANSFER",
  "paymentCurrency": "BTCSAT",
  "autopayout": true,
  "beneficiary": {
    "onChainAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }
}

Validation

Before creating a quote, you can validate beneficiary details:

NGN: Use the Name Enquiry endpoint to validate account details
ZAR: Validation not currently available
KES:
- For Pay to Phone: Ensure phone numbers are in correct format (+254…) and include the required network field ("mpesa" or "airtel")
- For Pay to Bill and Pay to Till: Use the KES Identifier Validation endpoint to validate business names (production only)
BTC: Ensure Lightning invoice is valid and not expired

Next Steps

View complete quote examples for all currency pairs
Learn about webhook notifications for tracking payments
Test your integration in our staging environment

Get Started

Payouts

Stablecoins

Webhooks

Guides

Beneficiary Formats

Bitcoin (BTC)

Lightning Invoice

Lightning Address

On-Chain Address

Nigerian Naira (NGN)

Fields

South African Rand (ZAR)

Fields

Kenyan Shilling (KES)

Pay to Phone (Mobile Money)

Fields

Pay to Bill (Business Payments)

Fields

Pay to Till

Fields

KES Identifier Validation

Endpoint

Headers

Request Body

Parameters

Response

Example: Validate Paybill

Example: Validate Till

Complete Quote Examples

Example: NGN Payout

Example: KES Payout (Pay to Phone)

Example: ZAR Payout

Example: BTC Payout (Lightning Invoice)

Example: BTC Payout (Lightning Address)

Example: BTC Payout (On-Chain Address)

Validation

Next Steps

​Bitcoin (BTC)

​Lightning Invoice

​Lightning Address

​On-Chain Address

​Nigerian Naira (NGN)

​Fields

​South African Rand (ZAR)

​Fields

​Kenyan Shilling (KES)

​Pay to Phone (Mobile Money)

​Fields

​Pay to Bill (Business Payments)

​Fields

​Pay to Till

​Fields

​KES Identifier Validation

​Endpoint

​Headers

​Request Body

​Parameters

​Response

​Example: Validate Paybill

​Example: Validate Till

​Complete Quote Examples

​Example: NGN Payout

​Example: KES Payout (Pay to Phone)

​Example: ZAR Payout

​Example: BTC Payout (Lightning Invoice)

​Example: BTC Payout (Lightning Address)

​Example: BTC Payout (On-Chain Address)

​Validation

​Next Steps

Bitcoin (BTC)

Lightning Invoice

Lightning Address

On-Chain Address

Nigerian Naira (NGN)

Fields

South African Rand (ZAR)

Fields

Kenyan Shilling (KES)

Pay to Phone (Mobile Money)

Fields

Pay to Bill (Business Payments)

Fields

Pay to Till

Fields

KES Identifier Validation

Endpoint

Headers

Request Body

Parameters

Response

Example: Validate Paybill

Example: Validate Till

Complete Quote Examples

Example: NGN Payout

Example: KES Payout (Pay to Phone)

Example: ZAR Payout

Example: BTC Payout (Lightning Invoice)

Example: BTC Payout (Lightning Address)

Example: BTC Payout (On-Chain Address)

Validation

Next Steps