Orders API

Query order lists and order details through the API.

Use the Orders API to list orders and retrieve a single order's current business state.

List Orders

Endpoint

GET /api/v1/orders

Query Parameters

Field	Required	Default	Description
`merchantId`	Yes	None	Merchant ID bound to the API key.
`page`	No	`1`	Page number. Starts from `1`.
`pageSize`	No	`20`	Number of orders per page. Maximum `100`.
`status`	No	None	Comma-separated order statuses, such as `awaiting_payment`, `underpaid`, `fullpaid`, `overpaid`, `expired`, `settled`, `full_refunded`, `closed`, or `compliance_hold`.
`chainName`	No	None	Comma-separated chain labels.
`orderId`	No	None	Search by Stafiel order ID or merchant business order reference.
`contractAddress`	No	None	Filter by payment contract or payment address.
`createdAtFrom`	No	None	ISO 8601 lower bound for order creation time.
`createdAtTo`	No	None	ISO 8601 upper bound for order creation time.
`sortBy`	No	`createdAt`	Use `createdAt`, `status`, or `amount`.
`sortOrder`	No	`desc`	Use `asc` or `desc`.

Request Example

curl "https://api.stafiel.com/api/v1/orders?merchantId=mch_your_merchant_id&page=1&pageSize=20&status=fullpaid,settled&chainName=base,eth" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

List Success Response

{
  "success": true,
  "data": {
    "items": [
      {
        "orderId": "ord_your_order_id",
        "merchantId": "mch_your_merchant_id",
        "status": "fullpaid",
        "amountUsd": "49.00",
        "totalPaidAmountUsd": "49.00",
        "chainName": "base",
        "chainId": 8453,
        "tokenSymbol": "USDC",
        "tokenAddress": "0x...",
        "tokenDecimals": 6,
        "orderAddress": "0x2222222222222222222222222222222222222222",
        "paymentUrl": "https://pay.stafiel.com/pay/ps_live_example",
        "expiresAt": "2026-05-19T12:30:00.000Z",
        "createdAt": "2026-05-19T12:00:00.000Z",
        "updatedAt": "2026-05-19T12:05:00.000Z",
        "metadata": {
          "customerReference": "CUS-8842"
        }
      }
    ],
    "chains": [],
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "hasMore": false,
    "createdAtFrom": null,
    "createdAtTo": null,
    "merchantId": "mch_your_merchant_id"
  }
}

List Response Fields

Field	Type	Description
`items`	array	Orders visible to the API key for the requested merchant and filters.
`chains`	array	Chain metadata included for filter or display context. API integrations may ignore it.
`total`	number	Total matching order count.
`page`	number	Current page number.
`pageSize`	number	Number of orders requested per page.
`hasMore`	boolean	Whether another page of results is available.
`createdAtFrom`	string or null	Applied lower creation-time filter.
`createdAtTo`	string or null	Applied upper creation-time filter.
`merchantId`	string	Merchant ID for single-merchant API key responses.

Pagination Notes

List responses use page-based pagination. For batch syncs, set createdAtTo at the start of the sync and keep that value while reading subsequent pages. This prevents newly created orders from changing the result window while your sync is in progress.

Order Item Fields

Field	Type	Description
`orderId`	string	Stafiel order ID.
`merchantId`	string	Merchant ID that owns the order.
`status`	string	Current business status of the order.
`amountUsd`	string or null	Original checkout amount.
`totalPaidAmountUsd`	string or null	Total recorded payment amount when token decimals are known.
`chainName`	string or null	Canonical public chain label.
`chainId`	number or null	Numeric chain ID when available.
`tokenSymbol`	string or null	Token symbol for the order.
`tokenAddress`	string or null	Token contract or mint address.
`tokenDecimals`	number or null	Token decimals used for amount formatting.
`orderAddress`	string or null	Payment contract or payment address.
`paymentUrl`	string or omitted	Hosted checkout URL, if still available for the order.
`expiresAt`	string	ISO 8601 expiration timestamp.
`createdAt`	string	ISO 8601 creation timestamp.
`updatedAt`	string	ISO 8601 update timestamp.
`metadata`	object or null	Sanitized order metadata.

Get Order Details

Endpoint

GET /api/v1/orders/{orderId}

Parameters

Field	Required	Default	Description
`orderId`	Yes	None	Path parameter. Stafiel order ID or supported order reference.
`merchantId`	Yes	None	Query parameter. Merchant ID bound to the API key.

Request Example

curl "https://api.stafiel.com/api/v1/orders/ord_your_order_id?merchantId=mch_your_merchant_id" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

Detail Success Response

{
  "success": true,
  "data": {
    "orderId": "ord_your_order_id",
    "merchantId": "mch_your_merchant_id",
    "status": "fullpaid",
    "amountUsd": "49.00",
    "totalPaidAmountUsd": "49.00",
    "chainName": "base",
    "chainId": 8453,
    "tokenSymbol": "USDC",
    "tokenAddress": "0x...",
    "tokenDecimals": 6,
    "orderAddress": "0x2222222222222222222222222222222222222222",
    "paymentUrl": "https://pay.stafiel.com/pay/ps_live_example",
    "expiresAt": "2026-05-19T12:30:00.000Z",
    "createdAt": "2026-05-19T12:00:00.000Z",
    "updatedAt": "2026-05-19T12:05:00.000Z",
    "metadata": {
      "customerReference": "CUS-8842"
    }
  }
}

Detail Response Fields

Field	Type	Description
`orderId`	string	Stafiel order ID.
`merchantId`	string	Merchant ID that owns the order.
`status`	string	Current business status of the order.
`amountUsd`	string	Original checkout amount.
`totalPaidAmountUsd`	string	Total recorded payment amount displayed to 2 decimals.
`chainName`	string	Canonical public chain label.
`chainId`	number or null	Numeric chain ID when available.
`tokenSymbol`	string	Token symbol for the order.
`tokenAddress`	string or null	Token contract or mint address.
`tokenDecimals`	number or null	Token decimals used for amount formatting.
`orderAddress`	string or null	Payment contract or payment address.
`paymentUrl`	string or omitted	Hosted checkout URL, if still available for the order.
`expiresAt`	string	ISO 8601 expiration timestamp.
`createdAt`	string	ISO 8601 creation timestamp.
`updatedAt`	string	ISO 8601 update timestamp.
`metadata`	object or null	Sanitized order metadata.

Order Statuses

The status field can use these values. Do not assume status changes are strictly linear; use webhooks or repeated API reads to observe the latest state.

Status	Meaning
`awaiting_payment`	The order is open and waiting for payment.
`underpaid`	Recorded payment is below the expected amount.
`fullpaid`	Recorded payment matches the expected amount.
`overpaid`	Recorded payment is above the expected amount.
`expired`	The payment window has expired.
`settled`	Settlement has been recorded.
`full_refunded`	The order has been fully refunded.
`compliance_hold`	The order is held by risk or compliance controls.
`closed`	The order is closed.

Error Responses

Error responses use this shape:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found"
  }
}

HTTP Status	Code	Meaning
`400`	`VALIDATION_ERROR`	Query parameter is invalid or unsupported.
`401`	`AUTH_FAILED`	API key is missing, invalid, or cannot access the requested merchant or order.
`403`	`AUTHORIZATION_ERROR`	Request is authenticated but not allowed.
`404`	`NOT_FOUND`	Order does not exist or is not visible.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Retry after the indicated time.