# Refunds API

> Check refund status and refund history for an order.

Canonical: https://stafiel.org/documentation/developer-integration/refund-api
Version: v1.0.0

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](/documentation/merchant-operations/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.