Create

Creates a fixed-crypto or fiat-nominated invoice and its checkout URL. Rates, payment amounts, deadline, and address remain unset until checkout activation. A fiat invoice prices the purchase in USD or EUR; the payer selects a cryptocurrency and network at checkout. Fiat currency availability is validated by the API. Omit network for fiat prices (supplying it returns 400 validation_error). Crypto requires currency and network from GET /v1/currencies (missing network returns 400 validation_error). An unknown pair returns 422 gate_unknown; a disabled pair returns 422 gate_not_enabled. A currency sent without a network that is neither an enabled fiat nomination nor a catalogued cryptocurrency returns 422 unprocessable_entity. Fiat nominations have no preselected pair. A crypto invoice preselects the pair you nominated and can also be paid with any other asset you have enabled on that same network, priced from the nominated amount at checkout; the response then names the asset being paid in currency and network while nominal_amount, nominal_currency and nominal_network keep the price you billed.

Idempotency: Idempotency-Key is required. A replay with the same key but different path parameters, query, or body returns 409 with code conflict. Exact request replays are idempotent and return the original invoice.

Usage notes#

Creation records the nominated price and returns a hosted checkout URL. Store id and checkout_url from the response. Address allocation, the selected crypto amount, the rate lock, and the payment deadline happen at checkout activation.

Send the price as amount, currency, and, for crypto, network. The response returns that original price as nominal_amount, nominal_currency, and nominal_network; these are not request fields. The response's amount_requested, currency, and network describe the crypto payment. The API also sets the returned draft_expires_at and expires_at deadlines; neither is a create-request parameter. See the request-to-response example.

Crypto invoices require network, including single-network assets. Enabled fiat denominations such as USD omit it. The optional external_id is unique per merchant/environment; keep your invoice-ID mapping locally and use the exact external_id list filter when reconciling an order.

See invoice lifecycle and idempotency. This request requires invoices:write.

POST/v1/invoices

curl --request POST 'https://api.thehalfin.com/v1/invoices' \
  --header "X-API-Key: $HALFIN_API_KEY" \
  --header 'Idempotency-Key: createInvoice-example-1001' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": "25.00",
  "currency": "USD",
  "external_id": "order-1001",
  "description": "Order 1001",
  "metadata": {
    "order_id": "1001"
  }
}'

Authorization

X-API-KeystringRequired
API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.
Example: $HALFIN_API_KEY

Header Parameters

Idempotency-KeystringRequired
Persist a unique key before sending this operation. Retry an uncertain outcome with the same key and unchanged request; a new operation needs a new key.
See idempotency and retries for replay, conflict, and key-release behavior.
Full header contract
Required for merchant POST requests that create invoices, addresses, payouts, or refunds. Use a unique key for each intended operation. The same key namespace is shared by all merchant operations within the same merchant and environment. Retry the original request with the same key and unchanged path, query, and body. JSON key ordering and insignificant whitespace are ignored; numeric literals and string values are preserved ("10" differs from "10.00"). Changing any field under a bound key returns 409 conflict. An executing request returns 409 in_flight. An exact retry returns the permanent original outcome with Idempotent-Replayed: true. Only Idempotency-Key-Released: true confirms that a refused attempt released the key. An unconfirmed release returns 503 service_unavailable without that header. Under uncertainty, retry the original request with the same key. The key is never echoed in response bodies. Keys contain 1–255 printable ASCII characters without spaces; a UUID is recommended.
- Minimum length: 1
- Maximum length: 255
- Pattern: ^[\x21-\x7E]+$
Example: createInvoice-example-1001

Request Body

Required

application/json

