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.
idempotencyKey No None Selects exact checkout recovery instead of order listing. Use only with merchantId, without other query parameters. See Checkout Recovery.
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.
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 as a decimal string. Trailing zeroes are not guaranteed.
totalPaidAmountUsd string or null Total recorded payment amount as a decimal string when token decimals are known. Trailing zeroes are not guaranteed.
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.

Checkout Recovery

For a creation request sent with an idempotencyKey, use the same Merchant ID and key to check its result.

GET /api/v1/orders?merchantId=mch_your_merchant_id&idempotencyKey=order_10001

Use the usual API key and client-mode headers. This query accepts one merchantId and one idempotencyKey, without pagination or other filters.

For an unseen result, the response is:

{
  "success": true,
  "data": {
    "items": [],
    "total": 0,
    "page": 1,
    "pageSize": 1,
    "hasMore": false,
    "merchantId": "mch_your_merchant_id",
    "checkoutRecovery": {
      "state": "unseen",
      "canReplaySameKey": true
    }
  }
}

The response includes items and checkoutRecovery. The checkoutRecovery.state value describes the creation result:

  • unseen: No matching creation request was found.
  • creating: Creation has not yet produced a completed result.
  • created: The order was created and is included in items.
  • closed: This creation attempt ended without creating an order and cannot continue under this key.

items is empty for unseen, creating, and closed.

checkoutRecovery.canReplaySameKey indicates whether creation can be attempted again with the same key and identical payload. A created result returns false because the order already exists; an identical creation request can still return its original response.

For an unseen or creating result with canReplaySameKey: true, the same creation request can be retried with backoff.

For closed, a new checkout attempt uses a new idempotency key. This recovery state is separate from the order status closed.

A client timeout or a creating result does not establish that creation failed. Keep the same key when continuing recovery.

Get Order Details

Endpoint

GET /api/v1/orders/{orderId}

Parameters

Field Required Default Description
orderId Yes None Path parameter containing the Stafiel order ID.
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 as a decimal string. Trailing zeroes are not guaranteed.
totalPaidAmountUsd string Total recorded payment amount as a decimal string. Trailing zeroes are not guaranteed.
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 only the API values listed below. 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.

Handling Considerations

  • underpaid: The recorded payment is below the expected amount. Depending on your merchant policy, you may wait for an additional payment, contact the customer, or review the order before fulfillment. Check later webhooks or order status updates for any additional payment. Reaching expiresAt does not mean that a partial payment was automatically refunded.
  • overpaid: The recorded payment is above the expected amount. The expected payment threshold has been reached, so you may continue with your normal paid-order review and fulfillment process. Handle the excess amount according to your merchant policy. Any refund is a separate operation and depends on refund availability. See Refund Operations to review availability and initiate a supported refund.

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.
PreviousCheckout Sessions APINextPayments API