kokiwa

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

  1. 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.
  2. On the project's Payment settings page, register a testnet payout address and select tokens. Your wallet needs a little testnet gas.
  3. 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

CaseWhat to doCheck that your system
Normal paymentPay in full from a walletMarks the order paid on payment_intent.paid
UnderpaymentSend half to deposit_address, then the restDoes not ship after the first transfer, and ships once complete
ExpiryCreate an intent with expires_in: 60 and do not payCancels the order on payment_intent.expired
Late paymentTransfer to deposit_address after the intent expiresShips or refunds on payment_intent.paid_late
Top-upSend 10 tUSDT to the user's deposit addressAdds to the balance on deposit.confirmed
Small top-upsSend 3 tUSDT to the deposit address twiceCredits both, and receives deposit.settled after sweeping
RetriesMake your webhook URL return 500 at firstCredits once after kokiwa retries
SignatureVerify with the wrong secretRejects 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.

Mint tUSDT yourself

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.

Get tUSDT on Solana devnet

Enter your Solana wallet address and kokiwa sends 1000 tUSDT. If the wallet is short of devnet SOL, it also gets 0.02 SOL for network fees. Up to 3 claims an hour per address and per network. Switch your wallet to Devnet.

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:

Mint tUSDT on TON testnet

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 wallet

Going 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.

Connect a wallet with WalletConnect