Settlement and the platform fee
When a payment is confirmed, the money is in the address it was sent to: the address of an invoice, or a reusable deposit address. Settlement is what happens next. cTpeWay charges the platform fee and moves the funds to your master wallet.
Your customer never sees any of this. For them, the invoice is Paid as soon as the payment is confirmed.
Your master wallet
Section titled “Your master wallet”You have one master wallet on each network. It is:
- where released funds arrive,
- where payouts are sent from,
- what pays the platform fee and the network fee when you receive tokens.
Your wallet and your addresses are yours alone. They are never shared with another merchant and funds are never pooled. cTpeWay creates and operates these addresses for you and signs the transfers described on this page, so you approve nothing by hand.
The platform fee
Section titled “The platform fee”cTpeWay charges 0.5% of every deposit. That is the only platform fee. There is no platform fee on payouts or refunds.
The fee is always charged in the network’s native coin: ETH on Ethereum, BNB on BNB Smart Chain, BTC on Bitcoin, SOL on Solana, TRX on Tron. This is true even when the deposit itself is a token.
That leads to two cases.
A deposit in the native coin
Section titled “A deposit in the native coin”Example: your customer pays in BNB on BNB Smart Chain.
The platform fee is taken from the deposit itself when it is released, together with the network fee of the transfer. What remains arrives in your master wallet. You need nothing in your master wallet for this, and a native-coin deposit is never held for the fee.
A deposit in a token
Section titled “A deposit in a token”Example: your customer pays in USDT on BNB Smart Chain.
A token cannot pay a fee that is charged in the native coin. So the platform fee is paid from your master wallet, in the native coin, and so is the network fee of moving the tokens. The full token amount then arrives in your master wallet.
If your master wallet does not hold enough native coin to pay both, the deposit waits in its address until it does. This is the status Held. Nothing is lost and your customer is unaffected. Send native coin to your master wallet on that network and the deposit is released.
How the fee amount is worked out
Section titled “How the fee amount is worked out”The fee is 0.5% of the deposit’s value in USD, converted to the native coin. Both prices are taken at the moment the payment is confirmed and stored with the settlement, so the fee of a held deposit does not change while it waits.
An illustration, with every amount on BNB Smart Chain: a deposit of 100 USDT is confirmed while the native coin, BNB, is priced at 600 USD.
| Deposit | 100 USDT on BNB Smart Chain, worth 100.00 USD |
| Platform fee | 0.5% = 0.50 USD = about 0.000833 BNB |
| Needed in the master wallet | about 0.00093 BNB: the platform fee plus the network fees |
| Master wallet holds 0.01 BNB | Released. The full 100 USDT on BNB Smart Chain arrives in the master wallet. |
| Master wallet holds 0.0005 BNB | Held until you add native coin. |
A very small platform fee is not sent in a transaction of its own. It is carried forward and collected with the next settlement on the same network. The size below which this happens is not final.
Charged, carried and due
Section titled “Charged, carried and due”A platform fee is not always paid at the moment it is worked out. The fee report in the dashboard, under Balances, shows every fee and where it stands, in three parts:
| Part | Meaning |
|---|---|
| Charged | The fee has been paid: the transaction that paid it is in a block. For a native-coin deposit, it was taken from the deposit on its way out. |
| Carried | The fee was too small for a transaction of its own. It was carried forward when the deposit was released, and a later fee transfer collects it. |
| Due | Neither yet. The deposit is still waiting, as pending, held, releasing or failed. The fee of a held deposit is due, not charged. |
The three parts always add up to the fee. On a settlement, fee_native is the whole fee, fee_paid the charged part and fee_carried the carried part.
Statuses
Section titled “Statuses”A settlement has one status. The three you will see most are Pending, Held and Released.
| Status | Meaning | What to do |
|---|---|---|
pending |
The payment is confirmed and the settlement is waiting to be released. | Nothing. |
held |
The deposit is waiting in its address. reason says why. Usually your master wallet is short of native coin. |
Usually: add native coin to the master wallet on that network. See the reasons below. |
releasing |
The transfers are on their way. | Nothing. |
released |
The funds are in your master wallet. | Nothing. |
failed |
The release could not be completed. reason says why. |
See the reasons below. You can ask for another attempt with POST/v1/settlements/{id}/release. |
reverted |
The payment was removed from the network after it had been confirmed. | See Payments and confirmations. |
Only a token deposit can be held for an unpaid fee.
Why a settlement is held or failed
Section titled “Why a settlement is held or failed”A settlement that is held or failed carries a reason. It is one of these values, and absent in every other status.
reason |
Status | Meaning | What to do |
|---|---|---|---|
insufficient_master_balance |
held |
The master wallet has too little native coin to pay the platform fee and the network fees of the release. Only token deposits can be held for this. | Add native coin to the master wallet. The deposit is then released by itself. |
uneconomic |
held |
The network fee of the release is estimated at more than half of what the deposit is worth. | Nothing. It is looked at again regularly and released when the estimate falls. |
below_sweep_min |
held |
The deposit is worth less than the minimum you have set for moving a deposit. | Nothing, or lower that setting. It is released when the setting allows it, or when another release from the same address takes it along. |
payment_orphaned |
failed |
A network reorganisation removed the payment while its release was under way. | Nothing. The settlement returns to the queue by itself if the payment is confirmed again. |
replanning |
failed |
For a moment only: a transaction prepared for the release could not be used as it was, and the release is being planned again by itself. | Nothing. |
transaction_failed |
failed |
A transaction of the release was rejected, or can no longer be included. | It is retried by a cTpeWay operator. What was already paid is not paid again. |
funds_missing |
failed |
The deposit is no longer at its address, and no release on record moved it. | It needs a cTpeWay operator. |
not_releasable |
failed |
The network cannot release this deposit as it stands. | It needs a cTpeWay operator. |
unclassified |
failed |
A reason outside this list. | It needs a cTpeWay operator. |
On Tron in particular, moving a token deposit uses TRX for the network fee, so a small token deposit on Tron may wait as uneconomic until moving it is worth it.
Releasing held deposits
Section titled “Releasing held deposits”When native coin arrives in your master wallet, cTpeWay releases held deposits by itself. You do not need to call anything.
- Deposits are released oldest first.
- A deposit that the balance cannot cover is skipped, so one large held deposit does not block the smaller ones behind it.
This order comes from the v2 design and can change before launch.
To find out what is held and how much to add:
| Where | What it tells you |
|---|---|
| settlement.held | Sent when a deposit becomes held. Includes required_native, the native coin needed for this release, and master_wallet_address, where to send it. |
| master_wallet.low_balance | Sent when deposits are held because the master wallet is short. Includes held_count and required_to_clear, the amount that releases everything. |
| GET/v1/master_wallets/{network} | The master wallet’s address and balances, held_count and required_to_clear. |
| GET/v1/settlements | The list of settlements. Add ?status=held for the deposits that are waiting. |
| Dashboard, Balances | The total held on each network and the amount needed to release all of it. |
If you have just topped up and do not want to wait, POST/v1/settlements/{id}/release asks for a release attempt now. It answers with the settlement as it is at that moment; settlement.released or settlement.held follows as an event.
What a settlement tells you
Section titled “What a settlement tells you”These are the fields you will use most. The API reference lists all of them.
| Field | Meaning |
|---|---|
gross |
The deposit, in the smallest unit of its asset. |
fee_native |
The platform fee, in the smallest unit of the network’s native coin. |
fee_source |
deposit when the fee is taken from a native-coin deposit, master when your master wallet pays it for a token deposit. |
fee_paid, fee_carried |
How much of the fee has been charged, and how much was carried forward. See Charged, carried and due. |
required_native |
Native coin your master wallet must hold for this release. |
network_fees |
Network fees paid for this settlement, in the native coin. |
net_released |
What arrived in your master wallet. |
reason |
Why the settlement is held or failed. See the list of reasons. |
fee_tx, topup_tx, sweep_tx |
The transactions that paid the fee, sent native coin to the deposit’s address when that was needed, and moved the funds. |
Fees at a glance
Section titled “Fees at a glance”| Native-coin deposit | Token deposit | |
|---|---|---|
| Platform fee (0.5%) | Taken from the deposit. | Paid by your master wallet, in native coin. |
| Network fee of the release | Taken from the deposit. | Paid by your master wallet, in native coin. |
| Can be held for the fee | No. | Yes, until the master wallet can pay. |
| You receive | The deposit minus both fees. | The full token amount. |
Paying out from your master wallet
Section titled “Paying out from your master wallet”Released funds stay in your master wallet until you send them somewhere. A payout does that. POST/v1/payouts sends an amount of one asset on one network, from the master wallet of that network, to an address you name.
Because a payout moves money out, the API asks for more than usual:
- The key must be allowed to pay out. A new secret key cannot. It needs the
payouts:writepermission, granted when the key is created, and at least one limit: an IP allowlist (the key then pays any valid address, only in requests from those IP addresses) or a payout allowlist (the key pays only the addresses on it). See API keys. - An
Idempotency-Keyheader is required, so that a retry can never pay twice. See Idempotency. - The amount is what the destination receives, in the asset’s smallest unit.
A payout starts as pending, moves through processing and included to confirmed, or ends as failed with a failure_code. You are told by the events payout.broadcast, payout.confirmed and payout.failed.
POST/v1/payouts/{id}/cancel cancels a payout, but only until its transaction has been signed.
A failed payout sent nothing. failure_code says why it failed. One value to know is stale: the payout was not signed in time. That happens when it has waited two hours, for instance through a pause of payouts, or when cTpeWay’s payout service was restarted while it waited. A stale payout is not paid late. Create it again, with a new idempotency key.
Payouts and refunds cannot be created while your account is on hold. When cTpeWay has paused payouts for a while, for instance during maintenance, creating one is answered with status 503 and the code payouts_paused, and the dashboard shows a notice. Try again later. A payout created before the pause waits and is sent when payouts resume, unless it has waited two hours by then: it then fails as stale, with nothing sent.
cTpeWay can also pause releases to master wallets for a while. Payments are still detected and confirmed and you receive the same events; the release of a deposit simply waits, and happens within a few minutes of the pause ending.
Refunds
Section titled “Refunds”A refund is a payout that returns one payment, or part of it, to the payer: POST/v1/refunds. The same rules apply. The key needs refunds:write as well as payouts:write, the payer’s address must be on the key’s payout allowlist when the key has one (a key limited by IP address alone refunds to any valid address), and an Idempotency-Key is required. The refunds of a payment cannot add up to more than the payment.
The 0.5% platform fee charged on the original deposit is not returned. See Invoices.
In test mode
Section titled “In test mode”Test mode uses the same settlement rules on test networks, with fees charged in test coins. That lets you see a deposit go from Pending to Held to Released before you go live. See Testing.
Events
Section titled “Events”| Event | Sent when |
|---|---|
| settlement.held | A confirmed deposit is waiting in its address. |
| settlement.released | The deposit was moved to your master wallet. |
| settlement.failed | The release could not be completed. |
| master_wallet.low_balance | Deposits are held because the master wallet is short of native coin. |