Webhook

概要

Webhookを使用すると、決済の完了、失敗、返金などのイベントをリアルタイムで受け取ることができます。 ZAFA PAYは決済ステータスが変更されると、登録されたWebhookエンドポイントにHTTP POSTリクエストを送信します。

Webhookエンドポイントは、加盟店管理画面（https://app.zafapay.com）の**「Webhook」**タブから管理できます。各エンドポイントには署名検証用の個別のWebhook Secretがあります。

Webhookエンドポイント

複数のWebhookエンドポイントを登録してイベント通知を受け取ることができます。各エンドポイントには個別のURL、シークレット、およびオプションのイベントフィルターがあります。

機能	説明
複数エンドポイント	加盟店ごとに最大16個のWebhookエンドポイントを登録可能
イベントフィルター	各エンドポイントが受信するイベントタイプを選択可能。フィルター未設定の場合、すべてのイベントを受信
エンドポイント別シークレット	各エンドポイントに署名検証用の個別のWebhook Secret（`whsec_xxx`形式）が付与
有効/無効切り替え	エンドポイントを削除せずに個別に有効化・無効化可能

Webhookエンドポイントは、加盟店管理画面の**「Webhook」**タブから作成・管理できます。

イベントタイプ

イベント	説明
`payment.succeeded`	決済が正常に完了
`payment.failed`	決済が失敗
`payment.canceled`	決済がキャンセル — マーチャントによる void(`POST /v1/payments/{id}/void`)、またはホスト型決済ページ上で顧客が 3D セキュア認証中にキャンセル
`payment.refunded`	返金が完了
`payment.chargeback`	チャージバックが発生

ペイロード

string

イベントタイプ（例: payment.succeeded）

string

トランザクションID

string

加盟店ID

string

加盟店名

string

決済ステータス（succeeded, failed, canceled, refunded, chargeback）

string

決済金額（文字列形式。例: "100.00"）

string

通貨コード

string

決済方法（card, depotなど）

string

保存されたカードのID（pmi_xxx形式）。リカーリング決済またはsave_cardを使用した場合のみ

boolean

リカーリング（継続課金）決済の場合はtrue

boolean

カードが将来の決済用に保存された場合のみtrueで含まれる

string

加盟店側の注文ID（決済作成時に指定した値）

string

商品名（決済作成時に指定した値）

string

顧客ID（決済作成時に指定した値）

string

顧客のメールアドレス（決済作成時に指定した値）

string

顧客の電話番号（決済作成時に指定した値）

string

返金済み金額（文字列形式。payment.refundedイベントのみ）

object

エラー詳細（payment.failedイベントのみ）

表示 error のプロパティ

string

統一エラーコード（例: card_declined, expired_card, insufficient_funds）

string

エラーカテゴリ: authentication, soft_decline, hard_decline, gateway_error

string

人間が読めるエラーメッセージ

string

推奨アクション: retry, contact_customer, use_different_card, none

string

カードブランド（visa, mastercard, amex, jcbなど）

string

カード番号の下4桁

string

カード名義人

number

カード有効期限（月）

number

カード有効期限（年）

string

カード発行国（ISO 3166-1 alpha-2コード、例: US, JP, SG）。BINルックアップデータが利用可能な場合のみ含まれます。

string

カードの資金源タイプ（credit, debit, prepaid）。BINルックアップデータが利用可能な場合のみ含まれます。

object

決済作成時に指定したメタデータ

string

トランザクション作成日時（ISO 8601形式）

string

Webhook送信日時（ISO 8601形式）

ペイロード例

payment.succeeded（決済成功）

{
  "event": "payment.succeeded",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "サンプルストア",
  "status": "succeeded",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "payment_method_id": "pmi_abc123",
  "is_recurring": false,
  "save_card": true,
  "external_id": "order_12345",
  "product_name": "プレミアムプラン",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-15T10:31:00Z"
}

payment_method_idはsave_cardが有効な場合、またはリカーリング決済の場合のみ含まれます
save_cardは初回決済でカードを保存した場合のみtrueで含まれます
is_recurringはリカーリング決済の場合trueになります

payment.failed（決済失敗）

{
  "event": "payment.failed",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "サンプルストア",
  "status": "failed",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "is_recurring": false,
  "external_id": "order_12345",
  "product_name": "プレミアムプラン",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "error": {
    "code": "card_declined",
    "category": "soft_decline",
    "message": "Your card was declined.",
    "recommended_action": "use_different_card"
  },
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-15T10:31:00Z"
}

errorオブジェクトはpayment.failedイベントでのみ含まれます。recommended_actionの値に応じて適切な対応を行ってください（retry, contact_customer, use_different_card, none）。

payment.canceled（決済キャンセル）

{
  "event": "payment.canceled",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "サンプルストア",
  "status": "canceled",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "is_recurring": false,
  "external_id": "order_12345",
  "product_name": "プレミアムプラン",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-15T10:32:00Z"
}

payment.canceled は以下の2つのケースで送信されます:

マーチャントによる void — 決済確定前のオーソリ/キャプチャ済み決済を POST /v1/payments/{id}/void で取り消した場合。
顧客による 3DS 中のキャンセル — ホスト型 3DS チャレンジ画面で顧客が「お支払いをキャンセル」をクリックした場合。同じ決済リンクで即座に再決済可能になります(別のカードでリトライ等)。

両ケースとも同じイベント形式です。区別が必要な場合は GET /v1/payments/{id} でトランザクションの直前状態を確認するか、独自の状態管理を併用してください。

payment.refunded（返金完了）

