Skip to content
Docsv2 preview

List the payments of an invoice

GET/v1/invoices/{id}/payments

Newest first. Each payment embeds the settlement it produced, in full, with the number of its invoice or the name of its deposit address.

Authorization

Section titled “Authorization”

Send your API key as a bearer token in the Authorization header. Secret API key: Authorization: Bearer ctp_live_sk_…. A publishable key (ctp_…_pk_…) is accepted by these operations only, which serve reference data: getRate, listAssets, listNetworks (each marked x-publishable-key: true). Every other operation refuses it with 403 publishable_key_not_allowed, whatever Origin the request carries: that header binds browsers, not other clients, and nothing on this API relies on it.

Path parameters

Section titled “Path parameters”
Name Type Description
id required string At most 100 characters.

Query parameters

Section titled “Query parameters”
Name Type Description
limit integer Number of items to return (1 to 100). Default 50. Minimum 1, maximum 100.
starting_after string Return items after this id: pass next_cursor of the previous page. At most 100 characters.
status string Payments in this status. One of detected, confirmed, orphaned, dropped, or several separated by commas. At most 256 characters.

Example request

Section titled “Example request”
Terminal window
curl "https://api.ctpeway.com/v1/invoices/{id}/payments" \
  -H "Authorization: Bearer $CTPEWAY_API_KEY"

Response

Section titled “Response”

200 OK

