fluxa

Orders

An order is a single charge request and its lifecycle. Every charge creates one. Use these endpoints to list your orders, fetch one with its payment and settlements, and issue refunds.

The order model

See Charges for the full field list. The lifecycle status is one of:

  • Name
    created
    Type
    Description

    Persisted, awaiting a payment instruction.

  • Name
    pending
    Type
    Description

    Payment in flight (processing or awaiting confirmations).

  • Name
    paid
    Type
    Description

    Fully settled.

  • Name
    expired
    Type
    Description

    Not paid before expiry.

  • Name
    canceled
    Type
    Description

    Canceled before payment.

  • Name
    failed
    Type
    Description

    The payment attempt failed terminally.

  • Name
    refunded
    Type
    Description

    Fully refunded.

  • Name
    partially_refunded
    Type
    Description

    Part of the amount has been returned; refunded_amount is between 0 and amount.

GET/api/v1/orders

List orders

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Return a paginated list of your orders, newest first.

Optional attributes

  • Name
    status
    Type
    string
    Description

    Filter by order status (e.g. paid).

  • Name
    limit
    Type
    integer
    Description

    Page size. Default 20, max 200.

  • Name
    offset
    Type
    integer
    Description

    Records to skip. Default 0.

Request

GET
/api/v1/orders
curl -G "$BASE/api/v1/orders" \
  -d status=paid -d limit=20 \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

Response

{
  "data": [
    {
      "id": "ord_2Zx9Qw8sUaM2",
      "merchant_order_id": "order-1001",
      "channel_code": "usdt_trc20",
      "amount": "49.90",
      "refunded_amount": "0",
      "currency": "USDT",
      "status": "paid",
      "paid_at": "2026-06-11T08:30:00Z",
      "created_at": "2026-06-11T08:25:00Z"
    }
  ],
  "total": 134,
  "limit": 20,
  "offset": 0
}
GET/api/v1/orders/:id

Retrieve an order

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Fetch one of your orders by id. The response includes the latest payment attempt, any settlements (on-chain sweeps), and checkout_url — the last hosted-checkout link issued for the order, when applicable.

Request

GET
/api/v1/orders/ord_2Zx9Qw8sUaM2
curl "$BASE/api/v1/orders/ord_2Zx9Qw8sUaM2" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

Response

{
  "order": {
    "id": "ord_2Zx9Qw8sUaM2",
    "status": "paid",
    "amount": "49.90",
    "currency": "USDT",
    "channel_code": "usdt_trc20"
  },
  "payment": {
    "id": "pay_7K2mQ",
    "status": "succeeded",
    "channel_ref": "0x9f3c...a1",
    "amount": "49.90",
    "currency": "USDT"
  },
  "settlements": [
    {
      "id": "stl_4Hn8Lp",
      "status": "confirmed",
      "amount": "49.65",
      "fee": "0.25",
      "to_address": "TQmsxC...merchantWallet",
      "tx_hash": "0x7ad2...e9"
    }
  ],
  "checkout_url": ""
}
POST/api/v1/orders/:id/refund

Refund an order

Signed locally — your secret stays in this browser and is never sent or stored.

No keys yet? Create an API key pair in the merchant portal — the secret is shown only once. Open the merchant portal →

Most merchant orders settle directly on-chain to your own wallet, so fluxa never holds the funds and they are not platform-refundable (see the note below). Platform refunds apply to custodial orders, which are operator-internal.

Refund a paid (or partially refunded) order. Omit amount to refund the full remaining balance, or pass a decimal amount for a partial refund. The order becomes refunded once fully returned, otherwise partially_refunded.

Optional attributes

  • Name
    amount
    Type
    string
    Description

    Amount to refund, as a decimal string. Omit to refund the full remaining balance.

  • Name
    reason
    Type
    string
    Description

    Free-text reason recorded with the refund.

On-chain (non-custodial) orders cannot be refunded through the platform — they settle directly to your address, so fluxa never held the funds and returns 409 refund_unsupported. Refund those off-platform.

Request

POST
/api/v1/orders/ord_2Zx9Qw8sUaM2/refund
curl "$BASE/api/v1/orders/ord_2Zx9Qw8sUaM2/refund" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "10.00", "reason": "partial refund" }'

Response

{
  "order": {
    "id": "ord_2Zx9Qw8sUaM2",
    "status": "partially_refunded",
    "amount": "49.90",
    "refunded_amount": "10.00",
    "currency": "USDT"
  }
}