{
  "event": "payment.refunded",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "サンプルストア",
  "status": "refunded",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "is_recurring": false,
  "external_id": "order_12345",
  "product_name": "プレミアムプラン",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "amount_refunded": "50.00",
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-20T14:00:00Z"
}

amount_refundedフィールドはpayment.refundedイベントでのみ含まれます。部分返金の場合は返金済み金額が設定されます。

payment.chargeback（チャージバック発生）

{
  "event": "payment.chargeback",
  "transaction_id": "tx_abc123",
  "merchant_id": "acct_12345",
  "merchant_name": "サンプルストア",
  "status": "chargeback",
  "amount": "100.00",
  "currency": "usd",
  "payment_method": "card",
  "is_recurring": false,
  "external_id": "order_12345",
  "product_name": "プレミアムプラン",
  "customer_id": "cust_12345",
  "email": "customer@example.com",
  "tel": "09012345678",
  "card_brand": "visa",
  "card_last4": "4242",
  "cardholder_name": "TARO YAMADA",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "card_country": "US",
  "card_funding": "credit",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-02-01T09:00:00Z"
}

チャージバックが発生した場合、取引金額が加盟店から引き落とされる可能性があります。速やかに対応してください。

署名検証

Webhookリクエストには署名ヘッダーが含まれます。エンドポイントのWebhook Secretを使用して署名を検証することで、リクエストがZAFA PAYから送信されたことを確認できます。

署名ヘッダー

環境	ヘッダー名
Sandbox	`X-Zafapay-Signature-Sandbox`
Production	`X-Zafapay-Signature`

検証方法

署名は生のリクエストボディを、エンドポイントのWebhook Secretをキーとして HMAC-SHA256 でハッシュ化し、hexエンコードしたものです。

HMAC はJSONをパースする前の、送信されたバイト列そのものに対して計算してください。パース済みオブジェクトを再シリアライズすると（JSON.stringify(req.body)）キー順・エスケープ・空白が変わることがあり、ダイジェストが一致せず正当なWebhookが検証に失敗します。Expressの場合は express.json() ではなく express.raw() を使います。

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {
  if (!signature) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)          // Buffer または文字列。再シリアライズしたオブジェクトは使わない
    .digest('hex');

  // 一定時間比較。timingSafeEqual は長さが異なると例外を投げるため、先に長さを確認する
  if (signature.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Express.jsでの使用例
app.post('/webhooks/zafapay', express.raw({ type: 'application/json' }), (req, res) => {
  // Sandboxと本番では署名ヘッダー名が異なる
  const signature =
    req.headers['x-zafapay-signature'] || req.headers['x-zafapay-signature-sandbox'];
  // このエンドポイントのWebhook Secret（whsec_xxx形式）を使用
  const secret = process.env.ZAFAPAY_WEBHOOK_SECRET;

  // 検証に失敗したリクエストは一切処理しない（fail closed）
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 署名検証が通ってから初めてパースする
  const { event, transaction_id, status } = JSON.parse(req.body);

  switch (event) {
    case 'payment.succeeded':
      // 決済成功時の処理
      break;
    case 'payment.failed':
      // 決済失敗時の処理
      break;
    case 'payment.refunded':
      // 返金時の処理
      break;
  }

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

レスポンス

Webhookを正常に受信した場合は、HTTPステータスコード 2xx を返してください。

{
  "received": true
}

リトライ

ZAFA PAYは以下の場合にWebhookを自動的にリトライします：

HTTPステータスコード 2xx 以外が返された場合
接続タイムアウトが発生した場合（10秒）

リトライスケジュール

試行回数	失敗後の待機時間
1回目	即時送信
2回目	1分後
3回目	5分後
4回目	30分後
5回目	2時間後
6回目	6時間後

合計6回のリトライが約9時間にわたって実行されます。すべてのリトライが失敗した場合、イベントはデッドレターキュー（DLQ）に移動され、手動での対応が必要になります。

リトライによる重複通知を防ぐため、transaction_idをキーにして冪等性を確保してください。

ベストプラクティス

署名を必ず検証する

不正なリクエストを防ぐため、署名検証は必須です

冪等性を確保する

同じイベントが複数回送信される可能性があるため、transaction_idをキーにして重複処理を防いでください

すぐにレスポンスを返す

Webhook処理は非同期で行い、すぐに 200 を返してください。処理に時間がかかるとタイムアウトでリトライが発生します

エラーをログに記録する

デバッグのため、受信したペイロードと処理結果をログに記録してください

概要

Payments

Customers

トークン

Webhook

概要

Webhookエンドポイント

イベントタイプ

ペイロード

ペイロード例

payment.succeeded（決済成功）

payment.failed（決済失敗）

payment.canceled（決済キャンセル）

payment.refunded（返金完了）

payment.chargeback（チャージバック発生）

署名検証

署名ヘッダー

検証方法

レスポンス

リトライ

リトライスケジュール

ベストプラクティス

​概要

​Webhookエンドポイント

​イベントタイプ

​ペイロード

​ペイロード例

​payment.succeeded（決済成功）

​payment.failed（決済失敗）

​payment.canceled（決済キャンセル）

​payment.refunded（返金完了）

​payment.chargeback（チャージバック発生）

​署名検証

​署名ヘッダー

​検証方法

​レスポンス

​リトライ

​リトライスケジュール

​ベストプラクティス

概要

Webhookエンドポイント

イベントタイプ

ペイロード

ペイロード例

payment.succeeded（決済成功）

payment.failed（決済失敗）

payment.canceled（決済キャンセル）

payment.refunded（返金完了）

payment.chargeback（チャージバック発生）

署名検証

署名ヘッダー

検証方法

レスポンス

リトライ

リトライスケジュール

ベストプラクティス