Section titled “200 OK”
Field Type Description
data array of objects
data[].id string
data[].status string One of detected, confirmed, orphaned, dropped.
data[].invoice_id optional string
data[].option_id optional string
data[].deposit_address_id optional string
data[].network string
data[].asset string
data[].asset_id string
data[].contract optional string
data[].decimals integer
data[].address string
data[].from_address optional string
data[].tx_hash optional string The transaction that paid. Absent while the payment is known only from a balance change (detected_by: balance) and its transaction has not been identified; payment.transaction_attached announces it. A simulated payment (test mode, simulated: true) carries its sim_… id here.
data[].tx_index optional integer Position of the transfer inside the transaction. Present exactly when tx_hash is.
data[].amount string A whole number written as a string of digits.
data[].confirmations integer
data[].block_height optional integer
data[].block_hash optional string
data[].usd_value optional string Value at the price snapshot taken at confirmation. A decimal number written as a string, with up to 8 decimal places.
data[].late boolean Confirmed after the invoice had expired or been canceled.
data[].simulated boolean
data[].detected_by string How the payment was found, fixed when it is first seen: poll (its transaction was seen while watching the address), hint (its transaction was reported through the checkout and found on the network), balance (the address’s balance rose; the transaction is identified later, and tx_hash is absent until then), simulated (test mode). One of poll, hint, balance, simulated.
data[].detected_at string (date-time)
data[].confirmed_at optional string (date-time)
data[].settlement optional object The settlement this payment produced, in full: status, fee, what is held and why, release transactions. Absent until the payment confirms. Webhook events carry only { id, status } here.
data[].settlement.id string
data[].settlement.status string One of pending, held, releasing, released, failed, reverted.
data[].settlement.payment_id string
data[].settlement.invoice_id optional string
data[].settlement.deposit_address_id optional string
data[].settlement.network string
data[].settlement.asset string
data[].settlement.asset_id string
data[].settlement.native_asset string
data[].settlement.gross string The deposit, base units of asset. A whole number written as a string of digits.
data[].settlement.usd_value string A decimal number written as a string, with up to 8 decimal places.
data[].settlement.fee_bps integer
data[].settlement.fee_native string Platform fee owed, base units of native_asset. A whole number written as a string of digits.
data[].settlement.fee_source string One of deposit, master.
data[].settlement.fee_paid string A whole number written as a string of digits.
data[].settlement.fee_carried string A whole number written as a string of digits.
data[].settlement.required_native optional string Native coin the master wallet must hold for this release. A whole number written as a string of digits.
data[].settlement.master_wallet_address optional string
data[].settlement.reason optional string Why it is held (status held) or why it failed (status failed); absent in any other status. insufficient_master_balance: Held: the master wallet has too little native coin to pay the platform fee and the network costs of the release (token deposits). Released by itself once the wallet is topped up. uneconomic: Held: the network fee of the release is estimated at more than half of what the deposit is worth. Looked at again on every planning run and released when the estimate falls. below_sweep_min: Held: the deposit is worth less than the merchant’s minimum for a sweep. It stays in its address until that setting allows it or another release from the same address takes it along. payment_orphaned: Failed: a chain reorganisation removed the payment while its release was under way. The settlement returns to the queue by itself if the payment confirms again. funds_missing: Failed: the deposit is no longer at its address and no release on record moved it. Needs an operator. not_releasable: Failed: the network cannot release this deposit as it stands (an asset or address it does not support, or a release plan that did not pass its checks). Needs an operator. transaction_failed: Failed: a transaction of the release was rejected or can no longer be included. Retried by an operator; what was already paid is not paid again. replanning: Failed for a moment: a transaction prepared for the release could not be used as it was, and the release is being planned again by itself. Nothing to do. unclassified: Failed: for a reason outside this list. Needs an operator. One of insufficient_master_balance, uneconomic, below_sweep_min, payment_orphaned, funds_missing, not_releasable, transaction_failed, replanning, unclassified.
data[].settlement.fee_tx optional string
data[].settlement.topup_tx optional string
data[].settlement.sweep_tx optional string
data[].settlement.network_fees string A whole number written as a string of digits.
data[].settlement.net_released optional string A whole number written as a string of digits.
data[].settlement.simulated boolean
data[].settlement.confirmed_at string (date-time)
data[].settlement.held_since optional string (date-time)
data[].settlement.released_at optional string (date-time)
data[].settlement.failed_at optional string (date-time)
data[].settlement.fee_usd string The platform fee in USD, fixed when the payment confirmed. A decimal number written as a string, with up to 8 decimal places.
data[].settlement.native_price string USD price of one whole native_asset in the price snapshot the fee was computed from: fee_native is fee_usd at this price. A decimal number written as a string, with up to 8 decimal places.
data[].settlement.livemode boolean false for objects of the test environment.
data[].invoice_number optional integer number of the invoice that was paid. Payments to an invoice only.
data[].deposit_address_name optional string Name of the deposit address that was paid, if it has one. Payments to a deposit address only.
data[].confirmations_required integer Confirmations the network asks of a payment of this value before it is confirmed. Compare with confirmations. On networks that follow the chain’s own finality this is the depth used when the node cannot report finality.
data[].livemode boolean false for objects of the test environment.
has_more boolean Whether more items exist after this page.
next_cursor string or null Pass as starting_after to get the next page; null on the last page. 
{
  "data": [
    {
      "id": "string",
      "status": "detected",
      "invoice_id": "string",
      "option_id": "string",
      "deposit_address_id": "string",
      "network": "string",
      "asset": "string",
      "asset_id": "string",
      "contract": "string",
      "decimals": 0,
      "address": "string",
      "from_address": "string",
      "tx_hash": "string",
      "tx_index": 0,
      "amount": "1000000",
      "confirmations": 0,
      "block_height": 0,
      "block_hash": "string",
      "usd_value": "10.00",
      "late": true,
      "simulated": true,
      "detected_by": "poll",
      "detected_at": "2026-01-01T00:00:00.000Z",
      "confirmed_at": "2026-01-01T00:00:00.000Z",
      "settlement": {
        "id": "string",
        "status": "pending",
        "payment_id": "string",
        "invoice_id": "string",
        "deposit_address_id": "string",
        "network": "string",
        "asset": "string",
        "asset_id": "string",
        "native_asset": "string",
        "gross": "1000000",
        "usd_value": "10.00",
        "fee_bps": 0,
        "fee_native": "1000000",
        "fee_source": "deposit",
        "fee_paid": "1000000",
        "fee_carried": "1000000",
        "required_native": "1000000",
        "master_wallet_address": "string",
        "reason": "insufficient_master_balance",
        "fee_tx": "string",
        "topup_tx": "string",
        "sweep_tx": "string",
        "network_fees": "1000000",
        "net_released": "1000000",
        "simulated": true,
        "confirmed_at": "2026-01-01T00:00:00.000Z",
        "held_since": "2026-01-01T00:00:00.000Z",
        "released_at": "2026-01-01T00:00:00.000Z",
        "failed_at": "2026-01-01T00:00:00.000Z",
        "fee_usd": "10.00",
        "native_price": "10.00",
        "livemode": true
      },
      "invoice_number": 0,
      "deposit_address_name": "string",
      "confirmations_required": 0,
      "livemode": true
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

The values are placeholders generated from the schema. They show the shape, not real data.

Errors

Section titled “Errors”

A failed request answers with the error format described under Errors.

Besides the codes any endpoint can return, this endpoint can answer with these code values: