Settlements API

Use the Settlements API to query settlement records for an order.

Endpoint

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

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/settlement?merchantId=mch_your_merchant_id" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

If no settlement record exists yet, data can be null.

Success Response

{
  "success": true,
  "data": {
    "txHash": "0xabc123...",
    "merchantAmount": "48.51",
    "platformAmount": "0.49",
    "status": "settled",
    "isVerified": true,
    "merchantAddress": "0x3333333333333333333333333333333333333333",
    "createdAt": "2026-05-19T12:20:00.000Z",
    "updatedAt": "2026-05-19T12:20:30.000Z"
  }
}

Response Fields

Field	Type	Description
txHash	string or null	Settlement transaction hash.
merchantAmount	string or null	Amount settled to the merchant wallet, displayed to 2 decimals.
platformAmount	string or null	Platform fee amount, displayed to 2 decimals.
status	string or null	Settlement status: pending, settled, or failed.
isVerified	boolean or null	Whether the settlement record has been verified.
merchantAddress	string or null	Merchant settlement address snapshot for the order.
createdAt	string	ISO 8601 creation timestamp.
updatedAt	string or null	ISO 8601 update timestamp.

Settlement Address Snapshot

The merchant settlement address is taken from the order's creation snapshot. A later wallet configuration change does not rewrite the settlement address for an existing order.

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.