amountstringRequired
Positive decimal amount in units of `currency`.
- Minimum length: 1
- Maximum length: 50
Example: 1
currencystringRequired
Fiat invoice price currency (USD or EUR, subject to availability validated by the API), or a cryptocurrency code from GET /v1/currencies. Omit network for fiat prices; the payer selects the cryptocurrency and network at checkout. For a fixed cryptocurrency amount, supply its network from GET /v1/currencies. A crypto invoice is payable with any of your enabled assets on the SAME network, priced from the nominated amount, so `currency` and `network` in every response name the asset actually being paid while the nomination stays what you billed. A code that is neither an enabled fiat nomination nor a catalogued cryptocurrency, sent without a network, is refused 422 unprocessable_entity.
- Minimum length: 1
- Maximum length: 20
Example: string
networkstringOptional
Required for crypto; omission returns 400 validation_error. Must be omitted for fiat; supplying it returns 400 validation_error. Unknown or disabled pairs return 422 gate_unknown or unprocessable_entity. The network is what a crypto invoice fixes; the payer may settle it in any of your enabled assets on this network, and never on another one.
- Minimum length: 1
- Maximum length: 30
Example: string
external_idstringOptional
Optional write-once field; omitted means null. Unique per merchant and environment; duplicate returns 409 conflict.
- Minimum length: 1
- Maximum length: 255
Example: string
descriptionstringOptional
Optional write-once field; omitted means null.
- Minimum length: 1
- Maximum length: 1000
Example: string
payer_emailstringOptional
Optional write-once field; omitted means null.
- Format: email
- Minimum length: 1
- Maximum length: 320
Example: [email protected]
redirect_urlstringOptional
Invoice override of the branding return URL; omitted means null.
- Format: uri
- Minimum length: 1
- Maximum length: 2048
- Pattern: ^https://[^\s@/?#]+([/?#][^\s]*)?$
Example: https://example.com
metadataobjectOptional
Merchant key-value metadata; omitted invoice metadata is stored and returned as an empty object.
- Maximum properties: 50
Example: {"key":"string"}
- [key]stringOptional
  - Maximum length: 500
  Example: string

Response Body

201 Invoice created.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

dataobjectRequired
- Unknown properties are rejected
Example: {"nominal_amount":"25.00","nominal_currency":"USD","nominal_network":null,"id":"00000000-0000-0000-0000-000000000003","merchant_id":"00000000-0000-0000-0000-000000000002","currency":null,"network":null,"amount_requested":null,"amount_paid":"0","status":"pending","invalid_reason":null,"environment":"test","deposit_address":null,"deposit_address_tag":null,"description":"Order 1001","external_id":"order-1001","metadata":{"order_id":"1001"},"redirect_url":null,"source":"api","static_address_id":null,"checkout_url":"https://checkout.thehalfin.com/pay/example-token","payments":[],"expires_at":null,"draft_expires_at":"2026-09-15T10:00:00Z","paid_at":null,"created_at":"2026-09-14T10:00:00Z","payer_email":null,"sent_at":null}
- refund_summaryobjectOptional
  Current refund coverage over confirmed source principal, independent of invoice payment status. Present on merchant invoice GET and list responses. A later confirmed payment can change full coverage to partial; unknown means coverage cannot be established reliably. Fees and delivered recipient amounts are separate.
  - Unknown properties are rejected
  Example: {"coverage":"none","has_inflight":false,"needs_attention":false,"amounts":[{"currency":"string","network":"string","principal_amount":"1","refunded_amount":"1","recipient_amount":"1","inflight_amount":"1","remaining_amount":"1"}]}
  - coverage"none" | "partial" | "full" | "unknown"Required
    Example: none
  - has_inflightbooleanRequired
    Example: false
  - needs_attentionbooleanRequired
    Example: false
  - amountsarray<object>Required
    Example: [{"currency":"string","network":"string","principal_amount":"1","refunded_amount":"1","recipient_amount":"1","inflight_amount":"1","remaining_amount":"1"}]
    - currencystringRequired
      Example: string
    - networkstringRequired
      Example: string
    - principal_amountstringRequired
      Confirmed incoming principal in this currency/network, not invoice fiat nominal.
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - refunded_amountstringRequired
      Completed refund principal; excludes refund fees and reversed executions.
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - recipient_amountstringRequired
      Amount delivered by completed returns, after any customer-paid fees.
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - inflight_amountstringRequired
      Principal reserved or in execution, including an unresolved outcome.
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - remaining_amountstringRequired
      Principal less completed and inflight principal, floored at zero; not an eligibility promise.
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
- nominal_amountstringRequired
  Immutable amount originally nominated by the merchant; for a static deposit, the received amount.
  Example: string
