Skip to main content
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..."
  }
}
FieldTypeRequiredDescription
lnInvoicestringYesLightning 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"
  }
}
FieldTypeRequiredDescription
lnAddressstringYesLightning address (email-like format)

​
On-Chain Address

For on-chain Bitcoin payouts to a standard Bitcoin address: 
{
  "beneficiary": {
    "onChainAddress": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5"
  }
}
FieldTypeRequiredDescription
onChainAddressstringYesBitcoin 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

FieldTypeRequiredDescription
bankAccountNamestringYesAccount holder’s name as registered with the bank
bankCodestringYesNIP bank code (get from /bank/bankcode?country=NG)
bankNamestringYesFull bank name
bankAccountNumberstringYes10-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

FieldTypeRequiredDescription
namestringYesBeneficiary’s full name
bankNamestringYesSouth African bank name
bankAccountNumberstringYesSouth 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 are processed through M-Pesa. There are three supported M-Pesa payment methods:

​
Pay to Phone (Mobile Money)

Send money directly to a mobile phone number. 
{
  "beneficiary": {
    "identifierType": "paytophone",
    "identifiers": {
      "phoneNumber": "+254796980711",
      "accountName": "John Doe"
    }
  }
}

​
Fields

FieldTypeRequiredDescription
identifierTypestringYesMust be "paytophone"
identifiers.phoneNumberstringYesKenyan phone number in international format (+254…)
identifiers.accountNamestringYesName associated with the M-Pesa account

​
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

FieldTypeRequiredDescription
identifierTypestringYesMust be "paytobill"
accountNamestringYesAccount name (usually the same as the account number)
identifiers.paybillNumberstringYesM-Pesa paybill number
identifiers.accountNumberstringYesAccount 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

FieldTypeRequiredDescription
identifierTypestringYesMust be "paytotill"
accountNamestringYesName of the business
identifiers.tillNumberstringYesM-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

HeaderValue
Content-Typeapplication/json
x-api-keyYour API key

​
Request Body

For Paybill validation: 
{
  "identifier": "247247",
  "identifierType": "PayBill"
}
For Till validation: 
{
  "identifier": "796980711",
  "identifierType": "Till"
}

​
Parameters

FieldTypeRequiredDescription
identifierstringYesThe paybill or till number to validate
identifierTypestringYesEither "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"
    }
  }
}

​
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…)
    • 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