導入ガイド

サーバーから API で支払いを作成すると、着金時に kokiwa が Webhook で通知します。資金はオンチェーンで直接あなたのウォレットに入り、kokiwa は預かりません。

まずテストネットで無料のテストトークンを使って全体を試してください。テストを参照。ユーザーに見える画面は支払いを体験で確認できます。

準備

登録メールアドレスを確認し、認証アプリを設定して、リカバリーコードを保存します。
プロジェクトを作成プロジェクトは 1 つの製品やサイトに対応し、受取アドレス、API キー、Webhook を個別に持ちます。
受け取りを設定プロジェクトの「受け取り設定」でチェーン、受取方法、トークンを選び、チェーンごとにウォレットで受取アドレスを登録します。受取アドレスはオンチェーンに記録され、登録したウォレットだけが変更できます。登録には少額のガス代がかかります。1 つのウォレットですべての EVM チェーンを登録できます。
API キーを作成キーは一度だけ表示されます。サーバーの環境変数に保存し、フロントエンドやアプリには入れないでください。
Webhook を設定「Webhook」ページで https の受信 URL を入力し、署名シークレットを保存してから「テストイベントを送信」で受信を確認します。

受け取り方を選ぶ

	支払い	入金アドレス
向いている用途	注文：金額が決まっていて 1 回で支払う	残高チャージ：金額はユーザー次第で、何度でも可能
アドレス	支払いごとに 1 つ、期限切れで無効	ユーザーごとに 1 つ、ずっと同じ
ユーザーの支払い方法	チェックアウトでウォレットから支払う。BNB Chain では専用アドレスへの送金も可能	ウォレットや取引所から送金
チェーン	全 8 チェーン	BNB Chain
gas	ウォレット支払いはユーザーが負担。送金の回収は kokiwa が負担	送金はユーザーが負担。回収は kokiwa が負担

両方を併用できます。

支払い

ユーザーの注文時に支払いを作成し、返された checkout_url を開いてもらいます。次のリクエストは、プロジェクトが USDT を受け取れるすべてのチェーンを表示し、ユーザーが 1 つ選びます。

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

入金アドレス

customer には自社システムのユーザー ID を指定します。同じユーザーで何度呼んでも同じアドレスが返ります。

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

入金を確認する

支払いがオンチェーンで確定すると、kokiwa が Webhook を送ります。Webhook だけを根拠に入金処理してください。ユーザーが success_url に戻ったことを根拠にしないでください。

支払い：payment_intent.paid を受け取ったら注文を支払い済みにします。
入金アドレス：deposit.confirmed を受け取ったら data.deposit.customer の残高を増やします。

すべてのイベントで署名を検証し、イベントの id で重複を除いてください。Webhook を参照。

金額

金額はすべてトークン数量の文字列です（例："25.00"、"24.9125"）。リクエスト、レスポンス、Webhook で共通なので、チェーンごとの換算は不要です。オンチェーンの精度をそのまま保つため、小数の桁数は一定ではありません。浮動小数点で計算しないでください。

返金

資金はすでにあなたのウォレットにあるため、kokiwa に返金 API はなく、支払いを取り消すこともできません。返金は受取アドレスからユーザーへ送金してください。transaction.from にそのまま返さず、ユーザーに返金先を確認してください。取引所から出金した場合、それは取引所のアドレスです。手数料は返還されません。

公開前のチェック

API キーはサーバーにのみあり、コードリポジトリやログに含まれていない。
Webhook で署名を検証し、同じイベントが重複しても二重に入金処理しない。
支払い作成時に Idempotency-Key を付け、ネットワークの再試行で 2 件作成されない。
payment_intent.paid_late を処理し、期限後の着金を取りこぼさない。
メインネットで受取アドレスを登録し、sk_live_ で始まるキーに切り替えた。
受取アドレスのシードフレーズをバックアップした。

次へ：テスト