# Payments API

> Query payment transactions recorded for an order.

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

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.