- nominal_currencystringRequired
  Currency of nominal_amount, including fiat USD/EUR.
  Example: string
- nominal_networkstring | nullRequired
  Fixed crypto network, or null for a fiat nomination.
  Example: null
- idstringRequired
  Invoice UUID.
  - Format: uuid
  Example: 00000000-0000-0000-0000-000000000001
- merchant_idstring | nullRequired
  Owning merchant UUID.
  - Format: uuid
  Example: null
- currencystring | nullRequired
  Cryptocurrency code.
  Example: null
- networkstring | nullRequired
  Blockchain network key for explorer and gate routing.
  Example: null
- amount_requestedstring | nullRequired
  Selected option total in crypto, including payer fees. Null before selection.
  Example: null
- amount_paidstringRequired
  Decimal string of the total amount paid.
  Example: 1
- pricing_rateobject | nullRequired
  The rate the selected payment option was priced at, from the invoice's applied pricing snapshot; null while the invoice is a draft with no gate selected. A fixed-crypto or static-address invoice carries it with spread_rate "0" and equal rates.
  - Unknown properties are rejected
  Example: null
  - snapshot_idstringRequired
    Pricing snapshot of the OFFER the rate is reproduced from; a late-payment re-lock does not change it.
    - Format: uuid
    Example: 00000000-0000-0000-0000-000000000001
  - reference_usdstringRequired
    Market reference, USD per one unit of the asset, at the moment the offer locked.
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - quoted_usdstringRequired
    Rate applied to the payer, `reference_usd × (1 − spread_rate)`, before service fees.
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - spread_ratestringRequired
    Platform conversion margin priced into the quoted rate, as a decimal fraction (0.02 = 2%); "0" when the payment is not auto-converted or the merchant bears the spread in the conversion.
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - sourcestring | nullRequired
    Market-data adapter the reference was read from; null for a constant price.
    Example: null
  - fetched_atstringRequired
    When the reference observation was taken.
    - Format: date-time
    Example: 2026-01-01T00:00:00Z
  - locked_untilstring | nullRequired
    End of the price promise for the payer; null when the snapshot is not time-bound.
    - Format: date-time
    Example: null
  - settlement_reference_usdstring | nullRequired
    Reference the credit was stamped at when the first payment arrived after locked_until and the invoice moved onto a refreshed snapshot; null otherwise. The quoted rate and the amount never move with it.
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: null
- status"pending" | "confirming" | "paid" | "overpaid" | "underpaid" | "expired" | "invalid" | "rejected"Required
  Invoice status. A payment that is still being processed leaves the status as it is: `pending` while nothing is credited, `confirming` while part is credited. `rejected` (final): money arrived and will not be credited; it carries no reason.
  Example: pending
- invalid_reason"payment_dropped" | "payment_reorged" | nullRequired
  Why a terminal `invalid` invoice closed: `payment_dropped` for an announced payment that was replaced, dropped or expired, `payment_reorged` for one whose block was orphaned. `null` for every other status.
  Example: null
- environment"live" | "test"Required
  Environment this invoice belongs to.
  Example: live
- deposit_addressstring | nullRequired
  Blockchain deposit address.
  Example: null
- deposit_address_tagstring | nullRequired
  Memo/tag for chains that require it (e.g. XRP, XLM).
  Example: null
- descriptionstring | nullRequired
  Invoice description.
  Example: null
- external_idstring | nullRequired
  Merchant-supplied external reference ID.
  Example: null
