# Check PayIn status

Retrieves the current state of a PayIn order. Use this to poll for the outcome of a transaction after creating it.

Endpoint: <mark style="color:$danger;">**POST**</mark> `/PayInMobileMoney/GetPayInMobileMoneyOrderByExternalID`

{% 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="242.208984375">Name</th><th width="211.4853515625">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="159.0841064453125">Name</th><th width="176.3104248046875">Type</th><th width="133.1141357421875">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 creating the PayIn.</td></tr></tbody></table>

#### Example request

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

```bash
curl -X POST "https://api-sandbox.nexterpay.io/PayInMobileMoney/GetPayInMobileMoneyOrderByExternalID?ExternalID=payin-20260423-000123" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const externalID = "payin-20260423-000123";

const response = await fetch(
  `https://api-sandbox.nexterpay.io/PayInMobileMoney/GetPayInMobileMoneyOrderByExternalID?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 transaction. |
| `externalID`       | string        | Echo of your `externalID`.                   |
| `validationStatus` | string        | Current lifecycle state. See Key concepts.   |
| `amount`           | number        | Transaction amount.                          |
| `currency`         | string        | Transaction currency.                        |
| `operator`         | string        | Mobile Money operator.                       |
| `countryCode`      | string        | Country code.                                |

#### Example responses

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

```json
{
    "orderID": "787bd3ee-bd27-4e1b-97f1-0e30c286e277",
    "externalID": "payin-1778194000964",
    "transactionIn": {
        "orderID": "787bd3ee-bd27-4e1b-97f1-0e30c286e277",
        "firstName": "Ayo",
        "lastName": "Adana",
        "email": "testtty@email.com",
        "mobileCountryCode": 237,
        "mobileNumber": "670000000",
        "description": "Test Top Up",
        "currency": "XAF",
        "countryCode": "CM",
        "operator": "Orange",
        "amount": 100.00,
        "mobileMoneyUrl": "",
        "validationStatus": "Pending",
        "extras": null
    },
    "tradingOrderStatus": "PayInExternalPending"
}
```

The customer has not yet approved the debit on their device.
{% endtab %}

{% tab title="200  Processing" %}

```json
{
  "orderID": "c9a1f8e0-4b3c-4b9e-8a2d-5e6f7a8b9c0d",
  "externalID": "payin-20260423-000123",
  "validationStatus": "Processing",
  "amount": 100,
  "currency": "XAF",
  "operator": "Orange",
  "countryCode": "CM"
}
```

Customer has approved. Nexterpay is settling with the operator.
{% endtab %}

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

```json
{
  "orderID": "c9a1f8e0-4b3c-4b9e-8a2d-5e6f7a8b9c0d",
  "externalID": "payin-20260423-000123",
  "validationStatus": "Success",
  "amount": 100,
  "currency": "XAF",
  "operator": "Orange",
  "countryCode": "CM"
}
```

Funds have moved successfully. Update your records.
{% endtab %}

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

```json
{
  "orderID": "c9a1f8e0-4b3c-4b9e-8a2d-5e6f7a8b9c0d",
  "externalID": "payin-20260423-000123",
  "validationStatus": "Failed",
  "amount": 100,
  "currency": "XAF",
  "operator": "Orange",
  "countryCode": "CM"
}
```

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

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

```json
{
    "orderID": "00000000-0000-0000-0000-000000000000",
    "externalID": null,
    "transactionIn": null,
    "tradingOrderStatus": 0
}
```

{% endtab %}
{% endtabs %}

### Validation status reference

| Status       | Type      | Meaning                                      |
| ------------ | --------- | -------------------------------------------- |
| `Pending`    | In-flight | Order accepted; awaiting customer action.    |
| `Processing` | In-flight | Settlement in progress with the operator.    |
| `completed`  | Terminal  | Funds moved.                                 |
| `Failed`     | Terminal  | Transaction did not complete.                |
| `Cancelled`  | Terminal  | Transaction was cancelled before completion. |

For full lifecycle details, see [validationStatus](/core-concepts.md#validationstatus-the-state-of-every-transaction).

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

### Common errors

<table><thead><tr><th width="187.7603759765625">Error</th><th>Cause</th><th>Fix</th></tr></thead><tbody><tr><td><code>OrderNotFound</code> (404)</td><td>The <code>externalID</code> does not match any existing order.</td><td>Confirm the <code>externalID</code> is correct. If you suspect a network failure during create, the order may not have been created - retry the create call with the same <code>externalID</code>.</td></tr><tr><td><code>TokenExpired</code> (401)</td><td>Bearer token past its lifetime.</td><td>Re-fetch a token via Authentication.</td></tr></tbody></table>


---

# 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/payin/check-payin-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.