# Key concepts

Before you write your first integration, understand these five concepts. Each one shows up in nearly every API call you'll make — and getting them right early saves significant rework later.

### `externalID` - the unique transaction ID you generate

`externalID` is a unique string **you generate** for every transaction. Nexterpay stores it alongside the transaction and uses it as the lookup key for status endpoints.

* **You own it.** Nexterpay does not generate it — your system does.
* **It must be unique per transaction** within your merchant account. Reusing an `externalID` on a new PayIn or PayOut call will be rejected.
* **Use it as your idempotency key.** If your network call times out and you are uncertain whether the order was created, do **not** retry with a new `externalID` — retry with the same one, or call the "Get by External ID" endpoint to check status.
* **Recommended format.** A UUID v4 (e.g., `a3c8f5d6-7b12-4e9a-9d4e-1f2a3b4c5d6e`) or a prefixed deterministic ID (`payin-20260423-000123`). Length should be ≤ 64 characters.

> ⚠️ Treat `externalID` as the single source of truth linking your system's transaction record to Nexterpay's. Persist it **before** making the API call, so a network failure cannot leave you without it.

### `orderID` — the unique transaction ID Nexterpay assigns

`orderID` is a UUID generated by Nexterpay and returned in the response of a successful create call. It is useful for:

* Looking up errors on a failed order via Get Order Errors.
* Correlating server-side logs with Nexterpay support.

Both `orderID` and `externalID` identify the same transaction. Prefer `externalID` as the primary key in your application; use `orderID` for diagnostics.

### `senderID` — the reusable identifier for payout senders

For PayOut transactions, Nexterpay requires a **sender** — the legal person initiating the disbursement. You create a sender once via Add Sender and receive a `senderID` (UUID). **Reuse this `senderID`** for all subsequent payouts from the same underlying sender.

> 💡 Do not call `AddPayOutSender` on every payout. Create senders once (typically at merchant onboarding or the first time a given legal entity initiates a payout) and store the returned `senderID`.

### `validationStatus` — the state of every transaction

Both PayIn and PayOut orders carry a `validationStatus` value describing where the transaction sits in its lifecycle.

| Status       | Meaning                                                                         |
| ------------ | ------------------------------------------------------------------------------- |
| `Pending`    | Order accepted; awaiting operator confirmation or customer action.              |
| `Processing` | Nexterpay is actively settling with the operator.                               |
| `Success`    | Funds have moved successfully.                                                  |
| `Failed`     | The transaction did not complete. Call Get Order Errors for diagnostic details. |
| `Cancelled`  | The transaction was cancelled before completion.                                |

The typical lifecycle:

Pending → Processing → Success\
↘\
Failed\
Cancelled

Poll the status endpoint until you reach a terminal state (`Success`, `Failed`, or `Cancelled`). A reasonable backoff is 5 seconds, then 10 seconds, then 30 seconds, capping at 60 seconds between polls.

### Idempotency — making your integration safe to retry

Network failures happen. A request times out, a connection resets, and your server doesn't know whether the transaction was created or not. Without a strategy, you risk double-charging or double-paying customers.

Nexterpay does not currently expose a dedicated `Idempotency-Key` header. Instead, idempotency is enforced via `externalID`:

1. Generate `externalID` and persist it in your database **before** the API call.
2. Send the create request.
3. On any error (timeout, 5xx, connection reset), **do not generate a new `externalID`**. Instead, call the corresponding `Get…ByExternalID` endpoint. If the order exists, you know the create succeeded on Nexterpay's side. If not, retry with the same `externalID`.

This pattern makes your integration safe against double-charging and double-paying customers.

### API conventions

A few platform-wide conventions worth knowing:

* **HTTP methods.** Most endpoints use `POST`, including some read operations like `Get…ByExternalID`. Only `/Errors/GetOrderErrors` uses `GET`.
* **Field naming.** Most fields use camelCase. PayOut transaction details use snake\_case (`mobile_number`, `account_number`) — see the PayOut guide for details.
* **Date and time format.** ISO 8601 in UTC (e.g., `2026-04-23T10:15:22Z`).
* **Currency.** ISO 4217 codes (e.g., `XAF`, `USD`, `NGN`).
* **IDs.** UUIDs for all Nexterpay-generated identifiers. Your `externalID` can be any unique string ≤ 64 characters.


---

# 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/core-concepts.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.