- metadataobjectRequired
  Merchant key-value metadata; omitted invoice metadata is stored and returned as an empty object.
  - Maximum properties: 50
  Example: {"key":"string"}
  - [key]stringOptional
    - Maximum length: 500
    Example: string
- redirect_urlstring | nullRequired
  Customer redirect URL.
  Example: null
- source"api" | "dashboard" | "static"Required
  How the invoice was created.
  Example: api
- static_address_idstring | nullRequired
  Static address UUID if created from a static address deposit.
  - Format: uuid
  Example: null
- checkout_urlstring | nullRequired
  Hosted checkout URL, published on create, get and list. Null for static deposits or when the stored checkout token cannot be recovered.
  Example: null
- paymentsarray<object>Required
  On-chain payments detected for this invoice.
  Example: [{"id":"00000000-0000-0000-0000-000000000001","currency":"string","network":"string","tx_hash":"string","amount":"1","confirmations":0,"required_confirmations":0,"status":"string","detected_at":"2026-01-01T00:00:00Z","settlement":null}]
  - idstringRequired
    Payment UUID. Stable across reads; use it to correlate settlement facts.
    - Format: uuid
    Example: 00000000-0000-0000-0000-000000000001
  - currencystringRequired
    Currency of this payment.
    Example: string
  - networkstringRequired
    Network on which this payment was received.
    Example: string
  - tx_hashstringRequired
    Blockchain transaction hash.
    Example: string
  - amountstringRequired
    Decimal string of the source payment amount.
    Example: 1
  - confirmationsintegerRequired
    Number of blockchain confirmations.
    Example: 0
  - required_confirmationsintegerRequired
    Required blockchain confirmations for this payment.
    Example: 0
  - statusstringRequired
    Payment status (observed, confirming, confirmed, converting, dropped).
    Example: string
  - detected_atstringRequired
    When the payment was first detected.
    - Format: date-time
    Example: 2026-01-01T00:00:00Z
  - settlementobject | nullRequired
    The payment's ACTUAL settlement: its own immutable ledger facts and the state of its conversion decision, independent of the receipt `status` and of the current wallet balance. `conversion` (where present) is the quote/execution view of the same payment; this object is the per-payment ledger view. Null only when the read path did not compute settlement for this row.
    - Unknown properties are rejected
    Example: null
    - conversion_status"not_applicable" | "pending" | "settled" | "source_restored" | "needs_review" | "unknown"Required
      State of the unfinished conversion decision, if one exists, otherwise the current acceptance's decision. Multiple unfinished decisions are contradictory and report `unknown`. `not_applicable`: no conversion target, or the decision refused conversion. `pending`: a target is frozen and the conversion has not completed (no decision row yet, execution pending, or batch-enrolled but not committed). `settled`: the payment's own target credit is committed (solo settled or batch member committed). `source_restored`: the conversion returned the source asset. `needs_review`: the conversion is quarantined for an operator. `unknown`: the stored facts are incomplete or contradictory for a credited payment; no amount is invented. Receipt `paid`/`confirming` is never mapped into this field. Consumers may receive new values in the future.
      Example: not_applicable
    - sourceobjectRequired
      The gate the payment arrived on. Always present.
      - Unknown properties are rejected
      Example: {"currency":"string","network":"string"}
      - currencystringRequired
        Asset code.
        Example: string
      - networkstringRequired
        Blockchain network key.
        Example: string
    - targetobject | nullRequired
      The conversion target frozen for this payment: from its conversion decision when one exists, else the invoice's frozen auto-conversion target, else null. A refused (`not_applicable`) decision nulls the target even when the invoice froze one. Never the merchant's current setting.
      - Unknown properties are rejected
      Example: null
      - currencystringRequired
        Asset code.
        Example: string
      - networkstringRequired
        Blockchain network key.
        Example: string
    - accepted_source_amountstringRequired
      This payment's latest acceptance credit in the source asset. It remains after an acceptance reversal (the reversal appears in `reversed_credits`); zero only when no acceptance was ever booked.
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - source_available_contributionstringRequired
      Signed net of every entry this payment booked on the merchant's available balance in the source asset: acceptance, mirrors, conversion debits, restored source and fee true-ups. Not the wallet balance — a later payout may have spent the shared balance — and it may be negative after a reversal.
      - Format: decimal
      - Pattern: ^-?\d+(\.\d+)?$
      Example: 1
    - credited_target_amountstringRequired
      Cumulative committed credit across this payment's conversion cycles in the selected target asset after gain/loss (dust already included). Published only when the selected decision is `settled`, otherwise zero. Zero in another state does not mean no earlier conversion credited money; consult the ledger history. A settled zero is an explicit zero-share batch allocation with no earlier credit in that target.
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - pending_conversion_source_amountstring | nullRequired
      The unfinished gross source obligation of a `pending` conversion decision (its frozen source debit). Null in every other state and when no decision row exists yet. It is not a promise of physically unused or returnable source.
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: null
    - reserved_amountsarray<object>Required
      This payment's own remaining positive reserved holds, per native gate, in canonical gate order. Empty when nothing is held.
      - Maximum items: 64
      Example: [{"currency":"string","network":"string","amount":"1"}]
      - currencystringRequired
        Asset code.
        Example: string
      - networkstringRequired
        Blockchain network key.
        Example: string
      - amountstringRequired
        Positive native amount as a decimal string.
        Format: decimal
        Pattern: ^\d+(\.\d+)?$
        Example: 1
    - reversed_creditsarray<object>Required
      Credits of this payment that were mirrored back (acceptance reversal, conversion credit reversal), per native gate, in canonical gate order. Each available credit is counted once.
      - Maximum items: 64
      Example: [{"currency":"string","network":"string","amount":"1"}]
      - currencystringRequired
        Asset code.
        Example: string
      - networkstringRequired
        Blockchain network key.
        Example: string
      - amountstringRequired
        Positive native amount as a decimal string.
        Format: decimal
        Pattern: ^\d+(\.\d+)?$
        Example: 1
    - conversion_execution"internal_fill" | "solo_external" | "batch" | nullOptional
      How the selected conversion decision was ACTUALLY carried out, as stamped when that decision was taken. `internal_fill`: filled from the platform's own position, with no venue and no chain leg. `solo_external`: this payment's own trade at an external venue. `batch`: enrolled into a group trade. Null while no decision row exists yet, and on payments that were never converted.
      Example: null
    - conversion_route_idstring | nullOptional
      The route the conversion was admitted on, as recorded on its attempt. Null when no attempt exists — a decision that refused conversion, or a batch member before its group is sealed.
      - Maximum length: 200
      Example: null
    - conversion_providerstring | nullOptional
      The executor that carried the conversion: `inventory` for a fill from the platform's own position, otherwise the venue adapter (`kraken-delivery`, `nearintents`, …). Null under the same conditions as `conversion_route_id`. Open vocabulary: the provider roster grows without a contract change.
      - Maximum length: 100
      Example: null
