List the payments to a deposit address
GET/v1/deposit_addresses/{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”curl "https://api.ctpeway.com/v1/deposit_addresses/{id}/payments" \ -H "Authorization: Bearer $CTPEWAY_API_KEY"import { CtpeWay } from '@ctpeway/sdk';
const ctpeway = new CtpeWay(process.env.CTPEWAY_API_KEY);
const result = await ctpeway.depositAddresses.listPayments('<id>');Response
Section titled “Response”200 OK
Section titled “200 OK”| Field | Type | Description |
|---|---|---|
data |
array of objects | |
data[]. |
string | |
data[]. |
string | One of detected, confirmed, orphaned, dropped. |
data[]. optional |
string | |
data[]. optional |
string | |
data[]. optional |
string | |
data[]. |
string | |
data[]. |
string | |
data[]. |
string | |
data[]. optional |
string | |
data[]. |
integer | |
data[]. |
string | |
data[]. optional |
string | |
data[]. 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[]. optional |
integer | Position of the transfer inside the transaction. Present exactly when tx_hash is. |
data[]. |
string | A whole number written as a string of digits. |
data[]. |
integer | |
data[]. optional |
integer | |
data[]. optional |
string | |
data[]. optional |
string | Value at the price snapshot taken at confirmation. A decimal number written as a string, with up to 8 decimal places. |
data[]. |
boolean | Confirmed after the invoice had expired or been canceled. |
data[]. |
boolean | |
data[]. |
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[]. |
string (date-time) | |
data[]. optional |
string (date-time) | |
data[]. 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[]. |
string | |
data[]. |
string | One of pending, held, releasing, released, failed, reverted. |
data[]. |
string | |
data[]. optional |
string | |
data[]. optional |
string | |
data[]. |
string | |
data[]. |
string | |
data[]. |
string | |
data[]. |
string | |
data[]. |
string | The deposit, base units of asset. A whole number written as a string of digits. |
data[]. |
string | A decimal number written as a string, with up to 8 decimal places. |
data[]. |
integer | |
data[]. |
string | Platform fee owed, base units of native_asset. A whole number written as a string of digits. |
data[]. |
string | One of deposit, master. |
data[]. |
string | A whole number written as a string of digits. |
data[]. |
string | A whole number written as a string of digits. |
data[]. optional |
string | Native coin the master wallet must hold for this release. A whole number written as a string of digits. |
data[]. optional |
string | |
data[]. 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[]. optional |
string | |
data[]. optional |
string | |
data[]. optional |
string | |
data[]. |
string | A whole number written as a string of digits. |
data[]. optional |
string | A whole number written as a string of digits. |
data[]. |
boolean | |
data[]. |
string (date-time) | |
data[]. optional |
string (date-time) | |
data[]. optional |
string (date-time) | |
data[]. optional |
string (date-time) | |
data[]. |
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[]. |
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[]. |
boolean | false for objects of the test environment. |
data[]. optional |
integer | number of the invoice that was paid. Payments to an invoice only. |
data[]. optional |
string | Name of the deposit address that was paid, if it has one. Payments to a deposit address only. |
data[]. |
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[]. |
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: