api.vouchereto.com/v1

Vouchereto API で開発する

バウチャーを受け取り、お客さまに紐づけ、貴社プラットフォームの残高に変える。そのためだけのシンプルな REST API です。

ベース URL: api.vouchereto.com/v1
テスト・本番: vch_test_… と vch_live_… のキー
認証: Bearer キー + HMAC-SHA256
形式: JSON · 金額は最小通貨単位

はじめてのバウチャー利用処理

キーを取得
加盟店ポータルでテストキーを作成します。キー全体が表示されるのは1回だけです。キーの末尾部分は、リクエストの署名に使うシークレットでもあります。
バウチャーを予約
コード、通貨、お客さまの参照 ID を送信します。バウチャーはそのお客さまに紐づき、ほかでは使えなくなります。
反映してから確定
貴社側で残高を反映してから確定します。チャージが失敗した場合はキャンセルすると、バウチャーは解放されます。
Webhook を受信
エンドポイントを登録すると、確定・キャンセル・期限切れ・チェックアウトの署名付きイベントを受け取れます。

バウチャー利用 · 例

POST /v1/redemptions
Authorization: Bearer vch_test_…
Idempotency-Key: topup-88213
Vouchereto-Signature: t=1790500000,v1=9c1e5f07…
Content-Type: application/json

{ "code": "7K2M-9QXR-4HTB-2WNZ", "customer_ref": "acct_48213", "currency": "USD" }

# 201 Created
{ "id": "5f0c2a7e-…", "object": "redemption", "status": "reserved",
  "amount_minor": 5000, "currency": "USD", "voucher_last4": "2WNZ",
  "customer_ref": "acct_48213", "livemode": false,
  "expires_at": "2026-09-27T14:12:00Z", "captured_at": null }

# Credit the customer first, then capture. Irreversible.
POST /v1/redemptions/5f0c2a7e-…/capture
Authorization: Bearer vch_test_…
Idempotency-Key: topup-88213-capture
Vouchereto-Signature: t=1790500012,v1=4b7d2e91…

# 200 OK
{ "id": "5f0c2a7e-…", "object": "redemption", "status": "captured",
  "captured_at": "2026-09-27T14:02:31Z", … }

# The top-up failed: release the voucher back to the customer
POST /v1/redemptions/5f0c2a7e-…/cancel
Authorization: Bearer vch_test_…
Idempotency-Key: topup-88213-cancel
Vouchereto-Signature: t=1790500015,v1=77aa01c3…

# 200 OK
{ "id": "5f0c2a7e-…", "object": "redemption", "status": "cancelled", … }

// Vouchereto-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + rawBody)>
// secret = the whsec_… signing secret of your webhook endpoint
import crypto from "node:crypto";

export function verifyWebhook(rawBody, header, secret) {
  const parts = header.split(",").map((p) => p.trim().split("="));
  const t = Number(parts.find(([k]) => k === "t")?.[1]);
  const sigs = parts.filter(([k]) => k === "v1").map(([, v]) => Buffer.from(v, "hex"));
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return sigs.some((s) => s.length === expected.length && crypto.timingSafeEqual(s, expected));
}

バウチャー利用のライフサイクル

有効なバウチャー予約済み

確定済みバウチャーは使用済みです。取り消しはできません。
キャンセル済みキャンセルされました。バウチャーは再び有効になります。
予約期限切れ時間内（標準15分）に確定されませんでした。バウチャーは再び有効になります。

実装のポイント

リクエストの署名

すべてのリクエストに Vouchereto-Signature ヘッダーを付けます。内容はタイムスタンプと、タイムスタンプ・メソッド・パス・ボディから API キーのシークレットで計算した HMAC-SHA256 です。時刻のずれは最大300秒まで許容します。

sign.js

// Sign every request with the secret part of your API key (the text after the last "_")
const t = Math.floor(Date.now() / 1000);
const payload = `${t}.${method} ${pathWithQuery}\n${body}`;
const v1 = crypto.createHmac("sha256", keySecret).update(payload).digest("hex");
headers["Vouchereto-Signature"] = `t=${t},v1=${v1}`;

冪等性

すべての POST には Idempotency-Key ヘッダーが必要です。同じキーでリクエストを繰り返すと、最初のレスポンスが Idempotent-Replayed: true 付きで返されます。キーの保持期間は最低30日間です。

サンドボックス用バウチャー

テストキーで POST /v1/sandbox/vouchers を呼び出すと、指定した状態（active、reserved、redeemed、expired、risk_hold、void）のテスト用バウチャーが作成され、そのコードが返されます。テストキーからはテストデータしか参照できません。

Webhook イベント

エンドポイントに送信されるイベント
イベント	送信されるタイミング
redemption.captured	予約済みのバウチャーが確定されました。反映した残高はそのまま維持して問題ありません。
redemption.cancelled	予約がキャンセルされました。バウチャーは再び有効になります。
redemption.expired	予約が確定されないまま期限切れになりました。
checkout.completed	ホスト型チェックアウトで支払いが完了し、バウチャーが適用されました。
checkout.expired	ホスト型チェックアウトのセッションが支払いなしで期限切れになりました。
checkout.failed	支払い済みのチェックアウトが取り消されました（返金時など）。

エラー

エラーコードとお客さまへの案内
ステータス	コード	お客さまへの案内
404	VOUCHER_INVALID	コードが見つかりません。ご確認のうえ、もう一度お試しください。
409	VOUCHER_ALREADY_REDEEMED	このバウチャーはすでに利用されています。
409	VOUCHER_RESERVED	このバウチャーは現在、別の支払いで使用中です。
422	VOUCHER_EXPIRED	このバウチャーは有効期限が切れています。
422	UNIVERSAL_NOT_ACCEPTED	ユニバーサルバウチャーはご利用いただけません。このサイト専用のバウチャーをご利用ください。
422	CURRENCY_MISMATCH	このバウチャーは別の通貨です。
429	TOO_MANY_INVALID_ATTEMPTS	試行回数が多すぎます。数分待ってから、もう一度お試しください。

エラーは RFC 7807（application/problem+json）に準拠し、固定のコードと request_id を含みます。

このページは API の概要です。すべてのフィールドを含むリファレンスは www.vouchereto.com/docs/reference で公開しています。

お困りですか？

[DEVELOPER SUPPORT EMAIL] までご連絡ください。すべてのメッセージに開発者が目を通します。

Vouchereto API で開発する

はじめてのバウチャー利用処理

キーを取得

バウチャーを予約

反映してから確定

Webhook を受信