- expires_atstring | nullRequired
  Fixed deadline from first checkout activation, null before activation.
  - Format: date-time
  Example: null
- draft_expires_atstring | nullRequired
  Draft deadline, null after activation.
  - Format: date-time
  Example: null
- paid_atstring | nullRequired
  Timestamp when the invoice was fully paid.
  - Format: date-time
  Example: null
- created_atstringRequired
  Creation timestamp.
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
- payer_emailstring | nullRequired
  Email address the invoice was sent to.
  Example: null
- sent_atstring | nullRequired
  Timestamp when the invoice email was sent.
  - Format: date-time
  Example: null
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "data": {
    "nominal_amount": "25.00",
    "nominal_currency": "USD",
    "nominal_network": null,
    "id": "00000000-0000-0000-0000-000000000003",
    "merchant_id": "00000000-0000-0000-0000-000000000002",
    "currency": null,
    "network": null,
    "amount_requested": null,
    "amount_paid": "0",
    "status": "pending",
    "invalid_reason": null,
    "environment": "test",
    "deposit_address": null,
    "deposit_address_tag": null,
    "description": "Order 1001",
    "external_id": "order-1001",
    "metadata": {
      "order_id": "1001"
    },
    "redirect_url": null,
    "source": "api",
    "static_address_id": null,
    "checkout_url": "https://checkout.thehalfin.com/pay/example-token",
    "payments": [],
    "expires_at": null,
    "draft_expires_at": "2026-09-15T10:00:00Z",
    "paid_at": null,
    "created_at": "2026-09-14T10:00:00Z",
    "payer_email": null,
    "sent_at": null
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

400 `validation_error`: The request format, parameters, headers, or field values are invalid.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"validation_error","message":"string","details":["string"]}
- code"validation_error"Required
  `validation_error`: The request format, parameters, headers, or field values are invalid.
  Example: validation_error
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

