> ## 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.

# Order lifecycle

> Every status an order moves through, and when to stop polling

An order moves through a small number of states. Knowing which are final is the difference
between fulfilling an order correctly and fulfilling one that never got paid.

## The flow

<Steps>
  <Step title="Initiated">
    [Create an order](/api-reference/orders/create-order) returns `statusId: 1`,
    `status: "Initiated"`. No money has been requested yet — the customer hasn't picked a method.
  </Step>

  <Step title="Pending">
    [Pay an order](/api-reference/orders/pay-order) moves it to `statusId: 2`. The exact message
    depends on the method: `pending-authenticaion` for a card awaiting 3-D Secure,
    `pending bank notification` for a bank transfer awaiting funds.
  </Step>

  <Step title="Final">
    The order settles as `Successful` (`statusId: 5`) or fails. At this point
    `isFinalStatus` is `true` and you can stop polling.
  </Step>
</Steps>

## Status values

| `statusId` | `status`     | Final? | Meaning                                                         |
| ---------- | ------------ | ------ | --------------------------------------------------------------- |
| `1`        | `Initiated`  | No     | Order created, no payment attempted                             |
| `2`        | `Pending`    | No     | Payment submitted, awaiting authentication or bank confirmation |
| `5`        | `Successful` | Yes    | Payment completed and settled                                   |

<Note>
  Treat `isFinalStatus` in the [order status](/api-reference/orders/get-order-status) response as
  authoritative rather than hard-coding the `statusId` list — it is the field the API is telling
  you to branch on.
</Note>

## Response codes

`statusCode` appears on every response and is a string, not a number.

| Code  | Meaning                                                |
| ----- | ------------------------------------------------------ |
| `00`  | Successful / operation successful                      |
| `01`  | Order created                                          |
| `02`  | Pending — awaiting authentication or bank notification |
| `13`  | Order not found, or order payment already pending      |
| `400` | Payload could not be decrypted                         |
| `401` | Missing or invalid API key                             |
| `604` | Payment link not found                                 |

## Polling

After [Pay an order](/api-reference/orders/pay-order), poll
[Get order status](/api-reference/orders/get-order-status) until `isFinalStatus` is `true`.

<Steps>
  <Step title="Poll every few seconds for the first two minutes">
    Most card payments resolve within seconds of the customer completing 3-D Secure.
  </Step>

  <Step title="Back off after that">
    Bank transfers depend on the customer actually sending the money, which can take much longer.
  </Step>

  <Step title="Stop after about five minutes">
    If the status still has not changed, treat the order as genuinely pending. Tell the customer
    you will confirm once the payment completes, and reconcile from your backend later — do not
    tell them it failed.
  </Step>
</Steps>

The response also carries `requeryNeeded`, a hint from the API that the status is not yet
settled and another poll is worthwhile.

<Warning>
  Poll from your **backend** before you fulfil an order, and confirm with
  [Verify an order](/api-reference/verification/verify-order) using your secret key. A status
  read with a public key is fine for updating your UI, but it is not proof of payment.
</Warning>

## Fees

Fees are added on top of the order amount, not deducted from it. An order for `500` with a fee
of `30` charges the customer `530` — the `totalChargedAmount` in the status response.

Check the fee before you charge with
[Get order fee](/api-reference/orders/get-order-fee), which breaks it down into
`subsidiaryFee` (your share) and `customerFee` (theirs).