Quickstart

This guide walks you from a fresh account to your first paid order. You'll create an API key, sign a request, create a charge, and learn how to be notified when it is paid.

1. Create an API key

Sign in to the merchant portal and create an API key pair. You'll get a key id (pk_test_… for sandbox, pk_live_… for production) and a secret (sk_…) that is shown only once. Start with a pk_test_ key — it runs the full flow without moving real money.

2. Pick a channel

A charge runs on an on-chain channel — a stablecoin asset like USDT or USDC on TRON or a major EVM chain (Ethereum, Base, Polygon, Arbitrum, BNB Chain). Settlement is non-custodial: the net settles on-chain straight to your own wallet address. List the channels enabled for your account to get their code values:

# See Authentication for how TS / SIG are computed.
curl "$BASE/api/v1/channels" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

3. Create a charge

Create a charge for an amount in a currency on a channel. merchant_order_id is your idempotency key — reusing it returns the same order instead of creating a duplicate.

curl "$BASE/api/v1/charges" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "order-1001",
    "amount": "49.90",
    "currency": "USDT",
    "network": "tron",
    "subject": "Pro plan"
  }'

{
  "order": {
    "id": "ord_2Zx9Qw8sUaM2",
    "merchant_order_id": "order-1001",
    "status": "created",
    "amount": "49.90",
    "currency": "USDT",
    "channel_code": "usdt_trc20"
  },
  "payment": { "id": "pay_7K2m", "status": "initiated" },
  "instruction": {
    "type": "crypto_address",
    "deposit_address": "TQ5...Xy9",
    "amount_due": "49.90",
    "chain": "usdt_trc20",
    "asset": "USDT",
    "required_confirmations": 19
  },
  "idempotent": false
}

4. Direct the payer

Act on the instruction:

• crypto_address — what an on-chain channel returns. Show the payer deposit_address, amount_due, chain/asset, and the required confirmations.

The redirect and client_secret instruction types also exist in the API, but they appear only for operator-internal custodial channels — external merchants on non-custodial on-chain settlement always get crypto_address.

5. Get notified when it's paid

Don't poll in production — register a webhook URL in the portal and fluxa will POST you a signed payment.succeeded event the moment the order settles. See Webhooks to verify the signature. You can also fetch an order any time:

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

Next steps