Stablecoin Payment for
Your Online Store

特長

ECサイトにステーブルチェックアウトを導入するための、すべての機能を備えています。

チェックアウトフロー

スニペットがIntent発行からチェックアウトページへのリダイレクトまでを自動で処理します。チェックアウト完了後、WebhookとリダイレクトでECサイトに結果が通知されます。

詳細シーケンス

Intent ステータス遷移

チェックアウトモードと payment_url

Intent発行時のリクエストで execution_mode を指定することで、顧客の決済手段を選択できます。レスポンスには payment_url が1つ返され、その内容はモードによって異なります。

スニペットで簡単導入

HTMLに数行のコードを貼るだけで、チェックアウトボタンが表示されます。Intent発行・為替変換・チェーン選択はすべてスニペットが自動で処理します。APIの直接呼び出しは不要です。

スニペットコード

<div id="bitvoy-checkout"
     data-client-id="YOUR_CLIENT_ID"
     data-amount="3000"
     data-shop-currency="JPY"
     data-currencies="USDC,JPYC"
     data-order-ref="order_12345"
     data-return-url="https://myshop.com/thanks"
     data-metadata='{"user_id":"12345"}'
     data-lang="ja">
</div>
<script src="https://bitvoy.org/checkout/button.js" async></script>

主なパラメータ

チェーン選択はスニペットのUIで顧客が行います。通貨ごとに対応チェーンが自動表示されます。

導入手順

登録フォームから申請してください。以下の情報をご用意いただきます:

• ECサイトのドメイン — 例: shop.example.com
• 入金先ウォレットアドレス — ステーブルコインの受取先 (0x...)
• 対応する通貨 — USDC / JPYC / USDT

登録完了後、以下の認証情報が発行されます:

• client_id — スニペットに設定するクライアントID
• webhook_secret — サーバーサイドAPI呼び出し時の X-Signature 生成 / Webhook署名検証用シークレット

チェックアウトページに上記のスニペットコードを貼り付け、data-client-id に発行されたクライアントIDを設定します。 金額・通貨・注文番号はサーバーサイドでHTMLに埋め込んでください。

intent.succeeded イベントを受け取り、注文ステータスを「支払い済み」に更新します。 必ず X-BitVoy-Signature を検証してください。

data-return-url に指定したURLでユーザーを受け取り、注文完了画面を表示します。 クエリパラメータに intent_id と txid が付与されます。

API リファレンス

スニペットを使用せず、独自のチェックアウトUIを実装したい場合に利用できるAPIです。Intent発行・ステータス確認・Webhook検証をサーバーサイドから直接制御できます。

サンプル実装として MerchantKit（ZIP） を提供しています。Express サーバー・Webhook 受信・PKCE フローを含む動作確認用サンプルです。

ベースURL: https://bitvoy.org

POST /checkout/create

Checkout Intent を発行します。ECサイトのサーバーサイドから呼び出してください。

認証

サーバーサイドからの呼び出しには X-Signature ヘッダー（HMAC-SHA256）が必要です。

X-Signature: HEX(HMAC-SHA256(JSON.stringify(requestBody), webhook_secret))

フロントエンド（スニペット）から呼び出す場合は Origin ヘッダーのドメイン照合で認証されるため X-Signature は不要です。

リクエストパラメータ

レスポンス例

{
  "intent_id": "int_01KK8VGFWGNQ62CAB3MA1N69B7",
  "payment_url": "https://bitvoy.org/oidc/authorize?...&state=int_xxx",
  "amount": "22.5",
  "currency": "USDC",
  "chain": "avalanche",
  "expires_at": "2026-03-20T09:15:00.000Z"
}

payment_url はモードによって内容が異なります。FAST / SMART モードはBitVoyウォレット（OIDC）URL、WC モードはWalletConnect URL（https://bitvoy.org/wc/pay/...）が返されます。

amount は shop_currency → currency に変換後のステーブルコイン金額（人間が読める単位）です。

GET /checkout/status/{intent_id}

Intentのステータスとチェックアウト結果を確認します。認証不要。

レスポンス例（SUCCEEDED）

{
  "intent_id": "int_01KK8VGFWGNQ62CAB3MA1N69B7",
  "status": "SUCCEEDED",
  "amount": "22.5",
  "currency": "USDC",
  "chain": "avalanche",
  "order_ref": "ORDER-12345",
  "created_at": "2026-03-20T09:00:00.000Z",
  "expires_at": "2026-03-20T09:15:00.000Z",
  "result": {
    "tx_hash": "0xf7a41da56eb6b4b276bc3c7d84d94d6944cc8fc9...",
    "paid_at": "2026-03-20T09:01:00.000Z"
  }
}

