Payments and confirmations

A payment is one transfer to one of your addresses: the address of an invoice option, or a reusable deposit address. One invoice can have several payments.

Statuses

Status	Meaning
detected	The transfer has been seen on the network. It is not final and can still disappear.
confirmed	The transfer has reached the confirmation threshold of its network. cTpeWay treats it as final and starts settlement.
orphaned	The network reorganised and the transaction is no longer part of it.
dropped	An unconfirmed transfer disappeared from the network without ever being included.

Act on confirmed, not on detected. Fulfil an order when you receive invoice.paid, and credit a deposit address when you receive deposit.payment_confirmed. A detected payment is useful for showing “payment seen, waiting for confirmation” to your customer, and for nothing else.

How a payment is detected

cTpeWay watches the addresses that can receive money: the addresses of open invoices and your reusable deposit addresses.

When a checkout page is open, detection is faster. The page tells cTpeWay that someone is looking at this invoice, so the invoice is checked every few seconds. The page can also report a transaction it has seen, for example the one a connected wallet just sent. cTpeWay then looks that transaction up on the network and checks the recipient, the asset and the amount itself. A report from the page only tells cTpeWay where to look. It is never proof of payment.

If the payer closes the page, nothing is lost. cTpeWay keeps checking the address.

Confirmations

Each network has its own rule for when a payment counts as confirmed, and cTpeWay applies it for you. GET/v1/networks tells you the rule of each network:

Field	Meaning
confirmation_rule	confirmations: the network counts blocks on top of the payment. finalized or safe: the network’s own finality decides, whatever the count.
confirmations_required	With the rule confirmations, how many confirmations a payment needs. With finalized or safe it is only a fallback depth, so do not count towards it.
estimated_confirmation_seconds	The expected time from sending a payment until it counts as confirmed. It is an estimate, not a promise, and it is absent when there is no figure for the network.

The checkout page shows the payer the progress, for example “3 of 12”. cTpeWay can adjust these values, so read them from the API and do not hard-code them. Read confirmations on the payment if you want to show progress yourself.

When a payment is reversed

A payment can be removed from a network after it was seen and, rarely, after it was confirmed. When that happens:

• the payment becomes orphaned and you receive payment.orphaned;
• if it belonged to an invoice, the invoice is re-evaluated without it and you receive invoice.payment_reverted;
• its settlement becomes reverted.

If the same transaction is included again later, the same payment is updated. It is not counted twice.

When the transaction is not known yet

Sometimes cTpeWay sees that the balance of one of your addresses has risen before it can tell which transaction brought the money. It does not wait. The payment is created at once, with detected_by set to balance and no tx_hash.

When the transaction has been identified, you receive payment.transaction_attached. From then on the payment has tx_hash and tx_index. Nothing else about it changes: it keeps its id, its status and its settlement.

So identify a payment by its id, and do not assume that every payment has a tx_hash. Check detected_by when you need to know.

Amounts

Every amount is a whole number of the asset’s smallest unit, written as a string, for example "100000000000000000000". Amounts are never decimals and never JavaScript numbers.

To show an amount, divide it by 10 to the power of the asset’s decimals. Take decimals from the payment itself, because the same asset can have different decimals on different networks: USDT has 18 on BNB Smart Chain and 6 on Tron.

What a payment tells you

These are the fields you will use most. The API reference lists all of them.

Field	Meaning
asset and network	What was sent, always as a pair, for example USDT on BNB Smart Chain.
amount, decimals	How much, in the smallest unit, and how to convert it for display.
address, from_address	Your address that received it, and the sender when the network makes that known.
tx_hash	The transaction on the network. Absent while a payment is known only from a balance change.
detected_by	How the payment was found: poll (its transaction was seen while watching the address), hint (reported through the checkout and then found on the network), balance (the balance rose; see above) or simulated (test mode).
confirmations	How many confirmations it has so far.
invoice_id or deposit_address_id	What it paid.
late	true if it was confirmed after its invoice had expired or been canceled.
simulated	true for a payment created with the test-mode simulator.
settlement	The id and status of its settlement, once the payment is confirmed.

Endpoints

Endpoint	What it does
GET/v1/payments	List payments.
GET/v1/payments/{id}	Retrieve one payment.
GET/v1/invoices/{id}/payments	Payments made to one invoice.
GET/v1/deposit_addresses/{id}/payments	Payments made to one deposit address.

Events

Event	Sent when
payment.detected	A transfer to one of your addresses was seen. Not final.
payment.confirmed	The payment reached the network’s confirmation threshold.
payment.orphaned	A network reorganisation removed the payment’s transaction.
payment.dropped	An unconfirmed payment disappeared without being included.
payment.transaction_attached	The transaction of a payment that was found by a balance change has been identified. The payment now has tx_hash.

Invoices and deposit addresses also send their own events about the same payments. See Invoices and Reusable deposit addresses.