Skip to main content

​
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 Network invoice, Lightning address, or on-chain address.

​
Lightning Network Invoice

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

​
Lightning Address

{
  "beneficiary": {
    "lnAddress": "[email protected]"
  }
}

​
On-Chain Address

{
  "beneficiary": {
    "onChainAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }
}

​
Fields

FieldTypeRequiredDescription
lnInvoicestringNo*Lightning Network invoice for the payout
lnAddressstringNo*Lightning address (e.g., [email protected])
onChainAddressstringNo*Bitcoin on-chain address (bech32, P2PKH, or P2SH)
*One of these fields is required for BTC payouts.
  • Lightning invoices must be valid and not expired when the payout is processed
  • Lightning addresses provide a reusable payment destination
  • On-chain addresses support standard Bitcoin address formats

​
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"
    }
  }
}

​
Fields

FieldTypeRequiredDescription
identifierTypestringYesMust be "paytophone"
identifiers.phoneNumberstringYesKenyan phone number in international format (+254…)

​
Pay to Bill (Business Payments)

Send money to a business paybill number with an account reference. 
{
  "beneficiary": {
    "identifierType": "paytobill",
    "identifiers": {
      "paybillNumber": "4141031",
      "accountNumber": "vlad"
    }
  }
}

​
Fields

FieldTypeRequiredDescription
identifierTypestringYesMust be "paytobill"
identifiers.paybillNumberstringYesM-Pesa paybill number
identifiers.accountNumberstringYesAccount number/reference for the paybill

​
Pay to Till

Send money to a business till number. 
{
  "beneficiary": {
    "identifierType": "paytotill",
    "identifiers": {
      "tillNumber": "796980711"
    }
  }
}

​
Fields

FieldTypeRequiredDescription
identifierTypestringYesMust be "paytotill"
identifiers.tillNumberstringYesM-Pesa till number
All Kenyan phone numbers must be in international format starting with +254.

​
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"
    }
  }
}

​
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": "[email protected]"
  }
}

​
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: Ensure phone numbers are in correct format (+254…)
  • BTC: Ensure Lightning invoice is valid and not expired

​
Next Steps