Stablecoin Payment for
Your Online Store

特長

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

チェックアウトフロー

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

詳細シーケンス

Intent ステータス遷移

WalletConnect経由のチェックアウトフロー

Intent発行時のレスポンスには、2つのチェックアウトURLが含まれます。顧客の環境に応じて使い分けることができます。

スニペットで簡単導入

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-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
• client_secret — API直接利用時に使用（スニペット利用時は不要）
• webhook_secret — Webhook署名検証用シークレット

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

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

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

API リファレンス

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

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

POST /oidc-payment/intents

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

リクエストパラメータ

レスポンス例

{
  "intent_id": "int_01KK8VGFWGNQ62CAB3MA1N69B7",
  "status": "CREATED",
  "expires_at": "2026-03-20T09:15:00.000Z",
  "intent_token": "eyJ...",
  "payment_start_url": "https://bitvoy.org/oidc/authorize?...intent_id=int_xxx",
  "wc_payment_url": "https://bitvoy.org/wc/pay/int_xxx"
}

payment_start_url にユーザーをリダイレクトすると、BitVoyチェックアウトページが表示されます。wc_payment_url はWalletConnect対応の外部ウォレットからチェックアウトする場合のURLです。

リダイレクト時に &lang=ja または &lang=en を付与すると、決済画面の表示言語を指定できます。省略時は英語になります。

GET /oidc-payment/intents/{intent_id}

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

認証

Authorization: Basic BASE64(client_id:) または ?client_id={client_id}

レスポンス例（SUCCEEDED）

{
  "intent_id": "int_01KK8VGFWGNQ62CAB3MA1N69B7",
  "status": "SUCCEEDED",
  "amount": "100",
  "currency": "JPYC",
  "chain": "avalanche",
  "order_ref": "ORDER-12345",
  "payee": {
    "type": "address",
    "address": "0x1234...abcd"
  },
  "expires_at": "2026-03-20T09:15:00.000Z",
  "created_at": "2026-03-20T09:00:00.000Z",
  "execution_mode": "SMART",
  "metadata": { "source": "my-ec-site" },
  "result": {
    "paid_at": "2026-03-20T09:01:00.000Z",
    "tx_hash": "0xf7a41da56eb6b4b276bc3c7d84d94d6944cc8fc9...",
    "chain": "avalanche",
    "paid_amount": "100"
  }
}

注意: ステータスが FAILED の場合、fail_code と fail_reason フィールドが追加されます。

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ペイロード内の 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 express = require('express');
const app = express();

const BITVOY_API = 'https://bitvoy.org';
const CLIENT_ID = process.env.BITVOY_CLIENT_ID;
const CLIENT_SECRET = process.env.BITVOY_CLIENT_SECRET;
const WEBHOOK_SECRET = process.env.BITVOY_WEBHOOK_SECRET;
const PAYEE_ADDRESS = '0x...';  // 入金先アドレス

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

  const resp = await fetch(`${BITVOY_API}/oidc-payment/intents`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      rp_client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      order_ref: orderId,
      amount: amount,          // 例: "4500" (4500 JPYC)
      currency: currency,      // 例: "JPYC"
      payee: PAYEE_ADDRESS,
      chain: chain,            // 例: "avalanche"
      execution_mode: 'SMART',   // ガスレスチェックアウト
      return_url: `https://shop.example.com/orders/${orderId}/complete`,
      metadata: { source: 'my-ec-site' }
    })
  });

  const data = await resp.json();

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

  // ユーザーをBitVoyチェックアウトページにリダイレクト
  // payment_start_url: BitVoyウォレット（パスキー認証）
  // wc_payment_url:   外部ウォレット（WalletConnect）
  res.json({
    payment_url: data.payment_start_url,
    wc_payment_url: data.wc_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}/oidc-payment/intents/${intent_id}?client_id=${CLIENT_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 requests, os

BITVOY_API = 'https://bitvoy.org'
CLIENT_ID = os.environ['BITVOY_CLIENT_ID']
CLIENT_SECRET = os.environ['BITVOY_CLIENT_SECRET']

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

    resp = requests.post(f'{BITVOY_API}/oidc-payment/intents', json={
        'rp_client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
        'order_ref': data['order_id'],
        'amount': data['amount'],
        'currency': 'USDC',
        'payee': '0x...',
        'chain': 'base',
        'execution_mode': 'SMART',
        'return_url': f'https://shop.example.com/orders/{data["order_id"]}/complete',
    })

    intent = resp.json()
    return jsonify({'payment_url': intent['payment_start_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})

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

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

<script>
async function checkout() {
  const res = await fetch('/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      order_id: 'ORDER-12345',
      amount: '4500',
      currency: 'JPYC',
      chain: 'avalanche'
    })
  });
  return res.json();
}

// BitVoyウォレット（パスキー認証）で決済
// lang パラメータで決済画面の表示言語を指定（'ja' | 'en'）
document.getElementById('pay-bitvoy').addEventListener('click', async () => {
  const { payment_url } = await checkout();
  const lang = document.documentElement.lang || 'ja';
  window.location.href = payment_url + '&lang=' + lang;
});

// 外部ウォレット（WalletConnect）で決済
document.getElementById('pay-wc').addEventListener('click', async () => {
  const { wc_payment_url } = await checkout();
  const lang = document.documentElement.lang || 'ja';
  window.location.href = wc_payment_url + '?lang=' + lang;
});
</script>

よくある質問