Home
>
Docs
>
>

エラーリファレンス

Jamm決済APIを利用する加盟店が遭遇しうるすべてのエラーコード、Webhook失敗理由、ステータス値のリファレンス。

本ページでは、Jamm決済APIを利用する加盟店が遭遇しうるエラーコード、Webhook失敗理由、ステータス値を一覧化しています。

失敗した決済のトリアージ、連携の問題のデバッグ、リトライ判断の参考としてご活用ください。


1. エラーが加盟店に伝わる経路

エラーは3つの経路で加盟店に届きます。経路は処理が同期・非同期・ポーリングのいずれかによって決まります。

経路タイミングペイロード
同期レスポンスAPIコールへの即時レスポンス — 4xx/5xx拒否、または失敗statusを含む200code + message(non-2xxの場合)またはstatus enum(200ボディの場合)
Webhookイベント非同期プッシュ — 課金・返金・契約の結果が確定したとき配信イベント上のerror.code + error.message
ステータス取得非同期プル — 課金または契約の現在の状態を取得status enum(FAILURE / FAILEDの場合はerrorも)

下記にカタログ化されているエラーコード(ON_SESSION_PAYMENT_ERROR_CODE_*ERROR_TYPE_*など)は安定しており、大文字小文字を区別します — 切り分けに使用しても安全です。各コードがレスポンスのどこに現れるかはSDKによって異なります:

  • 生HTTP(Connect RPC): details[].debugに含まれます。トップレベルのcodeは汎用プロトコルコード(invalid_argumentinternalなど)です。
  • SDKのエラーオブジェクト: 通常errorType / error_typeとして公開されるか(Java、Ruby)、details[]を辿る必要があります(Node、PHP)。

注: messageフィールドは人間が読むためのもので、変更される可能性があります — 分岐に使わないでください。


2. On-Session Paymentエラー

/v1/payments/on-sessionから返却されます。リクエスト拒否エラー(下記のOnSessionPaymentErrorCode_*)は同期的に返却されます。顧客がJammホスティングの決済ページを完了した後、最終的な課金結果はERROR_TYPE_*コードとしてEVENT_TYPE_CHARGE_FAIL Webhook(または課金のポーリング)で配信されます — カタログはSection 3. Charge processing errorsを参照してください。

OnSessionPaymentErrorCode(リダイレクト前にリクエストが拒否された場合)

Code意味リトライ可否
ON_SESSION_PAYMENT_ERROR_CODE_MISSING_REDIRECT_URLSsuccess_urlまたはfailure_urlが未指定不可 — リクエストを修正してください
ON_SESSION_PAYMENT_ERROR_CODE_MISSING_REQUIRED_PARAMETERS顧客IDまたはbuyer情報のいずれも未指定不可 — リクエストを修正してください
ON_SESSION_PAYMENT_ERROR_CODE_MISSING_CHARGE既存顧客フローで課金情報が欠落不可 — リクエストを修正してください
ON_SESSION_PAYMENT_ERROR_CODE_CUSTOMER_NOT_FOUND加盟店顧客IDが見つかりません不可
ON_SESSION_PAYMENT_ERROR_CODE_CUSTOMER_INACTIVE顧客は存在しますが課金が有効化されていません不可 — 新しい決済リンクを顧客に提供してください(On-Session PaymentのAPIリファレンス参照)
ON_SESSION_PAYMENT_ERROR_CODE_VALIDATION_FAILEDリクエストフィールドのバリデーションエラー(例: buyer.emailの形式不正、redirect.*urlの無効値、必須スカラーの欠落)。具体的なフィールドはmessageを確認してください。不可
ON_SESSION_PAYMENT_ERROR_CODE_STRATEGY_EXECUTION_FAILED決済準備中に問題が発生しました。原因はmessageを確認してください — 例えば “failed to get merchant” は加盟店アカウントのオンボーディングが未完了であることを示します。状況による — messageが一時的なエラーを示す場合のみリトライ可
ON_SESSION_PAYMENT_ERROR_CODE_INTERNAL_ERROR想定外の内部エラー。多くは一時的です。可 — バックオフ付きでリトライ

