支払い作成時の 3Dセキュア

3Dセキュアの概要については、下記ドキュメントをご覧ください。

• 3Dセキュア認証
• PAY.JPにおける3Dセキュア

3Dセキュアを開始する

通常の支払い作成と同様のパラメーターで支払いを作成します。その際、追加のパラメーター three_d_secure=true を指定することで、3Dセキュア処理待ち状態の支払いが作成されます。

3Dセキュア処理待ち状態の支払いを作成

curl -X POST https://api.pay.jp/v1/charges \
-u sk_test_c62fade9d045b54cd76d7036: \
-d "amount=500" \
-d "currency=jpy" \
-d "card=tok_xxx" \
-d "three_d_secure=true"

作成された支払いは決済の成否を表す paid 属性が false になっており、決済処理はまだ行われていない状態になっています。 また、3Dセキュアの認証状態を表す three_d_secure_status 属性が unverified になっており、これによって 3Dセキュア処理待ちであることが示されています。

注意：3Dセキュア開始から一定時間以内に支払い完了まで到達しない場合、その支払いの 3Dセキュアを進めることができなくなります。

購入者を3Dセキュアに誘導する

3Dセキュア認証を進めるために、購入者をカード会社が提供する 3Dセキュア認証画面に誘導します。 誘導の方法はリダイレクト型とサブウィンドウ型の2種類があります。

サブウィンドウ型

3D セキュア認証画面を表示するサブウィンドウを表示し、購入者はその内部に表示されるカード発行会社の画面上でパスワード入力等を行います。
誘導には、payjp.js v2 が提供する openThreeDSecureDialog 関数を利用します。
一部環境（モバイルにおけるアプリ内ブラウザなど）ではポップアップに対して警告やブロックが働くため、利用者によっては認証画面に辿りつけないこともございます。
利用状況に応じてリダイレクト型もご検討ください。

const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')

payjp.openThreeDSecureDialog(
  'サーバーサイドから渡された支払いID'
).then(() => {
  // 3Dセキュア処理が終了したことをサーバーサイドに通知する
})

openThreeDSecureDialog を呼び出すと、3D セキュア認証画面がサブウィンドウで開かれます。
購入者が 3D セキュア認証を終了させることでサブウィンドウは自動的に閉じられ、Promise が解決されます。
Promise が解決されたことが確認できたら、再度サーバー側に処理を移し、次項の支払い完了処理を行います。

リダイレクト型

サービスから PAY.JP が提供する 3D セキュア開始エンドポイントにリダイレクトさせ、認証完了後にサービスが指定するエンドポイントにリダイレクトで戻す方式です。 支払いを作成し 3D セキュアを実施するタイミングで、利用者を下記のエンドポイントにリダイレクトさせます。

https://api.pay.jp/v1/tds/支払いID/start?publickey=....&back=...

リダイレクト時のパラメーターとして、完了後の戻り先となる URL を指定します。以下の 2 通りの指定ができます。

• back
  • PAY.JP の管理画面で事前に登録した戻り先 URL を使用する場合に指定します。登録時に設定した識別子を指定してください。
• back_url
  • 動的に戻り先 URL を指定する場合に使用します。JWS（JSON Web Signatures）形式のデータで、戻り先 URL を含めて指定します。 back_url を使用した実装はコードサンプルを参考にご実装ください。

エンドポイントとパラメーターの詳細はAPIリファレンス - 3Dセキュア開始をご覧ください。

処理完了、あるいはエラーとなったタイミングで、利用者は指定した戻り先 URL にリダイレクトされます。戻り先 URL では次項の支払い完了処理を行います。

※ 戻り先 URL にリダイレクトされる時に、PAY.JPから特別なパラメーターが付与されたりすることはありません。
開始エンドポイントへの誘導前にあらかじめリソースのIDをセッションなどに保持しておいてください。

サブウィンドウ型に比べると少し実装は煩雑になりますが、一部モバイル環境ではサブウィンドウ型が適切に動作しない可能性があるため、より広い環境で動作させたい場合や、サブウィンドウのユーザー体験が望ましくない場合にはリダイレクト型をご利用ください。

支払いの3Dセキュアを完了させる

カード発行会社における認証の終了を検知したら、サーバーから 3Dセキュア完了エンドポイントにリクエストします。

curl -X POST https://api.pay.jp/v1/charges/支払いID/tds_finish \
-u sk_test_c62fade9d045b54cd76d7036:

3Dセキュア認証が正しく行われていれば、決済処理が行われ、通常の支払い作成と同様のレスポンスが返却されます。
注意：3Dセキュアが成功だったとしても、通常の支払い作成同様、与信不足やカードの一時的な停止などにより決済が失敗し、失敗レスポンスが返却される可能性もあります。

より細やかな制御をする場合は、3Dセキュア完了エンドポイントにリクエストする前に支払いオブジェクトを取得し直し、下記の項目のような実装をご検討ください。

完全認証を行いたい場合

取得されたオブジェクトの three_d_secure_status が attempted の場合に購入手続きを中断することで、完全認証となります。それ以外にも、商品や金額等をふまえて加盟店独自の基準で制御することも可能です。

three_d_secure_status が失敗状態のとき

unverified のままであったり、error であったりする場合は、3D セキュアの手順中に離脱した、パラメーターに異常があった等の問題が考えられます。この状態では 3D セキュア完了エンドポイントへのリクエストもエラーとなるため、支払いの作成から 3D セキュアフローをやり直す必要があります。
attempted または verified の場合は 3Dセキュア完了が可能です。

• APIリファレンス - Charge(支払い)

3Dセキュア認証の追加項目に対応する

概要についてはPAY.JPにおける3Dセキュア - 3Dセキュア認証における追加項目をご覧ください。
追加項目に対応するには、下記のどちらかのタイミングで必要な情報をカードにセットする必要があります。

トークン作成時にカード情報と共に入力させる

トークン作成時の3Dセキュア - 3Dセキュア認証の追加項目に対応するを参考に、各ライブラリで情報をセットしてください。

トークン作成時以外で入力させる

任意のタイミングで、有効なカード名義、および電話番号またはメールアドレスをエンドユーザーに入力してもらってください。

収集した追加項目は顧客カード更新のAPIにてセットできます。

curl https://api.pay.jp/v1/customers/cus_xxxxxx/cards/car_xxxxxxxxx \
-u sk_test_c62fade9d045b54cd76d7036: \
-d name="PAY TARO" \
--data-urlencode "email=pay@example.local" \
--data-urlencode "phone=+0819001234567" \

※顧客に登録したカードのみ追加項目の更新が可能です。

追加項目について

連携していただくメールアドレスおよび電話番号等の情報は、カード発行会社に登録されているデータと完全に一致している必要はありません。
カード会社の登録情報との一致を目指すものではなく、リスク判定のための情報の1つとして利用されます。
そのため、加盟店様に登録されている顧客情報や購入時の情報など、購入者自身が入力したものをご連携いただければ問題ありません。

これらのことから、追加項目の更新は顧客に登録したカードに対してのみ可能となっています。

作成したトークンを顧客に登録せずに支払いに使う場合、追加項目の更新はできませんのであらかじめご了承ください。
このようなケースは都度購入などで想定されますが、トークン作成から支払い確定までにメールアドレスや電話番号の変更があったとしても、トークン作成時に入力された値をそのままセットしていただいて問題ございません。