# Check payout status

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

Retrieves the current state of a payout order. Use this to poll for the outcome after sending a payout.

{% hint style="info" %}
This is a read-only operation that uses `POST` with a query parameter. No request body is required.
{% endhint %}

### Request

#### Headers

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

#### Query parameters

<table><thead><tr><th width="149.783203125">Name</th><th width="140.455078125">Type</th><th width="168.72265625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>ExternalID</code></td><td>string</td><td>yes</td><td>The <code>externalID</code> you submitted when sending the payout.</td></tr></tbody></table>

#### Example request

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```bash
curl -X POST "https://api-sandbox.nexterpay.io/Payouts/GetPayoutMobileMoneyOrderByExternalID?ExternalID=payout-1778195563528" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}

```javascript
const externalID = "payout-1778195563528";

const response = await fetch(
  `https://api-sandbox.nexterpay.io/Payouts/GetPayoutMobileMoneyOrderByExternalID?ExternalID=${externalID}`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`
    }
  }
);

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

{% endtab %}
{% endtabs %}

### Response

#### Response fields

| Field              | Type          | Description                                |
| ------------------ | ------------- | ------------------------------------------ |
| `orderID`          | string (UUID) | Nexterpay's identifier for this payout.    |
| `externalID`       | string        | Echo of your `externalID`.                 |
| `validationStatus` | string        | Current lifecycle state. See Key concepts. |
| `amount`           | number        | Payout amount.                             |
| `currency`         | string        | Payout currency.                           |
| `operator`         | string        | Payment provider used for this payout.     |
| `countryCode`      | string        | Country code.                              |

#### Example responses

{% tabs %}
{% tab title="200  Pending" %}

```json
{
    "orderID": "b6b44049-b088-4f1e-abd5-f4e3862f18a7",
    "externalID": "payout-1778195563528",
    "senderID": "cf0b664c-f672-41da-9170-7c273921b8f8",
    "transactionOut": [
        {
            "orderID": "b6b44049-b088-4f1e-abd5-f4e3862f18a7",
            "name": "John doejao",
            "address": "123 Street Douala",
            "email": "test@email.com",
            "mobile_number": "237670000000",
            "operator": "Orange",
            "account_number": "12345678901",
            "currency": "XAF",
            "countryCode": "CM",
            "amount": 120.00,
            "validationStatus": "Pending",
            "datetime": "2026-05-07T23:12:45",
            "bank_reference": "",
        }
    ],
    "tradingOrderStatus": "PayOutExternalPending"
}
```

The payout has been accepted and is awaiting processing.
{% endtab %}

{% tab title="200 - Processing" %}

```json
{
  "orderID": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "externalID": "payout-20260423-000045",
  "validationStatus": "Processing",
  "amount": 500,
  "currency": "XAF",
  "operator": "Orange",
  "countryCode": "CM"
}
```

Nexterpay is settling with the payment provider.
{% endtab %}

{% tab title="200 -Success" %}

```json
{
  "orderID": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "externalID": "payout-20260423-000045",
  "validationStatus": "completed",
  "amount": 500,
  "currency": "XAF",
  "operator": "Orange",
  "countryCode": "CM"
}
```

Funds have been delivered to the recipient.
{% endtab %}

{% tab title="200 - Failed" %}

```json
{
  "orderID": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "externalID": "payout-20260423-000045",
  "validationStatus": "Failed",
  "amount": 500,
  "currency": "XAF",
  "operator": "Orange",
  "countryCode": "CM"
}
```

The payout did not complete. Call Get Order Errors with the `orderID` for diagnostic details.
{% endtab %}

{% tab title="404 Not Found" %}

```json
{
  "error": "OrderNotFound",
  "message": "No payout order found for the provided externalID."
}
```

{% endtab %}
{% endtabs %}

### Validation status reference

| Status       | Type      | Meaning                                   |
| ------------ | --------- | ----------------------------------------- |
| `Pending`    | In-flight | Payout accepted; awaiting processing.     |
| `Processing` | In-flight | Settlement in progress with the provider. |
| `Success`    | Terminal  | Funds delivered to the recipient.         |
| `Failed`     | Terminal  | Payout did not complete.                  |
| `Cancelled`  | Terminal  | Payout was cancelled before completion.   |

For full lifecycle details, see Key concepts → validationStatus.

### Polling strategy

After sending a payout, poll this endpoint until the order reaches a terminal state (`Success`, `Failed`, or `Cancelled`).

A reasonable backoff schedule:

* First check: 5 seconds after send
* Subsequent checks: 10s, 30s, 60s
* Cap at 60s intervals
* Give up after \~10 minutes and call Get Order Errors for diagnostic details

{% hint style="info" %}
**Tip:** To query a payout sent days or weeks ago, simply pass its `externalID`. There is no time limit on retrieving historical order status.
{% endhint %}

### Common errors

| Error                 | Cause                                                | Fix                                                                                                                                                                       |
| --------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OrderNotFound` (404) | The `externalID` does not match any existing payout. | Confirm the `externalID` is correct. If you suspect a network failure during send, the payout may not have been created — retry the send call with the same `externalID`. |
| `TokenExpired` (401)  | 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/check-payout-status.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.