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

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

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

Secure Token APIの流れ

Secure Token APIの基本的な流れは、既存のTokens APIと似ています。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][email protected]" \
    -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 モードで挙動を確認したい場合、下記のテスト用カード番号およびテスト用顧客情報を利用してください。

テスト用カードで推奨されるテスト用顧客情報は下記の通りです。

• payment_details[name] : Test Card
• payment_details[month] : 08
• payment_details[year] : 2025

認証成功

3D Secure 2.0の成功フローをテストできます。

認証成功（追加認証あり）

3D Secure 2.0認証における、追加認証（チャレンジ）フローをテストできます。パスワード入力画面では 123456 と入力することで、認証成功となります。

認証失敗

3D Secure 2.0認証の失敗フローをテストできます。authentication_url にアクセス後、追加認証なしで認証失敗となります。

認証失敗（追加認証あり）

3D Secure 2.0認証の追加認証フローにおける、追加認証の失敗をテストできます。パスワード入力画面で 111111 と入力することで、認証失敗となります。