Orders

`GET /api/v1/topups/orders`

Returns a paginated list of your client's top-up orders, sorted by most recent first.

Request

curl "https://api.octopuscards.io/api/v1/topups/orders?status=PENDING&page=1&per_page=50" \
  -H "Authorization: Bearer <token>"

Query Parameters

Key	Type	Required	Description
`page`	integer	No	Page number (1-based). Default: `1`.
`per_page`	integer	No	Items per page (1–500). Default: `50`.
`status`	string	No	Filter by status. One of `PENDING`, `DELIVERED`, `FAILED`, `CANCELLED`, `RECHARGED`.
`product_id`	integer	No	Filter to a single product. Must be `> 0` when supplied.
`country`	string	No	Filter by country code (ISO 3166-1 alpha-3, uppercase, e.g. `IND`).
`client_reference`	string	No	Exact-match lookup against the `client_reference` you supplied on create. Recommended path for fetching an order by your own key — at most one result.

Response

[
  {
    "id": 9123456,
    "client_reference": "CAMPAIGN_DEC_24",
    "product_id": 4218,
    "product_name": "PUBG Mobile UC",
    "variant_name": "325 UC",
    "country_code": "GLO",
    "amount": 4.7405,
    "currency": "USD",
    "status": "PENDING",
    "status_text": "Order submitted for fulfilment",
    "created_at": "2026-05-19T14:30:00Z"
  },
  {
    "id": 9123440,
    "product_id": 4218,
    "product_name": "PUBG Mobile UC",
    "variant_name": "325 UC",
    "country_code": "GLO",
    "amount": 4.7405,
    "currency": "USD",
    "status": "DELIVERED",
    "status_text": "Top-up delivered",
    "transaction_id": 7401120,
    "created_at": "2026-05-19T13:55:00Z",
    "completed_at": "2026-05-19T13:55:08Z"
  }
]

Response Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total matching orders
`X-Total-Pages`	Total pages
`X-Page-Size`	Items in current page
`X-Has-More`	`true` if more pages exist

Enumerations

See the Create Order page for the status enum.

Response Fields

Key	Type	Description
`id`	integer	Server-issued order ID.
`client_reference`	string	Echo of the value you supplied on create (omitted if you didn't supply one).
`product_id`	integer	The product the order was placed against.
`product_name`	string	Display name of the product (e.g. "PUBG Mobile UC", "Airtel India").
`variant_name`	string	Display name of the variant Octopus Cards matched (e.g. "325 UC"). The variant_id itself is internal and not surfaced.
`country_code`	string	ISO 3166-1 alpha-3 country code of the product (e.g. `IND`, `GLO`).
`amount`	number	Amount debited from the wallet.
`currency`	string	Wallet/product currency.
`status`	string	Current status.
`status_text`	string	Latest human-readable detail.
`transaction_id`	integer	Wallet transaction ID (after debit).
`created_at`	string	RFC 3339.
`completed_at`	string	RFC 3339. Present only when terminal.

Errors

401 Unauthorized — missing JWT.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

`GET /api/v1/topups/orders/:id`

Returns a single order. For orders still in PENDING state, this endpoint refreshes the status from fulfilment before responding — so it returns the freshest known state, not a snapshot from your last write.

Request

curl "https://api.octopuscards.io/api/v1/topups/orders/9123456" \
  -H "Authorization: Bearer <token>"

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Order ID (path parameter). Returned as `id` from order creation.

Response

{
  "id": 9123456,
  "client_reference": "CAMPAIGN_DEC_24",
  "product_id": 4218,
  "product_name": "PUBG Mobile UC",
  "variant_name": "325 UC",
  "country_code": "GLO",
  "amount": 4.7405,
  "currency": "USD",
  "status": "DELIVERED",
  "status_text": "Top-up delivered",
  "transaction_id": 7401123,
  "input_data": {
    "player_id": "5123456789",
    "server": "asia"
  },
  "created_at": "2026-05-19T14:30:00Z",
  "completed_at": "2026-05-19T14:31:12Z"
}

Response Fields

See the Create Order response table. The list and detail responses share the same shape.

Polling cadence. A reasonable poll interval is 5–10 seconds for the first minute, then back off to 30–60 seconds. Top-ups typically resolve within seconds. An order that stays PENDING longer is Octopus Cards automatically retrying transient fulfilment issues — it isn't stuck. Stop foreground polling after a few minutes; rely on the notification email (or future webhook events) for the terminal transition. The server-side status check inside this endpoint has its own 15-second timeout, so polling faster than 5 seconds gives no benefit.

Errors

400 Bad Request — id is not a valid integer.

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "Invalid order ID"
  }
}

`PATCH /api/v1/topups/orders/:id/notification-email`

Attaches (or updates) the email address that will be notified when the order reaches a terminal status. Only accepted while the order is still in flight — once DELIVERED, FAILED, or CANCELLED, the email is locked.

Use this when your customer enters their email after placing the order (e.g. in a "where should we send the receipt?" follow-up screen).

Request

curl -X PATCH "https://api.octopuscards.io/api/v1/topups/orders/9123456/notification-email" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com"
  }'

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Order ID (path parameter).
`email`	string	Yes	Email address. Max 254 characters.

Response

{
  "success": true,
  "message": "Notification email updated successfully"
}

Response Fields

Key	Type	Description
`success`	boolean	Always `true` on success.
`message`	string	Confirmation string.

Errors

400 Bad Request — email missing, empty, or too long.

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "email is required"
  }
}

Other messages: "email is too long (max 254 characters)", "Invalid order ID", "Invalid request body".

On this page