BuyerメールアドレスのOn-Sessionリクエストのbuyer.emailが同じ加盟店IDで既に登録されているアクティブな顧客と一致する場合、既存の顧客が再利用され(同じcus-* IDが返却されます)、指定されたフィールドは既存レコードを更新します。重複はリクエスト拒否されません。事前に重複を検出したい場合は、加盟店ダッシュボードのList Customersセクションでメールアドレスから既存顧客を検索してください。


3. Charge processing errors(on-session & off-session)

これらのERROR_TYPE_*コードは両方のフローでの課金失敗に使用されます:

  • Off-session/v1/payments/off-session/async(および廃止予定の/v1/payments/off-session)から返却されます。非同期エンドポイントが推奨される連携方式です: HTTP 200でリクエストを受け付け、GetChargeでフォローアップするためのcharge_idtrx-…)を返却し、失敗はWebhook経由で通知されます。
  • On-session — リダイレクトフロー失敗後、EVENT_TYPE_CHARGE_FAIL Webhook(または課金のポーリング)で通知されます。
ErrorTypeDefault message原因対象リトライ可否
ERROR_TYPE_PAYMENT_VALIDATION_FAILEDInvalid payment request. Review input data.不正な入力、または削除・無効な顧客両方不可
ERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLEPayment gateway currently unavailableBankPayまたは銀行のメンテナンス中両方
ERROR_TYPE_PAYMENT_GATEWAY_FAILEDPayment gateway rejected requestBankPayが取引を拒否両方不可
ERROR_TYPE_PAYMENT_CHARGE_FAILEDPayment failed. Please contact Jamm support.内部エラー、未検出、キャンセル、または重複両方状況による
ERROR_TYPE_PAYMENT_CHARGE_REJECTEDCustomer has not completed KYCKYC未完了(Off-Session: forceKyc=true、On-Session: リダイレクト中に顧客がKYCを完了しなかった)両方不可
ERROR_TYPE_PAYMENT_CHARGE_OVER_LIMITPayment exceeds allowed limit銀行のクォータを超過両方不可
ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDSCustomer has insufficient funds顧客の残高不足両方不可
ERROR_TYPE_PAYMENT_LINK_EXPIREDPayment link has expired顧客が決済を完了する前にリダイレクトリンクが期限切れOn-Sessionのみ不可
ERROR_TYPE_PAYMENT_CUSTOMER_NOT_FOUNDCustomer ID not found参照された顧客がこの加盟店配下に存在しません両方不可
ERROR_TYPE_PAYMENT_CUSTOMER_INACTIVECustomer is not active. Issue a new payment link for them to complete.顧客は存在しますが、有効な契約がありません両方不可

非同期課金の場合、/v1/charge/{charge}で課金を取得してください。最終結果はChargeResult(またはEVENT_TYPE_CHARGE_FAIL Webhook)に含まれます。

例: EVENT_TYPE_CHARGE_FAIL Webhookペイロード

加盟店が設定したWebhook URLへのHTTP POSTで配信されます。トップレベルのフィールドはsnake_caseです。

{
  "id": "mwh-abc123xyz",
  "signature": "sha256=cc30ff809e21445817412de797ed2ca7cde7dea3f0844dcf20753edaaffe252c",
  "created_at": "2026-05-19T10:05:00Z",
  "event_type": "EVENT_TYPE_CHARGE_FAIL",
  "content": {
    "id": "trx-abc123xyz",
    "customer": "cus-abc123xyz",
    "description": "Order #1234",
    "merchant_name": "Merchant Co.",
    "initial_amount": 200,
    "discount": 2,
    "final_amount": 198,
    "currency": "JPY",
    "created_at": "2026-05-19T10:00:00Z",
    "updated_at": "2026-05-19T10:05:00Z",
    "error": {
      "code": "ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS",
      "message": "Customer has insufficient funds"
    }
  }
}

