API リファレンス

すべてのエンドポイントはサーバーから呼び出します。リクエストとレスポンスは JSON です。Webhook の URL と API キーはマーチャント管理画面で管理します。

基本ルール

エラー

失敗時は 4xx または 5xx を返します。エラーの種類は code で判断し、message は調査用にのみ使ってください。

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

支払い

支払いは、ユーザーに支払ってもらう 1 件の注文です。ユーザーはチェックアウトで支払い、結果は Webhook で通知されます。

最低受取額を下回るチェーンは除外され、すべて下回る場合はエラーになります。既定の最低額は 5 米ドルです。手数料は管理画面のプロジェクトの「手数料」で確認できます。

チェーンごとにトークンと金額を指定する

複数の通貨を受け取る場合や、チェーンごとに金額が異なる場合は、currency、amount、chains の代わりに options を使います。最大 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 です。このアドレスの累計が最低額に達すると受取アドレスへまとめて回収し、固定手数料は 1 回分だけかかります。

入金記録

入金記録（deposit）は、計上された 1 件のオンチェーン支払いで、支払いまたは入金アドレスから発生します。1 つの支払いに複数ある場合があります。

{
  "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 のままです。

これは指定できる値の全範囲で、どのプロジェクトでもすべて使えるという意味ではありません。設定は加盟店ごとに異なるため、実際に使えるチェーンと通貨は下の API で確認してください。

このキーのプロジェクトが現在のネットワークで受け取れるものを返します。

{
  "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（チェーン別の入金アドレス）を返します。