Stablecoin Payment for
Your Online Store

特長

ECサイトにステーブルコイン決済を導入するための、すべての機能を備えています。

決済フロー

BitVoy EC Payment APIは、Payment Intent方式を採用しています。ECサイトのサーバーからIntentを発行し、顧客をBitVoy決済ページにリダイレクト。決済完了後、WebhookとリダイレクトでECサイトに結果が通知されます。

詳細シーケンス

Intent ステータス遷移

API リファレンス

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

POST /oidc-payment/intents

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

payment_start_url にユーザーをリダイレクトすると、BitVoy決済ページが表示されます。

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",
  "result": {
    "paid_at": "2026-03-20T09:01:00.000Z",
    "tx_hash": "0xf7a41da56eb6b4b276bc3c7d84d94d6944cc8fc9...",
    "chain": "avalanche",
    "paid_amount": "100"
  }
}

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))

導入手順

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

• ECサイトのドメイン — 例: shop.example.com
• 入金先ウォレットアドレス — ステーブルコインの受取先 (0x...)
• 対応する通貨・チェーン — USDC / JPYC / USDT、Avalanche / Base
• Webhook URL — 決済通知を受け取るエンドポイント
• return_url — 決済完了後のリダイレクト先

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

• client_id — クライアントID
• client_secret — クライアントシークレット
• webhook_secret — Webhook署名検証用シークレット

チェックアウト時にサーバーからBitVoy APIを呼び出し、Payment Intentを発行します。 client_secret は必ずサーバーサイドで管理し、フロントエンドに露出させないでください。

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

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

実装例

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: 'AA',   // ガスレス決済
      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決済ページにリダイレクト
  res.json({ payment_url: data.payment_start_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': 'AA',
        '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-btn">ステーブルコインで支払う</button>

<script>
document.getElementById('pay-btn').addEventListener('click', async () => {
  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'
    })
  });
  const { payment_url } = await res.json();

  // BitVoy決済ページにリダイレクト
  window.location.href = payment_url;
});
</script>

よくある質問