GET /checkout/rate

法定通貨 → ステーブルコインの換算レートを取得します。

クエリパラメータ

レスポンス例

{
  "rate": 0.0075,
  "shop_currency": "JPY",
  "pay_currency": "USDC",
  "converted_amount": 22.5
}

Webhook通知

Intentのステータスが変化するたびに、登録された webhook_url にPOSTリクエストが送信されます。

イベント一覧

Webhookペイロード例（intent.succeeded）

{
  "event": "intent.succeeded",
  "timestamp": "2026-03-20T09:01:00.000Z",
  "intent": {
    "intent_id": "int_01KK8VGFWGNQ62CAB3MA1N69B7",
    "status": "SUCCEEDED",
    "order_ref": "ORDER-12345",
    "amount": "100000000000000000000",
    "currency": "JPYC",
    "chain": "avalanche",
    "network": "mainnet",
    "payee": {
      "type": "address",
      "address": "0x1234...abcd"
    },
    "created_at": "2026-03-20T09:00:00.000Z",
    "expires_at": "2026-03-20T09:15:00.000Z",
    "result": {
      "paid_at": "2026-03-20T09:01:00.000Z",
      "tx_hash": "0xf7a41da56eb6b4b276bc3c7d84...",
      "chain": "avalanche",
      "network": "mainnet",
      "paid_amount": "100000000000000000000"
    }
  }
}

Webhookペイロード例（intent.refunded）

{
  "event": "intent.refunded",
  "timestamp": "2026-03-20T10:00:00.000Z",
  "intent": {
    "intent_id": "int_01KK8VGFWGNQ62CAB3MA1N69B7",
    "status": "SUCCEEDED",
    "order_ref": "ORDER-12345",
    "amount": "100000000000000000000",
    "currency": "JPYC",
    "chain": "avalanche",
    "network": "mainnet",
    "payee": {
      "type": "address",
      "address": "0x1234...abcd"
    },
    "created_at": "2026-03-20T09:00:00.000Z",
    "expires_at": "2026-03-20T09:15:00.000Z",
    "result": {
      "paid_at": "2026-03-20T09:01:00.000Z",
      "tx_hash": "0xf7a41da56eb6b4b276bc3c7d84...",
      "chain": "avalanche",
      "network": "mainnet",
      "paid_amount": "100000000000000000000"
    }
  },
  "refund": {
    "refund_id": "abc123def456...",
    "refund_to": "0xabcd...1234",
    "amount": "100000000000000000000",
    "currency": "JPYC",
    "chain": "avalanche",
    "tx_hash": "0xe3b2c91a47fd8b5e276dc3d94...",
    "refunded_at": "2026-03-20T10:00:00.000Z"
  }
}

注意: Webhookペイロード内の amount / paid_amount はminor unit（JPYC: 18桁、USDC: 6桁）です。

Webhookヘッダー

Webhookリクエストには以下のヘッダーが付与されます:

署名検証

Webhookリクエストには X-BitVoy-Signature ヘッダーが付与されます:

X-BitVoy-Signature: sha256=HEX(HMAC-SHA256(payload, webhook_secret))

実装例

Node.js (Express)

Intent発行（チェックアウト）

const crypto = require('crypto');
const express = require('express');
const app = express();

const BITVOY_API = 'https://bitvoy.org';
const CLIENT_ID = process.env.BITVOY_CLIENT_ID;
const WEBHOOK_SECRET = process.env.BITVOY_WEBHOOK_SECRET;

// チェックアウト: Intent発行 → リダイレクト
app.post('/checkout', async (req, res) => {
  const { orderId, amount, chain } = req.body;

  const body = {
    client_id: CLIENT_ID,
    order_ref: orderId,
    amount: amount,            // 例: "3000" (3000 JPY)
    shop_currency: 'JPY',       // ストアの通貨 → ステーブルコインに自動変換
    currency: 'USDC',           // 決済ステーブルコイン
    chain: chain,               // 例: "avalanche"
    execution_mode: 'FAST',     // FAST / SMART / WC
    return_url: `https://shop.example.com/orders/${orderId}/complete`,
    metadata: { user_id: String(req.session.userId) }
  };

  // X-Signature: HMAC-SHA256(JSON.stringify(body), webhook_secret)
  const signature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(body))
    .digest('hex');

  const resp = await fetch(`${BITVOY_API}/checkout/create`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Signature': signature
    },
    body: JSON.stringify(body)
  });

  const data = await resp.json();

  // intent_id を注文に紐付けて保存
  await saveIntentToOrder(orderId, data.intent_id);

  // payment_url にユーザーをリダイレクト（モードに応じた内容が返される）
  res.json({ payment_url: data.payment_url });
});

