エラートリガーテストガイド

メタデータベースのエラートリガーを使用して、サンドボックス/テスト環境で決済エラーをシミュレートします。

---

概要

Jamm決済システムは、サンドボックス/テスト環境で特定の決済エラーをシミュレートできる、メタデータベースのエラートリガー機構をサポートしています。決済メタデータにtriggerErrorキーを含めることで、実際の決済フローを通すことなく、特定のエラーレスポンスをシステムに強制的に返させることができます。

これは以下の用途に役立ちます：

• エラーハンドリングおよびWebhook処理ロジックのテスト。
• 各エラー状態をUIが正しく表示することの確認。
• 失敗シナリオ（失敗トランザクション、キャンセルされた契約）のエンドツーエンドテスト。

---

仕組み

決済メタデータにtriggerErrorキーを含め、有効なErrorType文字列を値として指定します：

{
  "metadata": {
    "triggerError": "ERROR_TYPE_PAYMENT_CHARGE_FAILED"
  }
}

システムは決済フローをインターセプトし、通常の処理を短絡して、対応するエラーレスポンスを返します。APIおよびエラータイプによっては、失敗トランザクションやキャンセル済み契約のレコードも合わせて作成し、失敗を完全にシミュレートします。

エラーコードの確認方法

トリガーされたエラーは以下で確認できます：

• マーチャントダッシュボード — 顧客詳細ページに遷移し、失敗した課金や契約に紐づくエラーコードを確認します。
• モバイルアプリ — トランザクション一覧ページで、失敗トランザクションのエラーステータスを確認します。

---

対応API

エラートリガー機構は2つのAPIサーフェスでサポートされています。

1. オンセッション決済API（コア）

buyerが決済を開始・承認する、ユーザー対向の決済フローです。

• InitiatePayment ERROR_TYPE_PAYMENT_VALIDATION_FAILEDおよびERROR_TYPE_PAYMENT_LINK_EXPIREDのみがトリガーされます。それ以外のエラータイプは無視され、決済は通常通り進行します。

• ApprovePayment すべての対応エラータイプでトリガーされます。2FA認証の後に実行されます。ワークフロー固有の副作用レコードを作成し（下記参照）、課金を伴うワークフローではcharge.fail Webhookを送信します。

📋 メタデータの参照元（オンセッション）:

• 契約ワークフロー（PAYMENT_WORKFLOW_CONTRACT）: MerchantCustomer.Metadataから読み込み
• その他のワークフロー: ChargeMetadataから読み込み

ApprovePaymentのワークフロータイプ別副作用

ワークフロー	失敗トランザクション	キャンセル済み契約	charge.fail Webhook
PAYMENT_WORKFLOW_CHARGE	あり	なし	あり
PAYMENT_WORKFLOW_ONE_TIME_CHARGE	あり	なし	あり
PAYMENT_WORKFLOW_CONTRACT	なし	あり	なし
PAYMENT_WORKFLOW_CONTRACT_WITH_CHARGE	あり	あり	あり

---

2. オフセッション決済API（マーチャント）

オフセッション課金のためのサーバー間マーチャントAPIです。

• OffSessionPayment すべての対応エラータイプでトリガーされます。失敗トランザクションレコードと決済ワークフローレコードを作成し、charge.fail Webhookを送信します。

• OffSessionPaymentAsync 上記と同じです。

📋 メタデータの参照元（オフセッション）: APIリクエストで渡されたInitialCharge.Metadataから読み込みます。

---

Webhook

triggerErrorが課金失敗を発生させると、Jammは実際の失敗時と同じWebhookを配信します。これによりWebhook連携をエンドツーエンドでテストできます：

• 配信順序: charge.createdに続いてcharge.failが配信され、それぞれ発生元のフローに一致するapi_sourceを持ちます — オンセッションApprovePaymentでは3（API_SOURCE_ON_SESSION）、オフセッションでは1/2（API_SOURCE_OFF_SESSION_SYNC/API_SOURCE_OFF_SESSION_ASYNC）。
• 対象: 課金を伴うワークフローのみ。契約のみのオンセッショントリガー（PAYMENT_WORKFLOW_CONTRACT）は課金を作成しないため、charge.failは送信されません。
• ペイロード: charge.failのペイロードには、トリガーされたErrorTypeを持つerrorオブジェクト（code、message）が含まれます。