401 `unauthorized`: A valid API key is required.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"unauthorized","message":"string","details":["string"]}
- code"unauthorized"Required
  `unauthorized`: A valid API key is required.
  Example: unauthorized
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

403 `forbidden`: The API key does not have permission for this operation. `api_key_ip_forbidden`: The request source address is not allowed by the API key.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"forbidden","message":"string","details":["string"]}
- code"forbidden" | "api_key_ip_forbidden"Required
  `forbidden`: The API key does not have permission for this operation. `api_key_ip_forbidden`: The request source address is not allowed by the API key.
  Example: forbidden
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "forbidden",
    "message": "Permission denied"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

409 `conflict`: The idempotency key is bound to a different request, or this request conflicts with an existing resource. `in_flight`: A request with this idempotency key is still executing. Retry the original request with the same key.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"conflict","message":"string","details":["string"]}
- code"conflict" | "in_flight"Required
  `conflict`: The idempotency key is bound to a different request, or this request conflicts with an existing resource. `in_flight`: A request with this idempotency key is still executing. Retry the original request with the same key.
  Example: conflict
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "conflict",
    "message": "Request conflicts with the existing state"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

422 `unprocessable_entity`: The amount is outside the allowed range, the fiat invoice currency is unavailable, or the currency is neither an enabled fiat nomination nor a catalogued cryptocurrency. `gate_unknown`: The requested currency and network pair is unknown. `gate_not_enabled`: The currency and network pair is not enabled for this merchant in this environment.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"unprocessable_entity","message":"string","details":["string"]}
- code"unprocessable_entity" | "gate_unknown" | "gate_not_enabled"Required
  `unprocessable_entity`: The amount is outside the allowed range, the fiat invoice currency is unavailable, or the currency is neither an enabled fiat nomination nor a catalogued cryptocurrency. `gate_unknown`: The requested currency and network pair is unknown. `gate_not_enabled`: The currency and network pair is not enabled for this merchant in this environment.
  Example: unprocessable_entity
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "unprocessable_entity",
    "message": "The request cannot be processed in the current state"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

500 `internal_error`: The API could not complete the request. Contact support with the request ID if the error persists.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"internal_error","message":"string","details":["string"]}
- code"internal_error"Required
  `internal_error`: The API could not complete the request. Contact support with the request ID if the error persists.
  Example: internal_error
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

503 `service_unavailable`: The service is temporarily unavailable. If the outcome is uncertain, retry the original request with the same idempotency key.

Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true
Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"service_unavailable","message":"string","details":["string"]}
- code"service_unavailable"Required
  `service_unavailable`: The service is temporarily unavailable. If the outcome is uncertain, retry the original request with the same idempotency key.
  Example: service_unavailable
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

Usage notes# #

Authorization #

Header Parameters #

Request Body #

Response Body #

Usage notes#

Authorization

Header Parameters

Request Body

Response Body