How to check order status, poll, and retrieve codes

After creating an order, fetch its status and details — including gift card codes when ready — using the order ID from POST /orders.

When to use this

• Required when status is pending — POST /orders returned HTTP 200 with pending and empty or missing codes. Poll until completed or failed.
• After a client timeout — Retry POST /orders with the same Idempotency-Key first; then use GET /orders/{id} if you have order_id.
• Direct top-up — Poll until delivery.status is completed or failed (no codes expected). See direct top-up orders.
• Support / account pages — Show order history and codes to the customer.

Do not use POST /orders/check for order status; that endpoint is for checking product stock.

Step 1: Request order details

Endpoint: GET https://api.cardpluspay.com/v1/orders/{id}

Replace {id} with the order_id from the create-order response (e.g. 123).

Example request

curl -X GET "https://api.cardpluspay.com/v1/orders/123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Step 2: Use the response

Completed (codes or top-up)

{
  "success": true,
  "message": "Order details retrieved successfully",
  "data": {
    "order_id": 123,
    "order_no": "ORD-2026-001",
    "status": "completed",
    "state": "completed",
    "codes": [
      { "code": "XXXX-XXXX-XXXX-XXXX", "item_code": "GOOGLE-5USD-KOXx", "denomination": "5.00" }
    ],
    "amount": 5.00,
    "created_at": "..."
  }
}

For direct_top_up orders, expect codes: [] and delivery: { "mode": "direct_top_up", "status": "completed" }.

Still processing

{
  "success": true,
  "data": {
    "order_id": 124,
    "order_no": "ORD-2026-002",
    "status": "pending",
    "state": "pending",
    "codes": [],
    "amount": 4.90
  }
}

Wait and call GET /orders/{id} again. Do not refund your customer or create a duplicate order while status is pending.

Failed

{
  "success": true,
  "data": {
    "order_id": 125,
    "status": "failed",
    "state": "failed",
    "codes": []
  }
}

Terminal failure — your API wallet is restored. Handle refund or cancellation in your application according to your policy.

Polling guidance

• Poll GET /orders/{id} until status is completed or failed.
• Use modest backoff (for example 10–30 seconds initially, increasing for long-running orders). Many orders complete within one minute; some may take longer.
• A POST /orders client timeout does not mean failure — reconcile with the same Idempotency-Key or GET /orders/{id}.
• On HTTP 409 idempotency conflict with data.order_id, poll that order ID instead of starting a new purchase.

Error handling

404 — Order not found. The ID may be wrong or the order may belong to another account. 401 — Invalid or missing API key.

← Create order · Integration Guide · List orders & balance →