kokiwa

API reference

Call every endpoint from your server. Requests and responses are JSON. Webhook URLs and API keys are managed in the merchant dashboard.

EndpointPurpose
POST /v1/payment_intentsCreate a payment intent
GET /v1/payment_intents/{id}Retrieve a payment intent
POST /v1/deposit_addressesGet a user's deposit address
GET /v1/depositsList deposits
GET /v1/deposits/{id}Retrieve a deposit
GET /v1/chainsSee the project's chains and tokens
PUT /v1/customers/{external_id}Add tags and notes to a user (optional)
GET /v1/customers/{external_id}Retrieve a user (optional)

Conventions

Base URLhttps://api.kokiwa.com, for both mainnet and testnet.
AuthenticationHeader Authorization: Bearer sk_…. Keys starting with sk_live_ reach mainnet and keys starting with sk_test_ reach the testnet; their data is fully separate. A key can only reach its own project.
AmountsStrings in token units, such as "25.00". Requests allow up to 6 decimal places; responses keep full on-chain precision, so the number of places varies. Only transaction.raw_amount is the raw on-chain value.
TimesISO 8601 UTC, such as 2026-11-02T08:30:00Z.
AddressesEVM addresses are returned in EIP-55 checksum format. Show them unchanged and ignore case when comparing.
IdempotencyPOST requests can send Idempotency-Key (up to 255 characters). A retry with the same key returns the first result with the response header Idempotent-Replayed: true.

Errors

Failures return 4xx or 5xx. Branch on code; message is for debugging only.

{
  "error": {
    "code": "amount_below_minimum",
    "message": "options[0].amount is below the minimum",
    "details": { "min_amount": "5.00" }
  }
}
HTTPcodeMeaning
400invalid_*Invalid parameter; message names the field.
400chain_not_enabledThe project has no active payout address on this chain, or has turned payments off there.
400chain_not_availableThis chain does not take payments right now.
400chain_not_supportedThis chain has no deposit addresses.
400token_not_enabledThe project has not selected this token.
400currency_not_availableThe project cannot accept this currency on any chain.
400deposits_disabledThe project has turned deposit addresses off.
400amount_below_minimumBelow the minimum amount, given in details.min_amount.
401unauthorizedThe API key is missing, invalid or revoked.
403project_disabledThe project is disabled.
404not_foundThe resource does not exist or belongs to another project.
409request_in_progressA request with the same Idempotency-Key is still running. Retry shortly.
422idempotency_key_reusedThe same Idempotency-Key was used with a different request.
500internal_errorServer error. Retry later with the same Idempotency-Key.

Payment intents

A payment intent is an order for the user to pay. The user pays on the checkout page and you get the result by webhook.

Create a payment intent

POST/v1/payment_intents
ParameterDescription
currency requiredCurrency, such as USDT. See currencies in GET /v1/chains.
amount requiredToken amount with up to 6 decimal places, such as "25.00".
chainsOnly accept payment on these chains, such as ["bsc", "base"]. By default, every chain where the project accepts this currency.
customerThe user's ID in your system: 1 to 128 letters, digits or _ - . : @.
expires_inLifetime in seconds, 60 to 604800 (7 days). Default 1800 (30 minutes).
metadataAny JSON object, up to 50 keys and 8KB, returned unchanged by the API and webhooks. A good place for your order number.
success_urlThe https URL the checkout returns to after payment.
cancel_urlThe https URL the checkout returns to when the user clicks Cancel.

Chains where the amount is below the minimum are left out; if none remain, the request fails. The default minimum is 5 USD; your fees are in the Fees section of the project in the dashboard.

Set the token and amount per chain

To accept several currencies, or a different amount per chain, send options instead of currency, amount and chains. Up to 16 items; token is a symbol or contract address.

"options": [
  { "chain": "bsc", "token": "USDT", "amount": "25.00" },
  { "chain": "bsc", "token": "USDC", "amount": "25.00" }
]

Response