---

対応エラータイプ

triggerErrorの値	PaymentErrorCode	説明
ERROR_TYPE_PAYMENT_VALIDATION_FAILED	BAD_REQUEST	決済リクエストのバリデーションに失敗（例: 不正な決済ID）
ERROR_TYPE_PAYMENT_CHARGE_FAILED	INTERNAL	決済課金が失敗（例: ワークフロー開始失敗）
ERROR_TYPE_PAYMENT_LINK_EXPIRED	EXPIRED	決済リンクが期限切れ
ERROR_TYPE_PAYMENT_GATEWAY_FAILED	REJECTED	決済ゲートウェイがトランザクションを拒否
ERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLE	UNDER_MAINTENANCE	決済ゲートウェイが利用不可（例: BankPayが停止中）
ERROR_TYPE_PAYMENT_CHARGE_OVER_LIMIT	OVER_LIMIT	課金金額が許容上限を超過
ERROR_TYPE_PAYMENT_CHARGE_REJECTED	KYC_REQUIRED	KYC未完了により課金を拒否
ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS	INSUFFICIENT_FUNDS	顧客のアカウント残高不足
その他の有効なErrorType	OTHER	マッピングのないエラータイプはOTHERにフォールバック

⚠️ 注: 不正または認識できないtriggerError値を渡すとBAD_REQUESTエラーが返されます。

---

例

オフセッション決済

POST /api/v1/payment/withdraw
{
  "merchant_customer_id": "mc_123",
  "charge": {
    "price": 1000,
    "description": "Test charge",
    "metadata": {
      "triggerError": "ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS"
    }
  }
}

レスポンス: PaymentErrorCode = INSUFFICIENT_FUNDSのエラー。

オンセッション決済（ChargeMetadata経由）

決済セッション作成時に、課金メタデータへトリガーを含めます：

{
  "charge": {
    "price": 500,
    "metadata": {
      "triggerError": "ERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLE"
    }
  }
}

1. InitiatePaymentは通常通り進行します（このエラータイプは開始時には扱われません）。
2. ApprovePaymentはPaymentErrorCode = UNDER_MAINTENANCEのエラーを返し、失敗トランザクションレコードを作成します。

オンセッション決済（InitiatePayment固有エラー）

開始段階のエラーをテストする場合：

{
  "charge": {
    "metadata": {
      "triggerError": "ERROR_TYPE_PAYMENT_LINK_EXPIRED"
    }
  }
}

InitiatePaymentレスポンス: PaymentErrorCode = EXPIREDのエラー（マーチャント情報とリダイレクトURLを含む）。

---

エラーレスポンス形式

オンセッション（InitiatePayment）

{
  "result": {
    "error": {
      "error_code": "PAYMENT_ERROR_CODE_EXPIRED",
      "error_message": "test error triggered: ERROR_TYPE_PAYMENT_LINK_EXPIRED",
      "merchant": {
        "token": "...",
        "name": "...",
        "logo_url": "...",
        "redirect": {
          "success_url": "...",
          "failure_url": "..."
        }
      }
    }
  }
}

オンセッション（ApprovePayment）

{
  "result": {
    "error": {
      "error_code": "PAYMENT_ERROR_CODE_INTERNAL",
      "error_message": "test error triggered: ERROR_TYPE_PAYMENT_CHARGE_FAILED"
    }
  }
}

オフセッション

標準的なConnect RPCエラーを返します。HTTPステータスは最終的なPaymentErrorCodeから導出されます：

• BAD_REQUEST、CUSTOMER_NOT_FOUND、CUSTOMER_INACTIVE → HTTP 400（Bad Request）
• NOT_FOUND → HTTP 404（Not Found）
• UNDER_MAINTENANCE → HTTP 503（Service Unavailable）
• その他のコード → HTTP 500（Internal Server Error）

💡 ステータスまとめ: 上記のトリガーエラータイプの場合、ERROR_TYPE_PAYMENT_VALIDATION_FAILEDはHTTP 400、ERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLEはHTTP 503、残りのタイプはHTTP 500を返します。