Secure Token API

Secure Token APIは、KOMOJU上のクレジット決済において、3D Secure 2.0をサポートするためのAPIです。

3D Secure 2.0とは

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

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

KOMOJUでは、全クレジットカード決済への3-D Secure 2.0の設定を順次進めております。お使いのマーチャントによっては Secure Token API がご利用できない可能性があるので、ご了承ください。

Secure Token APIの流れ

Secure Token APIの基本的な流れは、既存のTokens APIと似ています。Secure Token APIでは、authentication_url に記載されたURLへアクセスして認証を行い、生成されたSecure Tokenを有効化する必要があります。

ショップショップKOMOJUKOMOJU顧客顧客POST /api/v1/secure_tokens/`verification_status=NEEDS_VERIFY`の確認`authentication_url`へリダイレクト3D Secure 2.0の認証`return_url`へリダイレクトGET /api/v1/secure_tokens/{id}`verification_status=OK`の確認POST /api/v1/payments`payment.status=captured`の確認Webhook `payment.captured`商品の発送またはサービスの提供

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"
}
リクエストパラメータ タイプ 詳細
amount 数値 金額
currency 文字列 アルファベット3文字の通貨コード
return_url 文字列 ユーザーが認証を完了した後にリダイレクトされるURL
payment_details[type] 文字列 credit_card の値
payment_details[email] 文字列 ペイメント受領時に送信するメールアドレス。
payment_details[number] 数値 クレジットカード番号
payment_details[month] 数値 有効期限月
payment_details[year] 数値 有効期限年
payment_details[verification_value] 数値 CCV セキュリティ番号
payment_details[name] 文字列 クレジットカードの所有者名(アルファベット)
レスポンスパラメータ タイプ 詳細
secure_token 文字列 生成されたSecure TokenのID
verification_status 文字列 OKNEEDS_VERIFYSKIPPEDERRORED のいずれかの値
authentication_url 文字列 3D Secure 2.0の認証を行うURL

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

なお、 verification_statusERRORED の場合、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_statusERRORED だった場合、お客様は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_statusOK もしくは 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 モードで挙動を確認したい場合、下記のテスト用カード番号およびテスト用顧客情報を利用してください。

注: これらのカードは Test モードでのみ利用可能です。Live モードでは利用できません。Live モードで購入の動作確認を行いたい場合は、お持ちの本物のクレジットカードをお使いください。

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

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

認証成功

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

カード番号 タイプ
4100000000000100 Visa
5100000000000107 Mastercard
3528000000000106 JCB

認証成功(追加認証あり)

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

カード番号 タイプ
4100000000005000 Visa
5100000000005007 Mastercard
3528000000005006 JCB

認証失敗

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

カード番号 タイプ
4100000000500000 Visa
5100000000500007 Mastercard
3528000000500006 JCB

認証失敗(追加認証あり)

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

カード番号 タイプ
4100000000300005 Visa
5100000000300002 Mastercard
3528000000300001 JCB