Get

Returns the invoice and its associated on-chain payments. The invoice must belong to the authenticated merchant and match the API key's environment. Use this endpoint for server-side status checks before fulfillment.

Usage notes#

Use the invoice UUID returned by creation. This operation requires invoices:read and returns the invoice's current state, unlike an idempotent replay of its original creation.

Check status before fulfillment. amount_paid is cumulative accepted gross; payments[] includes observations that may not be accepted. A static-origin invoice identifies its address through static_address_id and can have a null checkout_url.

Nominal fields preserve the original request. Payment-selection fields, address, and timestamps can be null before activation. See amounts and lifecycle.

Each payment carries a stable id and its own settlement: that payment's ledger facts and conversion state, null where the read did not compute them. A paid invoice does not make its payments settled. See payment settlement.

The refund_summary describes current returns separately from the invoice's payment status. A paid invoice remains paid after its refund. See refund visibility and read the linked refund operations for execution details.

GET/v1/invoices/{invoiceID}

curl --request GET 'https://api.thehalfin.com/v1/invoices/00000000-0000-0000-0000-000000000001' \
  --header "X-API-Key: $HALFIN_API_KEY"

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

Path Parameters

invoiceIDstringRequired
Invoice UUID.
- Format: uuid
Example: 00000000-0000-0000-0000-000000000001

Response Body

200 Invoice detail.

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.

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.

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.

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

404 `not_found`: The invoice was not found in the API key's merchant and environment scope.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"not_found","message":"string","details":["string"]}
- code"not_found"Required
  `not_found`: The invoice was not found in the API key's merchant and environment scope.
  Example: not_found
- 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": "not_found",
    "message": "Resource not found"
  },
  "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.

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

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

Usage notes# #

Authorization #

Path Parameters #

Response Body #

Usage notes#

Authorization

Path Parameters

Response Body