Payments API

Use the Payments API to inspect on-chain payment transactions recorded for an order.

Endpoint

GET /api/v1/orders/{orderId}/payments

Parameters

Field	Required	Default	Description
orderId	Yes	None	Path parameter. 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/payments?merchantId=mch_your_merchant_id" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

Success Response

{
  "success": true,
  "data": [
    {
      "orderId": "ord_your_order_id",
      "txHash": "0xabc123...",
      "fromAddress": "0x1111111111111111111111111111111111111111",
      "toAddress": "0x2222222222222222222222222222222222222222",
      "tokenAddress": "0x...",
      "amountUsd": "49.00",
      "confirmations": 24,
      "isConfirmed": true,
      "blockNumber": "12345678",
      "txLogIndex": "0",
      "createdAt": "2026-05-19T12:05:00.000Z",
      "updatedAt": "2026-05-19T12:06:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
orderId	string	Stafiel order ID associated with the payment record.
txHash	string or null	On-chain transaction hash.
fromAddress	string or null	Customer source address when available.
toAddress	string or null	Order payment address or contract address.
tokenAddress	string or null	Token contract or mint address.
amountUsd	string or null	Recorded stablecoin payment amount displayed to 2 decimals.
confirmations	number	Confirmation count currently recorded by Stafiel.
isConfirmed	boolean	Whether Stafiel currently treats the payment as confirmed.
blockNumber	string or null	Block number as a string when available.
txLogIndex	string or null	Log index as a string when available.
createdAt	string	ISO 8601 creation timestamp.
updatedAt	string	ISO 8601 update timestamp.

Confirmation

isConfirmed indicates whether Stafiel currently considers the recorded payment confirmed. Do not treat an early detected payment as final until order status and confirmation state meet your business requirements.

Chain Address Formats

EVM addresses use 0x.... Solana addresses use base58 public keys. Tron addresses use base58 T....

Error Responses

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.