kokiwa

Integration guide

Your server calls the API to create a payment, and kokiwa sends you a webhook when it arrives. Funds go straight to your wallet on-chain; kokiwa never holds them.

Run the whole flow on the testnet with free test tokens first, see Testing. To see what your users see, go to Try a payment.

Before you start

All of this happens in the merchant dashboard.

  1. Sign upVerify your email, set up an authenticator app and save the recovery codes.
  2. Create a projectA project is one of your products or websites, with its own payout addresses, API keys and webhooks.
  3. Set up paymentsOn the project's Payment settings page, pick chains, payment methods and tokens, then register a payout address on each chain with your wallet. The payout address is recorded on-chain and only the wallet that registered it can change it. Registering costs your wallet a little gas; one wallet can register every EVM chain.
  4. Create an API keyThe key is shown once. Keep it in a server environment variable, never in a front end or app.
  5. Set up a webhookOn the Webhooks page, enter your https URL, save the signing secret, then click Send test event to confirm it arrives.

Choose how to get paid

Payment intentDeposit address
Best forOrders: a fixed amount, paid onceAccount top-ups: any amount, as often as the user likes
AddressOne per payment intent, retired when it expiresOne per user, permanent
How users payFrom a wallet on the checkout page; on EVM chains they can also transfer to a dedicated addressA transfer from a wallet or exchange
ChainsAll 8The 6 EVM chains, one address
gasPaid by the user for wallet payments; kokiwa pays for sweeping transfersPaid by the user for the transfer; kokiwa pays for sweeping

You can use both.

Payment intent

Create a payment intent when the user places an order and open the returned checkout_url for them. The request below offers every chain where the project accepts USDT, and the user picks one.

curl https://api.kokiwa.com/v1/payment_intents \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10086" \
  -d '{
    "currency": "USDT",
    "amount": "25.00",
    "customer": "user_42",
    "metadata": { "order_id": "10086" },
    "success_url": "https://your-shop.com/orders/10086"
  }'

Deposit address

Set customer to the user's ID in your system. Repeated calls for the same user return the same address.

curl https://api.kokiwa.com/v1/deposit_addresses \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "user_42" }'

Confirm the payment

Once a payment is confirmed on-chain, kokiwa sends a webhook. Credit users only from webhooks, never because the user came back to success_url.

  • Payment intent: on payment_intent.paid, mark the order as paid.
  • Deposit address: on deposit.confirmed, add to the balance of data.deposit.customer.

Verify the signature of every event and deduplicate by event id, see Webhooks.

Amounts

Every amount is a string in token units, such as "25.00" or "24.9125", in requests, responses and webhooks alike, so there is no per-chain conversion. Amounts keep full on-chain precision, so the number of decimal places varies. Never calculate with floating point.

Refunds

The funds are already in your wallet, so kokiwa has no refund endpoint and cannot reverse a payment. To refund, send from your payout address to the user. Ask the user for a refund address instead of using transaction.from, which is the exchange's address when they withdrew from an exchange. Fees are not returned.

Launch checklist

  • API keys are only on the server, not in code repositories or logs.
  • Webhooks verify signatures, and a repeated event is not credited twice.
  • Payment intents are created with an Idempotency-Key, so a network retry cannot create two.
  • payment_intent.paid_late is handled, so a payment that arrives after expiry is not lost.
  • Payout addresses are registered on mainnet and you switched to a key starting with sk_live_.
  • The seed phrase of your payout address is backed up.