Retrieve a payment

GET/v1/payments/{id}

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

Name	Type	Description
`id` required	string	At most 100 characters.

curl "https://api.ctpeway.com/v1/payments/{id}" \
  -H "Authorization: Bearer $CTPEWAY_API_KEY"

import { CtpeWay } from '@ctpeway/sdk';

const ctpeway = new CtpeWay(process.env.CTPEWAY_API_KEY);

const result = await ctpeway.payments.retrieve('<id>');

Response

200 OK

Field	Type	Description
`id`	string
`status`	string	One of `detected`, `confirmed`, `orphaned`, `dropped`.
`invoice_id` optional	string
`option_id` optional	string
`deposit_address_id` optional	string
`network`	string
`asset`	string
`asset_id`	string
`contract` optional	string
`decimals`	integer
`address`	string
`from_address` optional	string
`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.
`tx_index` optional	integer	Position of the transfer inside the transaction. Present exactly when `tx_hash` is.
`amount`	string	A whole number written as a string of digits.
`confirmations`	integer
`block_height` optional	integer
`block_hash` optional	string
`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.
`late`	boolean	Confirmed after the invoice had expired or been canceled.
`simulated`	boolean
`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`.
`detected_at`	string (date-time)
`confirmed_at` optional	string (date-time)
`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.
`settlement.id`	string
`settlement.status`	string	One of `pending`, `held`, `releasing`, `released`, `failed`, `reverted`.
`settlement.payment_id`	string
`settlement.invoice_id` optional	string
`settlement.deposit_address_id` optional	string
`settlement.network`	string
`settlement.asset`	string
`settlement.asset_id`	string
`settlement.native_asset`	string
`settlement.gross`	string	The deposit, base units of `asset`. A whole number written as a string of digits.
`settlement.usd_value`	string	A decimal number written as a string, with up to 8 decimal places.
`settlement.fee_bps`	integer
`settlement.fee_native`	string	Platform fee owed, base units of `native_asset`. A whole number written as a string of digits.
`settlement.fee_source`	string	One of `deposit`, `master`.
`settlement.fee_paid`	string	A whole number written as a string of digits.
`settlement.fee_carried`	string	A whole number written as a string of digits.
`settlement.required_native` optional	string	Native coin the master wallet must hold for this release. A whole number written as a string of digits.
`settlement.master_wallet_address` optional	string
`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`.
`settlement.fee_tx` optional	string
`settlement.topup_tx` optional	string
`settlement.sweep_tx` optional	string
`settlement.network_fees`	string	A whole number written as a string of digits.
`settlement.net_released` optional	string	A whole number written as a string of digits.
`settlement.simulated`	boolean
`settlement.confirmed_at`	string (date-time)
`settlement.held_since` optional	string (date-time)
`settlement.released_at` optional	string (date-time)
`settlement.failed_at` optional	string (date-time)
`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.
`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.
`settlement.livemode`	boolean	`false` for objects of the test environment.
`invoice_number` optional	integer	`number` of the invoice that was paid. Payments to an invoice only.
`deposit_address_name` optional	string	Name of the deposit address that was paid, if it has one. Payments to a deposit address only.
`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.
`livemode`	boolean	`false` for objects of the test environment.

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

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

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:

payment_not_found