例: GetChargeレスポンス(CHARGE_STATUS_FAILURE

失敗した課金をポーリングするとき、GET /v1/charge/{charge}で返却されます。errorフィールドはchargeStatusCHARGE_STATUS_FAILUREの場合のみ設定されます。

{
  "charge": {
    "chargeId": "trx-abc123xyz",
    "chargeStatus": "CHARGE_STATUS_FAILURE",
    "description": "Order #1234",
    "initialAmount": 10000,
    "finalAmount": 10000,
    "currency": "JPY",
    "createdAt": "2026-05-19T10:00:00Z",
    "updatedAt": "2026-05-19T10:05:00Z",
    "error": {
      "code": "ERROR_TYPE_PAYMENT_CHARGE_OVER_LIMIT",
      "message": "Payment exceeds allowed limit"
    }
  }
}

4. 返金エラー

/v1/refundからの同期レスポンス

このエンドポイントは以下を返却します:

  • リクエスト自体が不正な場合(例: charge_id欠落)、バリデーションメッセージ付きのHTTP 400。
  • ビジネスルール違反や内部エラーの場合、テキストのmessage付きのHTTP 500。ワイヤー上には安定したエラーコードはなく、message文字列のみです。よくあるメッセージ:
例: message意味
transaction does not belong to the merchantcharge_idが加盟店に存在しません
transaction is not in a cancellable state返金不可な課金(例: 既に失敗、未決済)
refund amount exceeds refundable amountリクエスト金額が、この課金で返金可能な残額を超えています
transaction has already been partially refunded; only partial refunds are allowed全額返金は不可 — 部分返金で再送信してください

注: メッセージ文言は時間とともに変更される可能性があります。人間が読むためのものであり、安定した識別子としては扱わないでください。

Webhook経由の非同期失敗

返金が同期的に受け付けられた後、決済時に失敗した場合、加盟店はEVENT_TYPE_REFUND_FAILED Webhookを受信します。refund.errorオブジェクトは常にcode: "refund_failed"を持ち、根本原因はmessageに含まれます。

例: EVENT_TYPE_REFUND_FAILED Webhookペイロード

{
  "id": "mwh-xyz789abc",
  "signature": "sha256=4f9e2d1b8c5a3e7f0d6b4a2c1e9f8d7b3a5c2e1f4d9b8a6c3e7f1d2b5a8c4e9f",
  "created_at": "2026-05-19T10:15:00Z",
  "event_type": "EVENT_TYPE_REFUND_FAILED",
  "content": {
    "transaction": {
      "id": "trx-abc123xyz",
      "customer": "cus-abc123xyz",
      "status": 1,
      "description": "Order #1234",
      "merchant_name": "Merchant Co.",
      "initial_amount": 200,
      "discount": 2,
      "final_amount": 198,
      "currency": "JPY",
      "created_at": "2026-05-19T10:00:00Z",
      "updated_at": "2026-05-19T10:15:00Z"
    },
    "refund": {
      "refund_id": "rfd-def456uvw",
      "error": {
        "code": "refund_failed",
        "message": "payment_rejected_by_bank"
      }
    }
  }
}

5. WebhookイベントタイプAnd失敗ペイロード

Webhookイベントが失敗を報告する場合、イベントボディにはcodemessage、オプションのdetails配列を持つerrorオブジェクトが含まれます。

イベントタイプ

Eventタイミング
EVENT_TYPE_CHARGE_SUCCESS決済が正常に完了
EVENT_TYPE_CHARGE_FAIL決済が失敗 — charge.errorを確認してください
EVENT_TYPE_REFUND_SUCCEEDED返金が決済された
EVENT_TYPE_REFUND_FAILED返金が失敗 — refund.errorを確認してください
EVENT_TYPE_CONTRACT_ACTIVATED顧客が決済可能になった

失敗Webhookの読み取り方

2つの失敗イベントはcontentの構造が異なります — event_typeで分岐してください。

  • EVENT_TYPE_CHARGE_FAIL — contentは単一の課金を表します。失敗関連のフィールドはcontentの直下にあります:

    • content.id — 課金ID(trx-*
    • content.customer — 顧客ID(cus-*
    • content.error.codeERROR_TYPE_*の失敗理由(Section 3参照)
    • content.error.message — 人間が読むための詳細
  • EVENT_TYPE_REFUND_FAILED — contentは元の課金と返金の2つのオブジェクトを表します:

    • content.transaction.* — 元の課金。返金失敗による影響は受けません
    • content.transaction.status — 元の課金の数値ステータス(1 = 成功)
    • content.refund.refund_id — 返金ID(rfd-*
    • content.refund.error.code — 常にrefund_failed
    • content.refund.error.message — 根本原因

注: 返金結果はcontent.refund.errorにあり、transaction側にはありません。


6. ステータスリファレンス

課金または契約のステータスを取得する際(非同期レスポンス、ポーリング、Webhookのいずれか)、statusフィールドが主要なシグナルです。errorフィールドはステータスがFAILURE(非同期の場合はFAILED)のときのみ設定されます。

ChargeStatus

GetCharge(GET /v1/charge/{charge})およびEVENT_TYPE_CHARGE_* Webhookで返却されます。errorフィールドはステータスがCHARGE_STATUS_FAILUREの場合のみ設定されます。

Status意味
CHARGE_STATUS_PENDING課金保留中(非同期処理が進行中)
CHARGE_STATUS_WAITING_EKYC処理前にeKYC確認待ち
CHARGE_STATUS_SUCCESS決済完了
CHARGE_STATUS_FAILURE処理失敗 — errorフィールドを確認してください
CHARGE_STATUS_CANCELLEDキャンセル済み(例: 当日返金)
CHARGE_STATUS_REFUNDED返金済み

例: GetChargeレスポンス(CHARGE_STATUS_SUCCESS

{
  "charge": {
    "chargeId": "trx-abc123xyz",
    "chargeStatus": "CHARGE_STATUS_SUCCESS",
    "description": "Order #1234",
    "initialAmount": 10000,
    "finalAmount": 10000,
    "currency": "JPY",
    "createdAt": "2026-05-19T10:00:00Z",
    "updatedAt": "2026-05-19T10:05:00Z"
  }
}

AsyncStatus

/v1/payments/off-session/asyncの非同期レスポンスボディで返却されます。最新ステータスを後から取得するには、返却されたcharge_idを使ってGetCharge(/v1/charge/{charge})を呼び出してください。最終結果はWebhook経由でも通知されます。

Status意味
ASYNC_STATUS_PENDINGキューイング済み、未開始
ASYNC_STATUS_RUNNING処理中
ASYNC_STATUS_SUCCEEDED正常完了
ASYNC_STATUS_FAILED_TO_START開始できなかった(バリデーション/セットアップ失敗)
ASYNC_STATUS_FAILED実行中に失敗

例: 非同期POST 200ボディ(ASYNC_STATUS_FAILED_TO_START

POST /v1/payments/off-session/asyncから返却されます。HTTP 200でstatusフィールドに失敗状態が含まれます — chargeIdも発行されるのでGetChargeでフォローアップできます。

{
  "requestId": "pwf-abc123xyz",
  "status": "ASYNC_STATUS_FAILED_TO_START",
  "chargeId": "trx-abc123xyz"
}

ContractStatus

GetContractおよびEVENT_TYPE_CONTRACT_ACTIVATED Webhookで返却されます。

Status意味
CONTRACT_STATUS_INITIAL作成済み、顧客の決済が未有効化
CONTRACT_STATUS_PENDING_CHARGE初回課金の完了待ち
CONTRACT_STATUS_WAITING_EKYCeKYC待ち
CONTRACT_STATUS_APPROVED承認済み(KYC完了または不要)
CONTRACT_STATUS_ACTIVATED課金可能
CONTRACT_STATUS_EXPIRED決済リンクが期限切れ
CONTRACT_STATUS_DEACTIVATED無効化済み
CONTRACT_STATUS_CANCELLEDキャンセル済み

例: GetContractレスポンス(CONTRACT_STATUS_EXPIRED

{
  "contract": {
    "tokenId": "con-abc123xyz",
    "status": "CONTRACT_STATUS_EXPIRED",
    "merchantName": "Merchant Co.",
    "metadata": {},
    "createdAt": "2026-05-19T10:00:00Z",
    "updatedAt": "2026-05-19T11:30:00Z"
  }
}

Customer.status

決済レスポンス(on-session / off-session)および顧客取得エンドポイントで返却されるcustomerオブジェクトに含まれます。

FieldValues
paymentPAYMENT_AUTHORIZATION_STATUS_AUTHORIZEDPAYMENT_AUTHORIZATION_STATUS_NOT_AUTHORIZED
kycKYC_STATUS_APPROVEDKYC_STATUS_NOT_SUBMITTEDKYC_STATUS_IN_REVIEWKYC_STATUS_DENIED

payment = NOT_AUTHORIZEDの顧客は、KYCが承認されていてもOff-Sessionで課金できません。

例: GetCustomerレスポンス

{
  "customer": {
    "id": "cus-abc123xyz",
    "email": "customer@example.com",
    "linkInitialized": true,
    "activated": false,
    "status": {
      "payment": "PAYMENT_AUTHORIZATION_STATUS_NOT_AUTHORIZED",
      "kyc": "KYC_STATUS_IN_REVIEW"
    }
  }
}

7. CSV一括決済

加盟店ダッシュボードでCSVバッチを処理すると、ダウンロード可能な結果CSVにはStatus列(Success / Failed / Pending)とReason列が含まれます。

Status = Pendingの行は、ダウンロード時点でまだ処理中の課金を示します。加盟店ダッシュボードはバッチの完了を最大7分間ポーリングします。バッチが7分を超える場合、ダウンロードしたCSVにpending行が含まれる可能性があります。処理が完了したらHistoryページから再ダウンロードしてください(通常2時間以内に完了します — それ以上かかる場合はJammサポートにお問い合わせください)。

Reason列は失敗行についてのみ意味を持ちます — 成功行では無視できます。

バッチレベルの拒否(アップロード時)

一部のエラーは、行が処理される前にバッチ全体を拒否します。これらは結果CSVには記録されず、アップロード時に加盟店ダッシュボードに直接表示されます。

Reasonタイミング
CSV has X rows, maximum allowed is 300バッチが1回あたり300行の上限を超過
CSV must have header and at least one data rowファイルが空、またはヘッダーのみ
CSV must have 5 or 6 columns: customer_email, customer_id, price, description, metadata, idempotency_key (idempotency_key optional)列数が不正。idempotency_key列はオプションです(5列または6列対応)
column X must be 'Y', got 'Z'ヘッダーの列名が不一致
failed to parse CSVファイルを解析できませんでした(エンコーディング・クオーティングの問題)
TOTP must be enabled for CSV payments加盟店ユーザーがTOTPを有効化していません — CSV決済には必須です
invalid TOTP code入力されたTOTPコードが検証されませんでした
TOTP challenge has expiredTOTPチャレンジが時間内に使用されませんでした
TOTP challenge is locked3回のTOTP失敗後にロックされました(15分間のロックアウト)
TOTP challenge not found / batch not found / CSV batch has expiredチャレンジまたはバッチIDが無効または期限切れ

結果CSV内の失敗行のReason値は3つのグループに分類されます。

1. バリデーション拒否

課金が試行される前に行が拒否されたケース。メッセージは問題のあるフィールドを示します。

例:

  • row has wrong number of columns, got X (expected Y)
  • customer email is required / invalid email format
  • customer_id must start with 'cus-' or be empty
  • price must be a valid integer / price must be between <min> and <max>
  • description is required / description must be <N> characters or less
  • invalid metadata format: '…' / metadata key cannot be empty / metadata key 'X' cannot contain equals signs (=) / metadata value 'X' cannot contain equals signs (=) / duplicate metadata key: 'X'. Each key can only appear once
  • idempotency_key must match <pattern> / duplicate idempotency_key in this CSV; each key must be unique within a batch
  • multiple rows in this CSV are associated with the same user account; each user can only be charged once per batch

2. 顧客解決失敗

構造的なバリデーションは通過しましたが、プレフライト時(課金が試行される前)に顧客のルックアップに失敗したケース。バリデーションサマリーに、行レベルのバリデーションエラーと一緒に返されます。

Reason原因対応
Customer ID not found指定されたcustomer_idがこの加盟店に存在しません。顧客IDを確認してください。正しい場合、顧客がまだ登録されていない可能性があります — 加盟店のオンボーディングフロー経由で登録するよう顧客に依頼してください。
No customer linked to this emailこの加盟店配下にそのメールアドレスを持つ顧客レコードがありません。CSVのメールアドレスは、顧客が最初にOn-Session決済フローで作成された際のメールアドレスと一致する必要があります。顧客レコードに紐づくメールアドレスを使用するか、代わりにcustomer_idを渡してください。顧客の登録済みメールアドレスは、加盟店ダッシュボードのList Customersページで確認できます。
Customer is not active顧客は存在しますが、有効な契約がありません — Off-Session引き落としの認可が完了していない、またはキャンセルされています。顧客に新しいOn-Session決済リンクを送付して再認可してから、リトライしてください。

3. 課金処理失敗

行がOff-Session決済フローに到達したが、処理中に問題が発生したケース。

Reason原因対応
Customer has insufficient funds課金時に顧客の銀行残高が不足していました。顧客に確認し、後日リトライをご検討ください。
Customer has not completed KYC顧客がJammアプリで本人確認(KYC)を完了していません。顧客にKYC完了を依頼し、その後リトライしてください。
Payment exceeds allowed limit金額が顧客の銀行クォータを超えています。金額を減らしてリトライするか、顧客に確認してください。
Payment gateway currently unavailableBankPayまたは顧客の銀行がメンテナンス中です。バックオフ付きでリトライしてください。
Payment gateway rejected requestBankPayが取引を拒否しました。リトライしないでください。チャージID/バッチIDを添えてJammサポートにお問い合わせください。
Invalid payment request. Review input data.決済サービス内のバリデーションエラー。最も多いケース: アップロードと処理の間に顧客が無効化された(レースウィンドウ)。加盟店ダッシュボードで顧客のステータスを確認してください。無効な場合は決済リンクを再発行してください。
Payment failed. Please contact Jamm support.内部エラー、課金未検出、キャンセル、または重複。チャージID/バッチIDを添えてJammサポートにお問い合わせください。
Failed to initiate payment. Contact Jamm support if this persists.課金を開始できませんでした。リトライしても安全です。繰り返し発生する場合はJammサポートにお問い合わせください。
Payment is still processing. Try downloading the batch again in a few minutes. Contact Jamm support if it hasn't completed after 2 hours.ダウンロード時点で課金が完了していません。数分待ってからHistoryページから再ダウンロードしてください。

不明なReasonテキストや繰り返し発生する失敗については、Jammサポートにお問い合わせください(下記「問題の報告」を参照)。


8. リトライガイダンス

分類戦略
終端 — リトライ不可ERROR_TYPE_PAYMENT_VALIDATION_FAILEDERROR_TYPE_PAYMENT_CHARGE_REJECTEDERROR_TYPE_PAYMENT_CHARGE_OVER_LIMITERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDSERROR_TYPE_PAYMENT_LINK_EXPIRED、および多くのON_SESSION_PAYMENT_ERROR_CODE_*コード(パラメータ欠落、バリデーション、顧客未検出/無効)
リトライ可能 — 指数バックオフERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLEON_SESSION_PAYMENT_ERROR_CODE_INTERNAL_ERRORASYNC_STATUS_FAILED_TO_START
条件付きERROR_TYPE_PAYMENT_CHARGE_FAILEDON_SESSION_PAYMENT_ERROR_CODE_STRATEGY_EXECUTION_FAILED — リトライ前にmessageを確認してください

自動リトライではidempotency keyを使用して二重課金を回避してください。リトライ回数の上限を設定してください。

問題の報告

ここに記載されていないエラーが発生した場合、またはmessageフィールドが不明瞭な場合は、Jammサポートにお問い合わせください。迅速なトリアージのため、以下をできる限り含めてください:

  • 影響を受けたcharge_idcustomer_id、またはバッチID
  • 失敗発生のおおよその時刻(タイムゾーン付き)
  • HTTPレスポンスボディまたはWebhookペイロードの全文
  • 送信したリクエスト(URL、メソッド、ボディ) — 顧客の機微情報は削除してください
  • 問題が再現する場合の再現手順
  • 期待した動作と実際の動作

課金失敗については、報告前に加盟店ダッシュボードのList CustomersページFor該当取引を確認することもできます — ステータスと保存されているエラー理由から結果を説明できる場合があります。

Was this page helpful?
Need help? Coming Soon
Support Center Slack community Contact us
Sign up for our developer newsletter: Coming Soon
You can unsubscribe at any time. Read our
privacy policy and terms and conditions.
jaen