5. Quote and pay out

Request a quote

Price the USD amount the beneficiary should receive. Match source_currency and source_network to the wallet you funded.

POST /v1/payments/quotes

curl -X POST https://api-staging.checker.finance/v1/payments/quotes \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "source_currency": "USDT",
    "source_network": "TRX",
    "target_currency": "USD",
    "target_amount": "100.00"
  }'

Response — 200 OK:

{
  "quotes": [
    {
      "quote_id": "qte_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "provider": "provider-b",
      "source_currency": "USDT",
      "source_network": "TRX",
      "target_currency": "USD",
      "source_amount": "100.05",
      "target_amount": "100.00",
      "exchange_rate": "1.0005",
      "fee_amount": "0.05",
      "fee_currency": "USD",
      "valid_from": "2026-09-23T15:04:05Z",
      "valid_to": "2026-09-23T15:09:05Z"
    }
  ]
}

source_amount is what will be debited from the wallet; target_amount is what the beneficiary receives. USD is the only supported target currency on this corridor.

Submit the payout

POST /v1/payments/withdrawals

curl -X POST https://api-staging.checker.finance/v1/payments/withdrawals \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "beneficiary_id": "ben_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "customer_id": "cus_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "rail": "CHINA_OFFRAMP",
    "quote_id": "qte_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "purpose_code": "PAYMENT_FOR_PHYSICAL_GOODS",
    "file_ids": ["file_01ARZ3NDEKTSV4RRFFQ69G5FAV"],
    "description": "Invoice INV-2026-0915"
  }'

Response — 202 Accepted:

{
  "withdrawal_id": "wdr_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "account_id": "acc_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "beneficiary_id": "ben_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "customer_id": "cus_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "quote_id": "qte_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "amount": "100.05",
  "rail": "CHINA_OFFRAMP",
  "purpose_code": "PAYMENT_FOR_PHYSICAL_GOODS",
  "status": "PROCESSING"
}

Notes:

quote_id is required and amount is not allowed; the withdrawal amount is the quote's source_amount. Sending amount, or omitting quote_id, returns 400 VALIDATION_ERROR.
customer_id is required because the wallet is not linked to a customer (400 CUSTOMER_REQUIRED without it, 400 CUSTOMER_NOT_ONBOARDED if that customer is not onboarded for the corridor).
purpose_code is PAYMENT_FOR_PHYSICAL_GOODS or OTHER on this rail; any other value ends the withdrawal FAILED with reason_code: INVALID_PURPOSE_CODE.
file_ids must reference at least one previously uploaded INVOICE or CONTRACT.
description is optional on this rail.
The quote is consumed by the payout and moves to USED; reusing it returns 400 QUOTE_NOT_ACTIVE, and an expired quote returns 400 QUOTE_EXPIRED.