List

application/json

• dataarray<object>Required

  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","has_more":false,"next_cursor":null}

  • request_idstringRequired
    Correlation identifier issued by the API, also returned in the X-Request-ID response header. An inbound value is adopted only from explicitly trusted ingress; public client values are replaced.

    Example: string

  • has_morebooleanRequired
    True exactly when next_cursor is not null.

    Example: false

  • next_cursorstring | nullRequired
    Opaque cursor for the next page. Null when this is the last page.

    Example: null

{
  "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",
    "has_more": false,
    "next_cursor": null
  }
}

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"
  }
}

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"
  }
}

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"
  }
}

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"
  }
}

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. Retry later.

    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"
  }
}