3D Secure 2.0とは、クレジットカード決済の詐欺利用を防止するための本人認証プロトコルです。詳しくはこちらをご覧ください。

2018年6月1日に施行された「改正割賦販売法」において義務付けられている不正使用対策の要件を満たすものですので、APIによる決済を導入の方は、ぜひSecure Token APIへの対応をお願いいたします。

（API以外による導入の場合、自動的にKOMOJU上で処理するので対応の必要はありません。）

ホストページ、ホストフィールドをご利用の方、3D Secure 2.0は既にサポートされています。本ドキュメントはダイレクトにペイメントAPIを使用するマーチャント対象です。

Secure Token APIの流れ

Secure Token APIの基本的な流れは、既存の[Tokens API](/docs/tokens<!-- TODO: update link -->)と似ています。Secure Token APIでは、authentication_urlに記載されたURLへアクセスして認証を行い、生成されたSecure Tokenを有効化する必要があります。

1. Secure Tokenの作成

まずはじめに、POST /api/v1/secure_tokensにクレジットカード決済の情報をリクエストします。リクエストに成功すると、KOMOJUはSecure Tokenを作成し、その情報をレスポンスとして返します。

curl -X POST https://komoju.com/api/v1/secure_tokens \
    -u sk_12345: \
    -d "amount=1000" \
    -d "currency=JPY" \
    -d "return_url=https://example.com/complete" \
    -d "payment_details[type]=credit_card" \
    -d "payment_details[email]=test@example.com" \
    -d "payment_details[number]=4100000000000100" \
    -d "payment_details[month]=08" \
    -d "payment_details[year]=2025" \
    -d "payment_details[verification_value]=123" \
    -d "payment_details[name]=Test Card"

{
  "secure_token": "tok_1234567890abcdefghijklmnop",
  "verification_status": "NEEDS_VERIFY",
  "authentication_url": "https://komoju.com/three_d_secure_service/offsite?token=tok_1234567890abcdefghijklmnop"
}

verification_status の値が OK あるいは SKIPPED の場合、手順2および手順3はスキップできます。

なお、 verification_status が ERRORED の場合、Secure Tokenの生成が失敗しています。リクエスト内容を確認いただくか、再度、Secure Token の生成からやりなおしてください。

2. 認証画面へリダイレクトする

レスポンスに含まれる verification_status の値が NEEDS_VERIFY の場合、お客様をauthentication_url へリダイレクトしてください。そこでお客様の3D Secure 2.0の認証が行われます。

3. 認証終了後、認証結果をリクエストする

客様の3D Secure 2.0の認証が終了しますと、お客様はSecure Token作成時にリクエストした return_url へリダイレクトされます。この際、HTTPパラメータにsecure_token_id=[secure token id]が付与されております。

return_url へのリダイレクトが確認できましたら、GET api/v1/secure_tokens/:id にリクエストを送信して、認証結果を確認してください。

もしレスポンスに含まれる verification_status が ERRORED だった場合、お客様は3D Secure 2.0の認証が失敗したこととなり、決済へ進むことはできません。再度、Secure Tokenの作成からやり直していただくか、別のカードを使う等をお客様にお知らせしてください。

curl -X GET https://komoju.com/api/v1/secure_tokens/tok_1234567890abcdefghijklmnop \
    -u sk_12345:

{
  "secure_token": "tok_1234567890abcdefghijklmnop",
  "verification_status": "OK",
}

4. Secure Tokenを用いて決済APIをリクエストする

verification_status が OK もしくは SKIPPED となっていれば、そのSecure Tokenは決済APIで利用することができます。

SKIPPED は、3D Secure 2.0認証サーバとの通信障害など、なんらかの理由で認証が実行できない時に返ってきます。SKIPPED の状態では3D Secure 2.0 認証は行われていないことを意味するため、必要に応じて再試行するか決済を続けるかお選びください。

決済APIで指定する amount および tax の合計値は、Secure Token APIで指定した amount の値と同じである必要があります。tax を未指定にすると auto として扱われて自動で計上されるため、 tax=0 を指定することを推奨します。

curl -X POST https://komoju.com/api/v1/payments \
  -u sk_12345: \
  -d "amount=1000" \
  -d "tax=0" \
  -d "currency=JPY" \
  -d "payment_details=tok_1234567890abcdefghijklmnop"

テストカード

Testモードで挙動を確認したい場合、下記のテスト用カード番号およびテスト用顧客情報を利用してください。名義およびCVVは任意の値を、有効期限は将来の日付を指定してください。

3DS環境の信頼性とパフォーマンス向上のため、KOMOJUでは基礎となる3Dセキュア（3DS）インフラストラクチャベンダーのアップグレードを実施しています。2026年9月1日以降は、新しいテストカードをご使用ください。

認証成功 (3DS フリクションレス)

認証チャレンジなしで取引を完了できます。

2026年9月1日以降は以下のカードをご使用ください

認証成功（追加認証あり / 3DS フリクション）

パスワードチャレンジを伴う取引をテストできます。チャレンジを通過するには 123456 を入力してください。

2026年9月1日以降は以下のカードをご使用ください

チャレンジを通過するには 1234 を、チャレンジを失敗させるには 1111 を入力してください。

認証失敗 (3DS フリクションレス失敗)

チャレンジなしで拒否される認証をテストできます。

2026年9月1日以降は以下のカードをご使用ください

認証失敗（チャレンジでの失敗）

失敗するチャレンジパスワードをテストできます。失敗をシミュレートするには任意の数値を入力してください。

2026年9月1日以降は、「認証成功（追加認証あり）」セクションのテストカードを使用し、1111 を入力して失敗をテストしてください。