> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2.reeple.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get order status

> Poll an order until its payment reaches a final status

Returns the current state of an order and every payment attempt made against it. Poll this
after [Pay an order](/api-reference/orders/pay-order) until `isFinalStatus` is `true`.

## Endpoint

```
POST https://api-v4.reeple.ai/charge/order/status
```

Authenticate with your **public key**. See [Authentication](/api-reference/authentication).

<Note>
  This endpoint is safe to call from a context that holds your public key, which makes it
  convenient for updating a checkout UI. It is **not** proof of payment — confirm with
  [Verify an order](/api-reference/verification/verify-order) from your backend before you
  fulfil.
</Note>

## Request body

| Field  | Type   | Description                                                             |
| ------ | ------ | ----------------------------------------------------------------------- |
| `data` | String | **Required.** The RSA-[encrypted](/encryption) payload described below. |

## Payload (before encryption)

| Field       | Type   | Description                                                                                   |
| ----------- | ------ | --------------------------------------------------------------------------------------------- |
| `reference` | String | **Required.** The order reference from [Create an order](/api-reference/orders/create-order). |

```json theme={null}
{ "reference": "order-2026-0001" }
```

## Request example

```bash theme={null}
curl -X POST https://api-v4.reeple.ai/charge/order/status \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_PUBLIC_KEY" \
  -d '{ "data": "YOUR_ENCRYPTED_PAYLOAD" }'
```

## Response

```json theme={null}
{
  "status": "Successful",
  "statusCode": "00",
  "message": "Transaction was completed successfully",
  "data": {
    "isFinalStatus": true,
    "requeryNeeded": false,
    "requeryType": null,
    "orderSummary": {
      "id": 955219,
      "paymentReference": "RPL-A3B844129BE911F1ADC6026C64B362BB",
      "orderReference": "order-2026-0001",
      "totalChargedAmount": 530,
      "fee": 30,
      "statusId": 5,
      "status": "Successful",
      "paymentType": "C",
      "currencyId": 1,
      "paymentResponseCode": "00",
      "paymentResponseMessage": "Transaction was completed successfully",
      "providerResponseDate": null,
      "datePaymentConfirmed": null,
      "dateCreated": "2026-08-19T16:18:40",
      "narration": "Order #0001",
      "remarks": "Order initiated and created successfully"
    },
    "orderPayments": [
      {
        "orderId": 955219,
        "orderPaymentReference": "REEPLE-PAYREF-13A5C5F57856458E80EB56CA748C294A",
        "paymentOptionId": 2,
        "statusId": 5,
        "orderPaymentResponseCode": "00",
        "orderPaymentResponseMessage": "Transaction was completed successfully",
        "remarks": "Order payment initiated",
        "providerReference": "CPD5A4DAA8-C363-4179-A52F-0E8604F72494",
        "providerResponseCode": "02",
        "paymentUrl": "https://payment-v2.reeple.ai/redirect?t=aHR0cHM6Ly9jb3JlL...",
        "externalReference": "40878740125146805",
        "authOption": null,
        "saveCard": null,
        "processorProviderBank": "FCMB",
        "id": 956038,
        "dateCreated": "2026-08-19T16:18:56.144019",
        "dateUpdated": "2026-08-19T16:19:25.548306"
      }
    ]
  }
}
```

### Response fields

| Field                             | Description                                                                          |
| --------------------------------- | ------------------------------------------------------------------------------------ |
| `isFinalStatus`                   | **The field to branch on.** `true` means stop polling.                               |
| `requeryNeeded`                   | The API's own hint that another poll is worthwhile.                                  |
| `orderSummary.status`             | `Initiated`, `Pending` or `Successful`. See [Status codes](/api-reference/statuses). |
| `orderSummary.totalChargedAmount` | What the customer was actually charged, including fee.                               |
| `orderSummary.paymentType`        | The method used — `C`, `BANK-TRANSFER`, `USSD`.                                      |
| `orderPayments`                   | Every payment attempt against this order, newest last.                               |

<Warning>
  An order can have **more than one** entry in `orderPayments` — for example a failed card
  attempt followed by a successful bank transfer. Read the top-level `orderSummary` for the
  order's true state rather than assuming a single payment.
</Warning>

## While the payment is pending

```json theme={null}
{
  "status": "Pending",
  "statusCode": "02",
  "message": "pending-authenticaion",
  "data": {
    "isFinalStatus": false,
    "requeryNeeded": true,
    "orderSummary": { "statusId": 2, "status": "Pending" }
  }
}
```

## Common errors

| Code  | Message                                                     | Cause                                         |
| ----- | ----------------------------------------------------------- | --------------------------------------------- |
| `13`  | `Order not found at the moment`                             | The `reference` doesn't match an order        |
| `400` | `Something went wrong while trying to decrypt your payload` | See [Encryption](/encryption#troubleshooting) |

## Polling

See [Order lifecycle](/order-lifecycle#polling) for how often to poll and when to give up and
treat an order as genuinely pending.