Returns 201 and the payment intent. Open checkout_url for the user.

{
  "id": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "object": "payment_intent",
  "status": "pending",
  "livemode": true,
  "customer": "user_42",
  "checkout_url": "https://pay.kokiwa.com/p/pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "metadata": { "order_id": "10086" },
  "success_url": "https://your-shop.com/orders/10086",
  "cancel_url": null,
  "created_at": "2026-11-02T08:30:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "paid_at": null,
  "paid_option": null,
  "options": [
    {
      "id": "pio_5Hq2Tz8rLw0aVb3Kc9XyN1",
      "chain": "bsc",
      "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": "0x8b1F…c04E"
    },
    {
      "id": "pio_2Mn7Xc4bQe6uJs1Ga8RvK3",
      "chain": "base",
      "token": { "symbol": "USDT", "address": "0xfde4…9bb2", "decimals": 6 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": null
    }
  ],
  "deposits": []
}
FieldDescription
optionsWhat the user can choose from: one token on one chain per item.
options[].receivedAmount received for this item so far.
options[].deposit_addressThe dedicated transfer address for this payment intent, which you can also show on your own page. null when that method is not available (chains other than BNB Chain, or a very small amount).
paid_optionThe options[].id the user actually paid.
depositsEvery deposit credited to this payment intent, oldest first. See the deposit object.
livemodetrue on mainnet, false on the testnet.

Retrieve a payment intent

GET/v1/payment_intents/{id}

Returns the payment intent. Use it for reconciliation, or to check the status when a webhook has not arrived.

Payment intent status

statusDescription
pendingWaiting for payment.
partially_paidTransfers to the dedicated address fall short by amount − received. Do not ship; it becomes paid once the user pays the rest.
paidPaid in full, ready to ship. Any overpayment also counts in received; kokiwa does not return it.
expiredExpired without payment.
paid_lateFunds reached the dedicated address after expiry. The money is yours: decide whether to ship or refund.

Deposit addresses

Get a customer's deposit address

POST/v1/deposit_addresses
ParameterDescription
customer requiredThe user's ID in your system, same rules as payment intents. The user is created on first use.
chainAn EVM chain: bsc, ethereum, arbitrum, base, polygon, optimism. Default bsc. A customer has the same address on every EVM chain.
{
  "object": "deposit_address",
  "customer": "user_42",
  "chain": "bsc",
  "address": "0x3c9A…71d2",
  "tokens": [
    { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18, "min_settle_amount": "5.00" }
  ]
}

The same user always gets the same address, so you can show it long term. Only the tokens in tokens are credited.

Every transfer sends deposit.confirmed. Transfers below min_settle_amount are credited too, with status held; once the address has accumulated the minimum, they are swept to your payout address together for one fixed fee.

Deposits

A deposit is one credited on-chain payment, from a payment intent or a deposit address. A payment intent can have several.

{
  "id": "dep_9Kx2Pa6Wn3Ty8Lq5Rb1Ms4",
  "object": "deposit",
  "status": "settled",
  "method": "wallet",
  "chain": "bsc",
  "customer": "user_42",
  "payment_intent": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
  "amount": "25.00",
  "fee": "0.0875",
  "net": "24.9125",
  "usd_value": "25.00",
  "confirmed_at": "2026-11-02T08:41:07Z",
  "transaction": {
    "hash": "0x4e7a…91c3",
    "log_index": 212,
    "block_number": 44718235,
    "block_time": "2026-11-02T08:40:58Z",
    "from": "0x1f9C…a2B0",
    "to": "0x7d3E…09f1",
    "raw_amount": "25000000000000000000"
  },
  "settlement": {
    "tx_hash": "0x4e7a…91c3",
    "by": "payment",
    "settled_at": "2026-11-02T08:40:58Z"
  }
}
FieldDescription
methodwallet: paid from a wallet. deposit_address: transferred to an address.
customerThe user ID you sent, or null.
payment_intentThe payment intent it belongs to; null for deposit addresses.
amount、fee、netWhat the user paid, the fee, and what you receive. While held, fee is 0 and is set at sweeping.
usd_valueamount in US dollars at the token price set by kokiwa.
transactionThe user's payment on-chain, which you can check on a block explorer. When a transaction has several transfers, hash + log_index identify one. from is not always the user's own wallet: after an exchange withdrawal it is the exchange's address. raw_amount is the raw on-chain value of the transfer in the token's smallest unit, only for checking against a block explorer.
settlementThe transaction that reached your payout address, or null until settled. by is payment (settled by the payment itself), kokiwa (swept by kokiwa) or owner (reclaimed with your own wallet, no fee). Deposits swept together share a tx_hash.
statusDescription
confirmedConfirmed on-chain, waiting to be swept to your payout address. You can credit the user.
heldConfirmed on-chain, too small to sweep yet. You can credit the user.
settledReached your payout address.

Retrieve a deposit

GET/v1/deposits/{id}

List deposits

GET/v1/deposits

Newest first.

Query parameterDescription
customerOnly this user.
tx_hashFind by the hash of the payment or settlement transaction.
limitPage size, 1 to 100. Default 20.
starting_afterThe id of the last item on the previous page.
curl "https://api.kokiwa.com/v1/deposits?tx_hash=0x4e7a…91c3" \
  -H "Authorization: Bearer $KOKIWA_KEY"

{ "object": "list", "data": [ { "id": "dep_9Kx2…", "object": "deposit", ... } ], "has_more": false }

Chains and tokens

kokiwa supports the chains and currencies below. Use the chain column for chains and options[].chain, and the currency column for currency.

chainBlockchainCurrenciesPayment methods
bscBNB ChainUSDT, USDCwallet, deposit_address
ethereumEthereumUSDT, USDCwallet, deposit_address
arbitrumArbitrumUSDT, USDCwallet, deposit_address
baseBaseUSDT, USDCwallet, deposit_address
polygonPolygonUSDT, USDCwallet, deposit_address
optimismOptimismUSDT, USDCwallet, deposit_address
tonTONUSDTwallet
solanaSolanaUSDT, USDCwallet

Testnet takes USDT only. The token is tUSDT, but currency is still USDT.

This is the full range of values, not what a given project can accept. Each merchant's setup differs, so check what is available with the endpoint below.

List the project's chains and tokens

GET/v1/chains

Returns what the key's project can accept on the current network.

{
  "object": "list",
  "livemode": true,
  "currencies": ["USDT"],
  "data": [
    {
      "object": "chain", "chain": "bsc", "name": "BNB Smart Chain", "chain_id": 56, "testnet": false, "native": "BNB",
      "payout_registered": true, "active": true,
      "methods": { "wallet": true, "deposit_address": true },
      "tokens": [
        { "symbol": "USDT", "asset": "USDT", "address": "0x55d398326f99059fF775485246999027B3197955", "decimals": 18, "accepted": true },
        { "symbol": "USDC", "asset": "USDC", "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "decimals": 18, "accepted": false }
      ]
    }
  ]
}
FieldDescription
currenciesCurrencies you can send as currency right now.
data[].chainThe value for chain and options[].chain: bsc, ethereum, arbitrum, base, polygon, optimism, ton, solana.
data[].activeWhether the chain can take payments now: payout registered, a payment method on, and a token selected.
data[].tokens[].assetThe token's currency. Tokens with the same asset are equivalent across chains.
data[].tokens[].acceptedWhether the project selected this token.

Customers

Optional. A customer is created the first time a customer value appears; you only need these endpoints to filter by tag in the dashboard.

Set a customer's label and note

PUT/v1/customers/{external_id}
ParameterDescription
tagsUp to 20 tags of 1 to 64 letters, digits or _ - . :.
metadataAny JSON object, up to 50 keys and 8KB.

Retrieve a customer

GET/v1/customers/{external_id}

Returns the tags, notes and deposit_addresses (deposit addresses by chain).