Testing
Testnet payments are real transactions on each chain's testnet, using worthless test tokens. Payment intent statuses, deposits, sweeping and webhooks work exactly as on mainnet.
Switch to the testnet
- Turn on the Testnet switch at the top of the merchant dashboard. Your account and projects are shared; API keys, webhooks, payment settings and payment records are separate.
- On the project's Payment settings page, register a testnet payout address and select tokens. Your wallet needs a little testnet gas.
- Create an API key (starting with
sk_test_) and set up a webhook.
Make a test payment
curl https://api.kokiwa.com/v1/payment_intents \
-H "Authorization: Bearer $KOKIWA_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{ "currency": "USDT", "amount": "10.00", "customer": "test_user_1" }'Open the returned checkout_url; the checkout shows a Testnet label. Pay from a wallet, or on BNB Chain send tUSDT to the intent's deposit_address. Get tUSDT at the bottom of this page.
Fees match mainnet. At the default fees, a 10 USDT wallet payment costs 0.035 and you receive 9.965; a 10 USDT transfer costs 0.335 and you receive 9.665.
Cases to test
| Case | What to do | Check that your system |
|---|---|---|
| Normal payment | Pay in full from a wallet | Marks the order paid on payment_intent.paid |
| Underpayment | Send half to deposit_address, then the rest | Does not ship after the first transfer, and ships once complete |
| Expiry | Create an intent with expires_in: 60 and do not pay | Cancels the order on payment_intent.expired |
| Late payment | Transfer to deposit_address after the intent expires | Ships or refunds on payment_intent.paid_late |
| Top-up | Send 10 tUSDT to the user's deposit address | Adds to the balance on deposit.confirmed |
| Small top-ups | Send 3 tUSDT to the deposit address twice | Credits both, and receives deposit.settled after sweeping |
| Retries | Make your webhook URL return 500 at first | Credits once after kokiwa retries |
| Signature | Verify with the wrong secret | Rejects the request and credits nothing |
Get test tokens
Your wallet claims tUSDT from the contract, up to 1000 at a time with no limit on claims. Gas is the testnet's native coin, from its official faucet, such as the BNB Chain faucet.
Your wallet calls faucet on the test token contract and the tokens are minted to your own address. Up to 1000 per call, as often as you like; your wallet pays the gas (tBNB).
No wallet detected.
Payment intents created with an sk_test_ key are paid on the TON testnet, so switch the wallet to testnet. Get test TON from @testgiver_ton_bot in Telegram and tUSDT here:
Your TON wallet sends the public Faucet message to the tUSDT contract (kQBOp0yfL-_QhS_0IF-1TrYrfFIg7qpDKMoS3mGrMbXWd003) with 0.1 TON for gas; the unused part comes back. Up to 1000 per call, as often as you like. Scan the QR code with a TON wallet set to testnet, or open the link on your phone.
Open in walletGoing live
Register payout addresses on mainnet, create a key starting with sk_live_ and a mainnet webhook, then swap in the new key and signing secret. The API URL stays the same.