> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavapay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Beneficiary Formats

> Required beneficiary object formats for each supported currency

<Tip>
  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.
</Tip>

## Bitcoin (BTC)

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

### Lightning Invoice

```json theme={null}
{
  "beneficiary": {
    "lnInvoice": "lntbs20u1p5dmy87pp5l2pm..."
  }
}
```

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

<Note>
  The invoice must be valid and not expired when the payout is processed.
</Note>

### Lightning Address

```json theme={null}
{
  "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:

```json theme={null}
{
  "beneficiary": {
    "onChainAddress": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5"
  }
}
```

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

<Warning>
  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.
</Warning>

## Nigerian Naira (NGN)

For Nigerian Naira payouts, provide complete bank account details.

```json theme={null}
{
  "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                |

<Tip>
  Use the [Name Enquiry endpoint](/api-reference/endpoint/bank-info/name-enquiry) to validate the account details before creating a quote.
</Tip>

## South African Rand (ZAR)

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

```json theme={null}
{
  "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 |

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

## 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.

```json theme={null}
{
  "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"`       |

<Warning>
  Starting **July 12, 2026**, the `network` field is **required** for all pay-to-phone KES quotes.
</Warning>

### Pay to Bill (Business Payments)

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

```json theme={null}
{
  "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              |

<Tip>
  You can validate the paybill business name using the [KES Identifier Validation endpoint](/api-reference/endpoint/quote/validate-kes-identifier). See [detailed documentation](#kes-identifier-validation) below.
</Tip>

### Pay to Till

Send money to a business till number.

```json theme={null}
{
  "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    |

<Tip>
  You can validate the till business name using the [KES Identifier Validation endpoint](/api-reference/endpoint/quote/validate-kes-identifier). See [detailed documentation](#kes-identifier-validation) below.
</Tip>

<Note>
  All Kenyan phone numbers must be in international format starting with +254.
</Note>

## 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:

```json theme={null}
{
  "identifier": "247247",
  "identifierType": "PayBill"
}
```

For Till validation:

```json theme={null}
{
  "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

```json theme={null}
{
  "status": "ok",
  "data": {
    "organization_name": "Equity Paybill Account"
  }
}
```

### Example: Validate Paybill

```bash theme={null}
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

```bash theme={null}
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"
}'
```

<Note>
  This validation endpoint is only available in the production environment.
</Note>

## Complete Quote Examples

### Example: NGN Payout

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

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

### Example: BTC Payout (Lightning Address)

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

### Example: BTC Payout (On-Chain Address)

```json theme={null}
{
  "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](/api-reference/endpoint/bank-info/name-enquiry) 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](#kes-identifier-validation) to validate business names (production only)
* **BTC**: Ensure Lightning invoice is valid and not expired

## Next Steps

* View [complete quote examples](/api-reference/quote-examples) for all currency pairs
* Learn about [webhook notifications](/webhooks/introduction) for tracking payments
* Test your integration in our [staging environment](https://staging.api.mavapay.co/api/v1)