# Send a payout

## Send a payout

Endpoint: <mark style="color:red;">`POST`</mark> `/Payouts/PayoutMobileMoney`

Disburses funds to one or more recipients. This endpoint debits your Nexterpay wallet and routes the payout to the recipient's chosen payment provider.

{% hint style="warning" %}
Check your available balance via Get Ledger Balance before sending. Payouts exceeding your balance will fail.
{% endhint %}

### PayOut Request

#### Headers

<table><thead><tr><th>Name</th><th width="216.8857421875">Type</th><th>Value</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td>String</td><td><code>application/json</code></td></tr><tr><td><code>Authorization</code></td><td>String</td><td><code>Bearer &#x3C;token></code></td></tr></tbody></table>

#### Body

<table><thead><tr><th width="153.8359375">Field</th><th width="150.2353515625">Type</th><th width="110.5859375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>externalID</code></td><td>string</td><td>yes</td><td>Unique payout ID generated by you. See Key concepts.</td></tr><tr><td><code>senderID</code></td><td>string (UUID)</td><td>yes</td><td>From <a href="https://app.gitbook.com/o/IxFtW2iNx95uJW8nJNhT/s/8gv5innHSaMBGpSTwYJp/~/edit/~/changes/8/payout/add-a-sender">Add a sender.</a></td></tr><tr><td><code>transactionOut</code></td><td>array of objects</td><td>yes</td><td>One entry per recipient. Currently supports a single recipient per call.</td></tr></tbody></table>

#### `transactionOut[]` object

<table><thead><tr><th width="161.3115234375">Field</th><th width="156.162109375">Type</th><th width="135.96484375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>string</td><td>yes</td><td>Recipient's full name.</td></tr><tr><td><code>address</code></td><td>string</td><td>yes</td><td>Recipient's address.</td></tr><tr><td><code>email</code></td><td>string</td><td>yes</td><td>Recipient's email.</td></tr><tr><td><code>mobile_number</code></td><td>string</td><td>yes</td><td>Full mobile number <strong>including country code</strong> (e.g., <code>237670000000</code>). Note <code>snake_case</code>.</td></tr><tr><td><code>operator</code></td><td>string</td><td>yes</td><td>Payment provider (case-sensitive). Validate via Get MM Operators.</td></tr><tr><td><code>account_number</code></td><td>string</td><td>yes</td><td>Recipient's account number with the provider. Note <code>snake_case</code>.</td></tr><tr><td><code>currency</code></td><td>string (ISO 4217)</td><td>yes</td><td>e.g., <code>XAF</code>.</td></tr><tr><td><code>countryCode</code></td><td>string (ISO 3166-1 alpha-2)</td><td>yes</td><td>e.g., <code>CM</code>.</td></tr><tr><td><code>amount</code></td><td>number</td><td>yes</td><td>Payout amount in the local currency unit.</td></tr></tbody></table>

## Example request

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://api-sandbox.nexterpay.io/Payouts/PayoutMobileMoney" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalID": "payout-1778191899329",
    "senderID": "7f3e2a1b-9c8d-4e5f-a0b1-c2d3e4f5a6b7",
    "transactionOut": [
      {
        "name": "Amina Ngono",
        "address": "12 Rue de la Paix, Douala",
        "email": "amina.ngono@example.com",
        "mobile_number": "237670000000",
        "operator": "Orange",
        "account_number": "12345678901",
        "currency": "XAF",
        "countryCode": "CM",
        "amount": 500
      }
    ]
  }'
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "externalID": "payout-1778191899329",
  "senderID": "7f3e2a1b-9c8d-4e5f-a0b1-c2d3e4f5a6b7",
  "transactionOut": [
    {
      "name": "Amina Ngono",
      "address": "12 Rue de la Paix, Douala",
      "email": "amina.ngono@example.com",
      "mobile_number": "237670000000",
      "operator": "Orange",
      "account_number": "12345678901",
      "currency": "XAF",
      "countryCode": "CM",
      "amount": 500
    }
  ]
}
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  "https://api-sandbox.nexterpay.io/Payouts/PayoutMobileMoney",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      externalID: "payout-1778191899329",
      senderID: "7f3e2a1b-9c8d-4e5f-a0b1-c2d3e4f5a6b7",
      transactionOut: [{
        name: "Amina Ngono",
        address: "12 Rue de la Paix, Douala",
        email: "amina.ngono@example.com",
        mobile_number: "237670000000",
        operator: "Orange",
        account_number: "12345678901",
        currency: "XAF",
        countryCode: "CM",
        amount: 500
      }]
    })
  }
);

const data = await response.json();
```

{% endtab %}
{% endtabs %}

### Response

#### Example responses

{% tabs %}
{% tab title="201 Created" %}

```json
{
    "orderID": "7ef84fbd-9893-4a45-ad03-3e38bc207f78",
    "externalID": "payout-1778191899329",
    "senderID": "cf0b664c-f672-41da-9170-7c273921b8f8",
    "transactionOut": [
        {
            "orderID": "7ef84fbd-9893-4a45-ad03-3e38bc207f78",
            "name": "Amina Ngono",
            "address": "123 Street Douala",
            "email": "amina.ngono@example.com",
            "mobile_number": "237670000000",
            "operator": "Orange",
            "account_number": "12345678901",
            "currency": "XAF",
            "countryCode": "CM",
            "amount": 150.00,
            "validationStatus": "Pending",
            "datetime": "2026-05-07T22:11:41",
            "bank_reference": "",
        }
    ],
    "tradingOrderStatus": "PayOutExternalPending"
}
```

{% endtab %}

{% tab title="400 - Insufficient funds" %}

```json
{
    "type": "Create Order Error",
    "title": "Order Error",
    "status": 400,
    "detail": "Insufficient Cleared Balance. Requested: 5000.00 Available: 143.000000"
}
```

{% endtab %}

{% tab title="400 Sender ID does not exist" %}

```json
{
    "type": "Create Order Error",
    "title": "Order Error",
    "status": 400,
    "detail": "Sender ID does not Exists: 00000000-0000-0000-0000-000000000000",
    "traceId": "40004374-000d-9500-b63f-84710c7967bb"
}
```

{% endtab %}
{% endtabs %}

### What happens next

After a successful `201 Created`, Nexterpay routes the payout to the recipient's payment provider. The recipient receives the funds once settlement completes- in seconds

To track the outcome, poll the [Check payout status endpoint](/payout/check-payout-status.md) with the same `externalID`.

### Common errors

| Error                     | Cause                                       | Fix                                                                                                                                          |
| ------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `InsufficientFunds`       | Wallet balance below payout amount.         | Check balance via Get Ledger Balance. Top up your wallet.                                                                                    |
| `ExternalIDAlreadyExists` | Reusing an `externalID`.                    | Generate a fresh `externalID`. If retrying after a timeout, call Check payout status first to verify whether the payout was already created. |
| `SenderNotFound`          | `senderID` is invalid or was never created. | Confirm the `senderID` is correct, or call Add a sender first.                                                                               |
| `InvalidOperator`         | Operator name mis-cased or not supported.   | Fetch valid operators via Get MM Operators.                                                                                                  |
| `TokenExpired`            | Bearer token past its lifetime.             | Re-fetch a token via Authentication.                                                                                                         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nexterpay.io/payout/send-a-payout.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.