# Create PayIn order

Initiates a Mobile Money debit against a customer's wallet. The customer receives a prompt on their device (USSD or Mobile Money app) asking them to approve the debit.

### Create PayIn Request

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

#### Headers

<table><thead><tr><th width="227.0859375">Name</th><th width="178.318359375">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="188.5224609375">Field</th><th width="149.7705078125">Type</th><th width="135.009765625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>externalID</code></td><td>string</td><td>yes</td><td>Unique transaction ID generated by you. See Key concepts.</td></tr><tr><td><code>transactionIn</code></td><td>object</td><td>yes</td><td>Transaction details. See below.</td></tr></tbody></table>

#### `transactionIn` object

| Field               | Type                        | Required | Description                                                                                             |
| ------------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `firstName`         | string                      | yes      | Customer's first name.                                                                                  |
| `lastName`          | string                      | yes      | Customer's last name.                                                                                   |
| `email`             | string                      | yes      | Customer's email address.                                                                               |
| `mobileCountryCode` | integer                     | yes      | Numeric dialing code (e.g., `237` for Cameroon).                                                        |
| `mobileNumber`      | string                      | yes      | Mobile number without country code.                                                                     |
| `description`       | string                      | no       | Free-text description shown on the ledger entry.                                                        |
| `currency`          | string (ISO 4217)           | yes      | e.g., `XAF`.                                                                                            |
| `countryCode`       | string (ISO 3166-1 alpha-2) | yes      | e.g., `CM`.                                                                                             |
| `operator`          | string                      | yes      | Mobile Money operator (case-sensitive). Validate via [Get MM Operators.](/catalog/catalog-operators.md) |
| `amount`            | number                      | yes      | Amount in the local currency unit.                                                                      |

#### Example request

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

```bash
curl -X POST "https://api-sandbox.nexterpay.io/PayInMobileMoney/PayInMobileMoney" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalID": "payin-1778194000964",
    "transactionIn": {
      "firstName": "Amina",
      "lastName": "Ngono",
      "email": "amina.ngono@example.com",
      "mobileCountryCode": 237,
      "mobileNumber": "670000000",
      "description": "Order #4521 — Premium subscription",
      "currency": "XAF",
      "countryCode": "CM",
      "operator": "Orange",
      "amount": 100
    }
  }'
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "externalID": "payin-1778194000964",
  "transactionIn": {
    "firstName": "Amina",
    "lastName": "Ngono",
    "email": "amina.ngono@example.com",
    "mobileCountryCode": 237,
    "mobileNumber": "670000000",
    "description": "Order #4521 — Premium subscription",
    "currency": "XAF",
    "countryCode": "CM",
    "operator": "Orange",
    "amount": 100
  }
}
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  "https://api-sandbox.nexterpay.io/PayInMobileMoney/PayInMobileMoney",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      externalID: "payin-1778194000964",
      transactionIn: {
        firstName: "Amina",
        lastName: "Ngono",
        email: "amina.ngono@example.com",
        mobileCountryCode: 237,
        mobileNumber: "670000000",
        description: "Order #4521 — Premium subscription",
        currency: "XAF",
        countryCode: "CM",
        operator: "Orange",
        amount: 100
      }
    })
  }
);

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 submitted `externalID`.                                                                                                 |
| `validationStatus` | string        | Initial lifecycle state. Typically `Pending`. See [Key concepts.](/core-concepts.md#validationstatus-the-state-of-every-transaction) |

#### Example responses

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

```json
{
    "orderID": "787bd3ee-bd27-4e1b-97f1-0e30c286e277",
    "externalID": "payin-1778194000964",
    "transactionIn": {
        "orderID": "787bd3ee-bd27-4e1b-97f1-0e30c286e277",
        "firstName": "Amina",
        "lastName": "Ngono",
        "email": "amina.ngono@example.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"
}
```

{% endtab %}

{% tab title="400 Bad Request" %}

```json
{
  "error": "ExternalIDAlreadyExists",
  "message": "An order with this externalID has already been submitted."
}
```

{% endtab %}

{% tab title="401 Unauthorized" %}

```json
{
  "error": "TokenExpired",
  "message": "Your token has expired. Please re-authenticate."
}
```

{% endtab %}
{% endtabs %}

### What happens next

After a successful `201 Created`, the customer receives a Mobile Money prompt on their device. They must approve the debit for the transaction to complete.

To track the outcome, poll the [Check PayIn status ](https://app.gitbook.com/o/IxFtW2iNx95uJW8nJNhT/s/8gv5innHSaMBGpSTwYJp/~/edit/~/changes/8/payin/payin/check-payin-status)endpoint with the same `externalID`.

### Common errors

| Error                     | Cause                                                             | Fix                                                                                                                                                 |
| ------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ExternalIDAlreadyExists` | Reusing an `externalID` from a previous transaction.              | Generate a fresh, unique `externalID`. If retrying after a timeout, call Check PayIn status first to verify whether the order was actually created. |
| `InvalidOperator`         | Operator name is mis-cased or not supported in the given country. | Fetch valid operators via Get MM Operators and use the exact string returned.                                                                       |
| `InvalidCountry`          | Country code not supported.                                       | Confirm support via Get Countries.                                                                                                                  |
| `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/payin/create-payin-order.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.