Aicscan Documentation
FrançaisEnglish

Pay: invoices

Create an invoice

POST/v1/invoices

Price in USDT or in an enabled display currency (see GET /v1/rates); the exchange rate is frozen at creation. One deposit address per offered chain (variant A), or the merchant's shared address with a unique amount (variant B, one chain only). Errors: chain_not_available, amount_below_minimum, amount_above_cap, ttl_out_of_range, duplicate_external_ref, unique_amount_exhausted (409, variant B), currency_suspended (409, USDT/USD guard or missing rate), kyb_required (403, live mode).

Authentication
API key (Authorization: Bearer)
Required scope
pay:write
  • Safe to retry with the Idempotency-Key header: see Idempotency.

Headers#

  • Idempotency-Keystringrequired

    Required on every Pay POST; makes it safe to retry for 24 hours. Scoped to the key's environment.

    1 to 255 characters

Request body#

  • currencystringrequired

    USDT, or an enabled display currency (USD, EUR, XOF…).

  • price_e6stringrequired

    Price in millionths of the currency, e.g. 12500000 = 12.50. No more decimals than the currency has (XOF: none).

  • chain_idsarray of integerrequired

    Chains offered to the payer.

    1 to 10 items
  • variantstring

    A: one deposit address per invoice. B: shared address and unique amount, one chain only.

    Values A B
    Default "A"
  • ttl_secondsinteger

    Validity; default 3600, from 900 to 604800.

  • external_refstring

    Your reference, unique per environment.

    at most 200 characters
  • descriptionstring
    at most 1000 characters
  • metadataobject

    8 KiB at most.

Responses#

201Invoice created.

Response headers

  • Locationstring

    /v1/invoices/{id}.

Object fields
  • idstring · uuid
  • objectstring
    Values invoice
  • statusstring
    Values waiting confirming paid underpaid overpaid expired paid_late canceled held
  • environmentstring
    Values test live
  • external_refstringnullable
  • variantstring
    Values A B
  • chain_idintegernullable

    Chain of the payment (set at creation when one chain is offered).

  • tokenstringnullable
  • decimalsintegernullable
  • amount_dueany
  • amount_receivedany
  • amount_pendingany
  • differencestringnullable

    Signed difference to the amount due, native units.

  • priceobjectnullable
    Object fields
    • currencystring
    • price_e6string
    • fx_rate_e6string

      Units of the currency for 1 USDT, in millionths, frozen at creation.

    • fx_sourcestring
    • fx_as_ofstring · date-time
  • chainsarray of object
    Fields of each item
    • amountstring

      Native units, e.g. 12500000 for 12.5 USDT with 6 decimals.

    • amount_formattedstring
    • decimalsinteger
    • chain_idinteger
    • tokenstring
    • deposit_addressstring

      Base58 T… on TRON.

    • payment_uristringnullable

      EIP-681 URI for a QR code (EVM chains).

  • expires_atstring · date-time
  • paid_atstring · date-timenullable
  • created_atstring · date-time
  • metadataobject
4xx · 5xxError.

Standard error format: see Errors.