Webhook受信

const crypto = require('crypto');

app.post('/webhook/bitvoy', express.raw({ type: 'application/json' }), async (req, res) => {
  // 1. 署名を検証
  const signature = req.headers['x-bitvoy-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const payload = JSON.parse(req.body);

  // 2. intent.succeeded イベントを処理
  if (payload.event === 'intent.succeeded') {
    const { intent_id, order_ref, result } = payload.intent;

    // 注文を「支払い済み」に更新
    await updateOrderStatus(order_ref, {
      status: 'paid',
      tx_hash: result.tx_hash,
      paid_at: result.paid_at,
      intent_id: intent_id
    });
  }

  res.json({ received: true });
});

チェックアウト完了ページ（return_url）

// ユーザーがBitVoyチェックアウトページから戻ってくるURL
app.get('/orders/:orderId/complete', async (req, res) => {
  const { intent_id, txid } = req.query;
  const order = await getOrder(req.params.orderId);

  // Webhookが先に到達していれば、既に paid になっている
  // まだの場合はポーリングで確認
  if (order.status !== 'paid' && intent_id) {
    const resp = await fetch(
      `${BITVOY_API}/checkout/status/${intent_id}`
    );
    const intent = await resp.json();
    if (intent.status === 'SUCCEEDED') {
      await updateOrderStatus(order.id, { status: 'paid' });
    }
  }

  res.render('order-complete', { order, txid });
});

Python (Flask)

Intent発行

import hmac, hashlib, json, requests, os

BITVOY_API = 'https://bitvoy.org'
CLIENT_ID = os.environ['BITVOY_CLIENT_ID']
WEBHOOK_SECRET = os.environ['BITVOY_WEBHOOK_SECRET']

@app.route('/checkout', methods=['POST'])
def checkout():
    data = request.get_json()
    order_id = data['order_id']

    body = {
        'client_id': CLIENT_ID,
        'order_ref': order_id,
        'amount': data['amount'],     # 例: "3000" (3000 JPY)
        'shop_currency': 'JPY',         # ストアの通貨 → ステーブルコインに自動変換
        'currency': 'USDC',
        'chain': 'base',
        'execution_mode': 'FAST',
        'return_url': f'https://shop.example.com/orders/{order_id}/complete',
    }

    # X-Signature: HMAC-SHA256(JSON.stringify(body), webhook_secret)
    body_str = json.dumps(body, separators=(',', ':'))
    signature = hmac.new(
        WEBHOOK_SECRET.encode(), body_str.encode(), hashlib.sha256
    ).hexdigest()

    resp = requests.post(
        f'{BITVOY_API}/checkout/create',
        data=body_str,
        headers={'Content-Type': 'application/json', 'X-Signature': signature}
    )

    intent = resp.json()
    return jsonify({'payment_url': intent['payment_url']})

Webhook検証

import hmac, hashlib

@app.route('/webhook/bitvoy', methods=['POST'])
def webhook():
    payload = request.get_data()
    sig = request.headers.get('X-BitVoy-Signature', '')

    expected = 'sha256=' + hmac.new(
        WEBHOOK_SECRET.encode(), payload, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(sig, expected):
        return jsonify({'error': 'Invalid signature'}), 401

    data = request.get_json()
    if data['event'] == 'intent.succeeded':
        intent = data['intent']
        update_order(intent['order_ref'], status='paid',
                     tx_hash=intent['result']['tx_hash'])

    return jsonify({'received': True})

フロントエンド（チェックアウトボタン）

フロントエンドからはECサイト自身のバックエンド経由でIntent発行し、受け取った payment_url にリダイレクトします。execution_mode をバックエンドに渡すことでBitVoy / WalletConnect を切り替えられます。

<button id="pay-bitvoy">BitVoyウォレットで支払う</button>
<button id="pay-wc">外部ウォレットで支払う（MetaMask等）</button>

<script>
async function createCheckout(executionMode) {
  const res = await fetch('/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      order_id: 'ORDER-12345',
      amount: '3000',    // JPY建て金額
      chain: 'avalanche',
      execution_mode: executionMode
    })
  });
  return res.json();
}

// BitVoyウォレット（FAST / SMART モード）で決済
document.getElementById('pay-bitvoy').addEventListener('click', async () => {
  const { payment_url } = await createCheckout('FAST');
  window.location.href = payment_url;
});

// 外部ウォレット（WalletConnect）で決済
document.getElementById('pay-wc').addEventListener('click', async () => {
  const { payment_url } = await createCheckout('WC');
  window.location.href = payment_url;
});
</script>

よくある質問

旧API（/oidc-payment/intents）のドキュメントは EC Payment API V1 を参照してください。