API 参考

所有接口都从你的服务端调用，请求和返回都是 JSON。Webhook 地址和 API key 在商户后台管理。

基本约定

错误

失败时返回 4xx 或 5xx。请按 code 判断错误类型，message 只用于排查。

{
  "error": {
    "code": "amount_below_minimum",
    "message": "options[0].amount is below the minimum",
    "details": { "min_amount": "5.00" }
  }
}

支付单

一张支付单是一笔要用户支付的订单。用户在收银台付款，结果通过 Webhook 通知你。

低于最低收款金额的链会被排除；所有链都不满足时返回错误。默认最低金额是 5 美元，你的费率见后台项目的“费率”部分。

指定每条链的代币和金额

需要同时收多个币种，或者每条链金额不同时，用 options 代替 currency、amount 和 chains。最多 16 项，token 填符号或合约地址。

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

返回

返回 201 和支付单对象。把 checkout_url 给用户打开。

{
  "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": []
}

返回支付单对象。用于对账，或在没有收到 Webhook 时确认状态。

支付单状态

充值地址

{
  "object": "deposit_address",
  "customer": "user_42",
  "chain": "bsc",
  "address": "0x3c9A…71d2",
  "tokens": [
    { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18, "min_settle_amount": "5.00" }
  ]
}

同一个用户永远返回同一个地址，可以长期展示。只有转入 tokens 列出的代币才会入账。

每笔转账都会发 deposit.confirmed。低于 min_settle_amount 的转账同样入账，状态为 held；这个地址累积到最低金额后一起归集到你的收款地址，只收一次固定手续费。

入账

入账（deposit）是一笔计入的链上付款，来自支付单或充值地址。一张支付单可以有多笔入账。

{
  "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"
  }
}

按时间从新到旧返回。

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 }

链和代币

kokiwa 支持下面的链和币种。chains、options[].chain 填 chain 列的值，currency 填币种列的值。

测试网只有 USDT。代币是 tUSDT，currency 仍然填 USDT。

这里是可以填写的全部范围，不代表某个项目都能使用。每个商户的配置不同，实际可用的链和币种请用下面的接口查询。

返回这个 key 所属的项目在当前网络的收款能力。

{
  "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 }
      ]
    }
  ]
}

客户

可选。customer 第一次出现时会自动创建客户，只有需要在后台按标签筛选时才用这组接口。

返回标签、备注和 deposit_addresses（按链列出的充值地址）。