Simulate deposit

API key: Payment (sandbox)

Sandbox only. Creates one new deposit on the channel and drives it to the stage you ask for, emitting the same webhooks and producing the same deposit contract a real payment would. No blockchain and no provider are involved.

Request body

Parameter	Type	Required	Description
amount	string	Yes	Deposit amount as a decimal string, for example "100".
currency	string	Yes	A token enabled on the channel's project, for example USDT.
network	string	Yes	The network code the token arrives on, for example TRC20.
stage	string	No	confirming, reorged or confirmed. Defaults to confirmed.

{
  "amount": "100",
  "currency": "USDT",
  "network": "TRC20",
  "stage": "confirmed"
}

Stages

Every call starts by emitting payment_channel.deposit.confirming, exactly as a real detection does. stage decides where it stops:

Stage	Ends at	Webhooks emitted
confirming	confirming	confirming
reorged	reorged	confirming, then reorged
confirmed	confirmed	confirming, then confirmed

Each call creates a new deposit with a new pcd_. To exercise a reorg followed by re-inclusion of the same payment, use a production-like flow rather than two simulated deposits — the simulator does not re-include.

Response (200 OK)

The full deposit contract, identical in shape to Retrieve Deposit.

{
  "id": "pcd_7VjMrK3fXd9BzQ4tLnWyGh",
  "payment_channel_id": "pc_2QhKZv6mRt9WdA3nYpLbXf",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "payment_channel_external_id": "customer-42",
  "status": "confirmed",
  "is_final": true,
  "is_test": true,
  "currency": "USDT",
  "network": "TRC20",
  "chain_id": 728126428,
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "gross": "100",
  "fee": "1",
  "net": "99",
  "applied_fee_percent": 1.0,
  "customer_fee_percent": 0,
  "tx_hash": "4c8a2f61d05be79341ac6b28e5f0d97341b6ce80a2f5d3719b04ec6a582f1d37",
  "transfer_id": "sandbox:payment-channel-deposit:9a1f7c3e5b8d42069e7a15c0d3b64f28",
  "destination_address": "TQ5mVdC8yPjRs2NbHfW7ZkXe1LoAu4Tg6r",
  "block_height": 0,
  "first_included_block_timestamp": 1767225600,
  "explorer_url": "https://tronscan.org/#/transaction/4c8a2f61d05be79341ac6b28e5f0d97341b6ce80a2f5d3719b04ec6a582f1d37",
  "created_at": 1767225600,
  "updated_at": 1767225600,
  "confirmed_at": 1767225600
}

Two fields look different from a real deposit, and both are honest markers rather than accidents: block_height is 0, and transfer_id is namespaced sandbox:…. Those values are what keep a simulated row out of every chain-scanning path. The explorer_url is generated from a synthetic hash — the transaction it points at does not exist on any chain.

Sandbox money is virtual. fee and net are calculated from the deposit's own snapshot rates, and the amount lands in your sandbox balance the same way a real deposit lands in your live one.

Rules

• —The channel must be a sandbox channel and you must sign with a sandbox Payment key. A production key is rejected before anything is created.
• —currency + network must be a token enabled on the project and accepted by the sandbox catalog.
• —amount must fit the token's decimal precision. An amount with too many decimals is rejected rather than silently rounded into a different number.

Errors

Code	HTTP	When
payment_channels_disabled	503	Payment channels are not enabled for your account in this environment.
payment_key_required	403	The request was signed with a Payout (rk_) key.
payment_channel_simulation_sandbox_only	403	The channel is a production channel.
payment_channel_not_found	404	The id resolves to nothing this credential may see.
currency_not_enabled_for_project	400	The token is not enabled on the channel's project.
acceptance_disabled	503	The token is not currently accepted for collection.
amount_too_many_decimals	400	amount has more decimals than the token supports.
field_must_be_positive	400	amount is zero or negative.
field_invalid_enum	400	An unknown currency, network or stage.

See Testing for the wider sandbox workflow and Error Codes for the full catalogue.