Refunds API

Check refund status and refund history for an order.

Use the Refunds API to check refund availability and inspect verified refund records for an order.

Refund Status

Endpoint

GET /api/v1/orders/{orderId}/refund-status

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/refund-status?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": {
    "hasMerchantRefunded": false,
    "hasAnyRefunded": false,
    "isWithinWindow": true,
    "windowEndsAt": "2026-05-21T12:00:00.000Z",
    "refundableAmountUsd": "49.00",
    "hasPlatformRefunded": false,
    "isInitialized": true,
    "canRefund": true,
    "totalMerchantRefundAmountUsd": "0.00",
    "totalPlatformRefundAmountUsd": "0.00"
  }
}

Status Response Fields

Field	Type	Description
`hasMerchantRefunded`	boolean	Whether a merchant refund has been recorded.
`hasAnyRefunded`	boolean	Whether any successful refund has been recorded.
`isWithinWindow`	boolean	Whether the merchant after-sales window is still open.
`windowEndsAt`	string or omitted	ISO 8601 after-sales window end time when still inside the window.
`refundableAmountUsd`	string or omitted	Current refundable amount displayed to 2 decimals.
`hasPlatformRefunded`	boolean	Whether a platform-initiated refund has been recorded.
`isInitialized`	boolean	Whether the payment contract or program state is initialized.
`canRefund`	boolean	Whether refund is currently available after initialization, window, amount, network, and refund-history checks.
`totalMerchantRefundAmountUsd`	string	Total merchant refund amount displayed to 2 decimals.
`totalPlatformRefundAmountUsd`	string	Total platform-initiated refund amount displayed to 2 decimals.

Use canRefund as the API signal for whether a refund can currently be submitted through Stafiel. Do not infer refund eligibility from order status alone.

Refund History

Endpoint

GET /api/v1/orders/{orderId}/refund-history

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

The response lists successful refund records, including refund amount, transaction hash, refund initiator, verification status, and refund metadata where available.

The endpoint returns all successful refund records for the order in one array. No pagination parameters apply.

Success Response

{
  "success": true,
  "data": {
    "refundHistory": [
      {
        "refundAmountUsd": "10.00",
        "transactionHash": "0xabc123...",
        "txHash": "0xabc123...",
        "refundMeta": [
          {
            "recipient": "0x1111111111111111111111111111111111111111",
            "amountUsd": "10.00",
            "originalPaymentHash": "0xpayment..."
          }
        ],
        "refundBy": "merchant",
        "isVerified": true,
        "verifiedAt": "2026-05-19T12:12:00.000Z",
        "status": "refunded",
        "createdAt": "2026-05-19T12:10:00.000Z"
      }
    ],
    "status": "refunded",
    "chainName": "base",
    "chainId": 8453
  }
}

History Response Fields

Field	Type	Description
`refundHistory`	array	Successful refund records for the order.
`status`	string	Latest refund status when refund history exists.
`chainName`	string	Canonical public chain label.
`chainId`	number	Numeric chain ID.
`refundAmountUsd`	string	Refunded amount displayed to 2 decimals.
`txHash`	string or omitted	On-chain refund transaction hash. Use this field for new integrations.
`transactionHash`	string or omitted	Compatibility alias for `txHash`.
`refundMeta`	array	Per-recipient refund allocation details when available.
`refundBy`	string or null	Refund initiator, such as `merchant` or `platform`.
`isVerified`	boolean	Whether the refund has been verified on-chain.
`verifiedAt`	string or omitted	ISO 8601 verification timestamp.
`createdAt`	string or omitted	ISO 8601 creation timestamp.

API Boundaries

The public Refunds API exposes refund status and successful refund history for an order. It does not submit refunds. Use the Merchant Dashboard to operate supported refunds. See Refund Operations.

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 or refund record does not exist or is not visible.
`409`	`REFUND_NOT_SUPPORTED`	Refund is not supported for this chain.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Retry after the indicated time.