加盟店向け API 連携マニュアル

ベース URL は次のとおりです。すべての API リクエストは HTTPS で送信してください。

https://voucher-pay.site

• 金額（amount）はすべて日本円・整数（税込の請求額）で指定します。
• リクエスト／レスポンスのボディは application/json です。
• 推奨は「決済セッション方式」（利用者を VOUCHER PAY の決済ページへ誘導）です。加盟店様が バウチャーコードを直接扱う「直接チャージ方式」も利用できます。

加盟店ごとに発行される API キーを、すべてのリクエストの X-API-Key ヘッダーに付与します。

X-API-Key: <あなたの API キー>
Content-Type: application/json

• API キーは VOUCHER PAY 運営が発行します。サーバー側だけで保持し、 フロントエンドやリポジトリに含めないでください。
• キーが無い／不正な場合は 401 unauthorized を返します。
• 加盟店が停止（suspended）状態の場合は 403 merchant_suspended を返します。

1. 加盟店サーバーが POST /api/v1/checkout-sessions を呼び、 決済ページの URL（checkout_url）を受け取る。
2. 利用者を checkout_url へリダイレクトする。
3. 利用者が VOUCHER PAY 上で残高を使って支払う。
4. 支払い完了後、利用者は success_url へ戻される（?session_token=… 付き）。
5. 同時に、設定済みなら加盟店の Webhook に checkout.completed が送信される。
6. 加盟店は Webhook の署名検証、または GET /api/v1/checkout-sessions/{token} による 状態確認で決済完了を確定し、注文を確定する。

重要： 注文の確定は「リダイレクト時のパラメータ」だけを根拠にせず、必ず Webhook の署名検証または状態取得 APIのいずれかでサーバー側で確認してから行ってください。

POST /api/v1/checkout-sessions

リクエスト

curl -X POST https://voucher-pay.site/api/v1/checkout-sessions \
  -H "X-API-Key: $VOUCHERPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "order_id": "order_20260910_0001",
    "success_url": "https://your-shop.example.com/orders/1001/complete",
    "cancel_url":  "https://your-shop.example.com/orders/1001/cancel"
  }'

レスポンス（201 Created）

{
  "status": "success",
  "checkout_url": "https://voucher-pay.site/checkout/cs_XXXXXXXXXXXXXXXX"
}

• 受け取った checkout_url へ利用者をリダイレクトしてください。
• 決済セッションの有効期限は作成から30分です。
• 既存の order_id を再送した場合は 200 OK で同じ URL を返します（二重にセッションを作りません）。

支払い完了後、利用者は success_url にクエリ session_token が 付与された状態で戻されます。

https://your-shop.example.com/orders/1001/complete?session_token=cs_XXXXXXXXXXXXXXXX

この session_token を使って状態取得 API（第7章）を呼び、 session_status が completed かつ order_id が一致することを確認してから注文を確定してください。

決済が完了すると、VOUCHER PAY は加盟店の Webhook URL へ次の通知を POST します。 Webhook URL と署名シークレットは、加盟店ごとに VOUCHER PAY 運営が設定します。

送信ヘッダー

X-VoucherPay-Event: checkout.completed
X-VoucherPay-Signature: sha256=<署名（16進）>
Content-Type: application/json

ボディ

{
  "event": "checkout.completed",
  "order_id": "order_20260910_0001",
  "amount": 1500,
  "transaction_id": "txn_XXXXXXXXXXXXXXXX",
  "status": "completed",
  "occurred_at": "2026-09-10T12:34:56+09:00"
}

署名の検証

署名は「受信した生のリクエストボディ」を、加盟店ごとの署名シークレットを鍵として HMAC-SHA256 で計算した値です。次のように検証してください（PHP の例）。

<?php
$secret    = getenv('VOUCHERPAY_WEBHOOK_SECRET');   // 運営から共有された署名シークレット
$payload   = file_get_contents('php://input');      // 生のボディ（JSONを再生成しない）
$header    = $_SERVER['HTTP_X_VOUCHERPAY_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (! hash_equals($expected, $header)) {
    http_response_code(400);
    exit;   // 署名不一致：処理しない
}

$data = json_decode($payload, true);
// $data['order_id'] の注文を「入金済み」として確定する処理をここに書く
http_response_code(200);   // 正常受信は 2xx を返す

配信仕様： Webhook はベストエフォートです（タイムアウト5秒・自動再送なし）。 ネットワーク障害などで届かない場合に備え、注文確定は Webhook 単独に頼らず、第7章の状態取得 API での確認を必ず併用してください。 受信側は正常時に 2xx を返してください。

GET /api/v1/checkout-sessions/{token}

{token} には、セッション作成時に得た checkout_url 末尾の cs_…（＝復帰時の session_token）を指定します。

curl https://voucher-pay.site/api/v1/checkout-sessions/cs_XXXXXXXXXXXXXXXX \
  -H "X-API-Key: $VOUCHERPAY_API_KEY"

レスポンス

{
  "status": "success",
  "session_status": "completed",
  "order_id": "order_20260910_0001",
  "amount": 1500,
  "transaction_id": "txn_XXXXXXXXXXXXXXXX"
}

• session_status は pending（未完了）または completed（完了）。
• 他の加盟店のセッションは参照できません（404）。

加盟店側で利用者からバウチャーコードを受け取り、直接決済する方式です。1枚のバウチャーコードに対して即時に課金します。

curl -X POST https://voucher-pay.site/api/v1/charge \
  -H "X-API-Key: $VOUCHERPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voucher_code":"K4X9-7QRT-2MPL","amount":1500,"order_id":"order_20260910_0001"}'

{
  "status": "success",
  "voucher_code": "K4X9-7QRT-2MPL",
  "charged_amount": 1500,
  "remaining_balance": 3500,
  "transaction_id": "txn_XXXXXXXXXXXXXXXX"
}

{
  "status": "success",
  "voucher_code": "K4X9-7QRT-2MPL",
  "refunded_amount": 1500,
  "remaining_balance": 5000
}

API キーの発行、Webhook URL・署名シークレットの設定、テスト用アカウントのご相談は、 VOUCHER PAY 運営までお問い合わせください。

運営会社情報は 運営会社ページ をご覧ください。