NAV
←
POP Card Registration API(v1.4)

導入

概要

カード登録機能では、カードの有効性を確認するために少額の与信（2円）のみを実行し、カード情報をVeriTransに登録します。
カード情報は、本機能のご利用時に指定した取引IDに紐付けられます。
また、本機能のご利用時に会員IDを指定することで、カード情報は指定した会員IDに紐付けられます。
取引IDや会員IDに紐づけられたカード情報は、MDKやMAP(Merchant Administration Portal)を使用することで、決済等に利用することが可能です。

  1. 消費者様はカード登録操作を実施します。
  2. ECサイトはPOPのAPIにリクエストを送信しpayment_keyを取得します。
  3. POPはレスポンスでpayment_keyを返戻します。
  4. ECサイトはhtmlページを作成し、消費者様のブラウザへ返戻します。
  5. ECサイトが作成したJavaScriptでpop.pay(payment_key, options)を呼び出します。消費者様はカード情報を入力し、登録ボタンをクリックします。POP JSはカード情報をPOPに送信します。
  6. POPはリクエストを処理し、結果を返戻します。このとき、POP JSは、ECサイトが作成したJavaScriptコールバックまたはリクエストパラメータで指定されたURLを呼び出します。
  7. POPはカード登録結果をECサイトに通知します。

registration flow

バックエンド

ECサイトではPOPからpayment_keyを取得してください。 payment_keyを取得後、フロントエンドに進むことができます。

エンドポイント

Payment Key

https://pay3.veritrans.co.jp/pop/v1/register-card

リクエスト

ECサイトがPOPからpayment_keyを取得するためのリクエストパラメータについて説明します。

HTTPメソッド

POST

リクエストヘッダ

POP_SERVER_KEY = "Test-POP-Server-Key";

AUTH_STRING = Base64("Test-POP-Server-Key:");

AUTH_STRING = "VGVzdC1QT1AtU2VydmVyLUtleTo=";

次の2つのヘッダをHTTPリクエストに設定します。

POPはBASIC認証によりHTTPリクエストの検証を行います。ユーザ名にPOP_SERVER_KEYを、パスワードに空文字を設定してください。 POP_SERVER_KEYはMAPのAPI設定から取得可能です。

Authorization ヘッダの値はAUTH_STRINGで記載しております。 AUTH_STRINGはユーザ名とパスワードをbase64でエンコードした文字列です。

AUTH_STRING = Base64(POP_SERVER_KEY + :)

リクエストパラメータ

必要最小限のパラメータを指定した場合は以下の通りです。

{
    "order_id": "ORDER-0001"
}

指定可能なパラメータを全て指定した場合は以下の通りです。

{
    "order_id": "ORDER-0001",
    "dummy": true,
    "payment_key_expiry_duration": 1440,
    "success_url": "https://example.com/success",
    "failure_url": "https://example.com/failure",
    "incomplete_url": "https://example.com/incomplete",
    "push_url": "https://example.com/push",
    "card": {
        "mpi": false,
        "paynow_account_id": "TEST-ACCOUNT-101"
    },
    "email": {
        "customer_name": "スミス ジョン",
        "customer_email_address": "smith.john@example.com"
    }
}

リクエストには、以下のパラメータが指定可能です。

パラメータ 説明
order_id
string(100) (required)		 取引ID。取引毎に一意になるように指定してください。半角英数字と ‘-'（ハイフン）と ’_‘（アンダースコア）のみ指定可能です。他の文字は使用できません。
dummy
boolean (optional)		 ダミー取引を実施するために設定します。ダミーリクエストでは実際の与信処理は発生いたしません。VeriTransとの結合テスト用にご利用ください。
Values: true or false (Default: false)
success_url
string(256) (optional)		 カード登録成功時のリダイレクトURL。指定されていない場合、POP設定の「システム設定」タブにある「決済成功時URL」に設定の値を使用します。
failure_url
string(256) (optional)		 カード登録失敗時のリダイレクトURL。指定されていない場合、POP設定の「システム設定」タブにある「決済失敗時URL」に設定の値を使用します。
incomplete_url
string(256) (optional)		 カード登録未完了時のリダイレクトURL。指定されていない場合、POP設定の「システム設定」タブにある「決済未完了時URL」に設定の値を使用します。
push_url
string(256) (optional)		 PUSH通知送信用URL。指定されていない場合、POP設定の「システム設定」タブにある「PUSH通知送信先URL」に設定の値を使用します。
payment_key_expiry_duration
number(6) (optional)		 payment_keyが生成されてから利用不可となるまでの有効期間を「分」で指定します。
Maximum value: 129600 (90日)
Default: 1440(1日)
card
object (optional) カード登録用パラメータ		 カード登録用のパラメータです。
email
object (optional) 消費者様へのメール通知用パラメータ		 消費者様の名前とメールアドレスを指定するためのパラメータです。

カード登録用パラメータ

{
    "card": {
        "mpi": false,
        "paynow_account_id": "TEST-ACCOUNT-101"
    }
}

{
    "card" : {
        "mpi" : true,
        "3ds_version" : "2",
        "paynow_account_id" : "TEST-ACCOUNT-101",
        "cardholderEmail" : "smith.john@example.com",
        "cardholderHomePhoneNumber" : "0312345678",
        "cardholderHomePhoneNumberCountry" : "81",
        "cardholderMobilePhoneNumber" : "08012345678",
        "cardholderMobilePhoneNumberCountry" : "81",
        "cardholderWorkPhoneNumber" : "08012345678",
        "cardholderWorkPhoneNumberCountry" : "81"
    }
}
パラメータ 説明
mpi
boolean (optional)		 3Dセキュア（本人認証）有効フラグ。設定されていない場合、POP設定の「システム設定」タブにある"本人認証"に設定の値を使用します。
Values: true or false
paynow_account_id
string(100) (optional)		 消費者様毎に一意の会員ID。 与信の取得に成功した場合、会員が新規作成され、入力したカード情報と紐付けられます。
既に会員が存在する場合、入力したカード情報は追加で会員に紐付けられます。
どちらの場合も、新しく紐付けられたカードが初期選択カードとなります。
※別途ワンクリック継続課金の契約が必要です。
3ds_version
string(1) (optional)		 mpiがtrueに指定されている場合、本人認証バージョンを設定することが可能です。
このパラメータが指定されていない場合、MAPのPOP設定の「システム設定」タブにある「本人認証バージョン」に設定の値を使用します。
Values: 1 or 2
cardholderEmail
string(254) (optional)		 カード保有者メールアドレス。3Dセキュア（本人認証）の処理で使用されます。
3Dセキュア（本人認証）が有効の場合、指定が必要になります。mpiパラメータの説明もあわせてご確認ください。
cardholderHomePhoneNumber
string(15) (optional)		 カード保有者自宅電話番号。本人認証の処理で使用されます。
このパラメータには半角数字のみ使用可能です。(ハイフン使用不可)
3Dセキュア（本人認証）が有効の場合、指定が必要になります。mpiパラメータの説明もあわせてご確認ください。
cardholderHomePhoneNumberCountry
string(3) (optional)		 カード保有者自宅電話番号の国コード。本人認証の処理で使用されます。
このパラメータには半角数字のみ使用可能です。（ITU-T E.164 で規定された地域別国コードを指定）
Default:81（※日本の国コード）

電話番号を設定した場合は、必ず国コードが必要になります。
日本の番号はデフォルト値がセットされますので設定不要ですが、海外の番号をセットした場合は必ず正しい国コードを設定してください。
cardholderMobilePhoneNumber
string(15) (optional)		 カード保有者携帯電話番号。本人認証の処理で使用されます。
このパラメータには半角数字のみ使用可能です。(ハイフン使用不可)
3Dセキュア（本人認証）が有効の場合、指定が必要になります。mpiパラメータの説明もあわせてご確認ください。
cardholderMobilePhoneNumberCountry
string(3) (optional)		 カード保有者携帯電話番号の国コード。本人認証の処理で使用されます。
このパラメータには半角数字のみ使用可能です。（ITU-T E.164 で規定された地域別国コードを指定）
Default:81（※日本の国コード）

電話番号を設定した場合は、必ず国コードが必要になります。
日本の番号はデフォルト値がセットされますので設定不要ですが、海外の番号をセットした場合は必ず正しい国コードを設定してください。
cardholderWorkPhoneNumber
string(15) (optional)		 カード保有者勤務先電話番号。本人認証の処理で使用されます。
このパラメータには半角数字のみ使用可能です。(ハイフン使用不可)
3Dセキュア（本人認証）が有効の場合、指定が必要になります。mpiパラメータの説明もあわせてご確認ください。
cardholderWorkPhoneNumberCountry
string(3) (optional)		 カード保有者勤務先電話番号の国コード。本人認証の処理で使用されます。
このパラメータには半角数字のみ使用可能です。（ITU-T E.164 で規定された地域別国コードを指定）
Default:81（※日本の国コード）

電話番号を設定した場合は、必ず国コードが必要になります。
日本の番号はデフォルト値がセットされますので設定不要ですが、海外の番号をセットした場合は必ず正しい国コードを設定してください。

消費者様へのメール通知用パラメータ

{
    "email": {
        "customer_name": "スミス ジョン",
        "customer_email_address": "smith.john@example.com"
    }
}

以下は消費者様へのメール通知専用のパラメータです。

パラメータ 説明
customer_name
string(256) (optional)		 メール通知の際に表示される消費者様の名前を設定します。このパラメータには全角/半角文字が使用可能です。
customer_email_address
string(256) (optional)		 消費者様へのメール通知を送信する宛先のメールアドレスを設定します。

レスポンス

レスポンスパラメータ

成功時のレスポンス

{
    "payment_key": "28GTzdVOZNeImaHMDeQF1319",
    "result_code": "R000",
    "status": "success",
    "message": "\"Payment Key\" has been generated successfully",
    "payment_key_expiry_time": "20200401000000"
}

失敗時のレスポンス

{
    "result_code":"RC01",
    "status":"failure",
    "message":"Invalid \"Order ID\""
}

POPは、ECサイトからリクエストを受信した場合、以下のパラメータをレスポンスとして返戻します。

パラメータ 説明
payment_key
string(24) (optional)		 カード登録リクエストに対してPOPが生成した一意のpayment_key。
エラー発生時は返戻されません。
result_code
string(4) (required)		 成功または失敗の具体的な理由を示す4文字の結果コード
status
string(7) (required)		 処理のステータス
Values: success or failure
message
string(256) (required)		 処理結果の詳細を表すメッセージ
payment_key_expiry_time
string(14) (optional)		 payment_keyの有効期限。(YYYYMMDDhhmmss 形式)
エラー発生時は返戻されません。

HTTPステータスコード

POPはレスポンスで以下のHTTPステータスコードを返戻します。

ステータスコード 説明
201 Created リクエストは成功しました。
400 Bad Request リクエストパラメータのバリデーションに失敗しました。詳細についてはレスポンスパラメータのresult_codeとmessageを参照してください。
401 Unauthorized マーチャント認証に失敗しました。
500 Internal Server Error POPで原因不明のエラーが発生しました。

フロントエンド

通常の決済フローと同様に、バックエンドで取得したpayment_keyを引数にしてpop.pay関数を実行することで、ブラウザ上にカード登録機能専用の画面が表示されます。

登録結果

登録結果は通常のカード決済と同様の機能にて連携します。メール通知に関しては、カード登録専用の文面となります。 詳細につきましては、こちらから「VeriTrans4G POP 開発ガイド」に記載の「決済結果」と「通知」を参照してください。

リンク生成機能

POPは通常のPOPクライアントに加え、カード登録画面のリンクURL生成機能も提供しています。 ECサイトは取得したURLを電子メールやSMSのメッセージ機能等を使って消費者様に送信し、POPが生成したカード登録画面に誘導することが可能です。そのカード登録画面からPOPクライアントが表示されます。リダイレクト機能やPOP JSのオプションは使用できません。本機能はMAP(Merchant Administration Portal)からもご利用いただけます。

https://pay3.veritrans.co.jp/pop/v1/account-registration-link

HTTPメソッド

POST

リクエストヘッダ

リクエストに設定するヘッダの詳細はリクエストヘッダを参照してください。

以下のパラメータを除いて、バックエンドのリクエストパラメータのすべてのパラメータを設定できます。

POPは有効なリクエストに対して、バックエンドのレスポンスパラメータに加えて、以下の表のパラメータをレスポンスとして返戻します。 リクエストに失敗した際にPOPから返戻される結果コードについては、結果コードを参照してください。

成功時のレスポンス

{
    "payment_key": "28GTzdVOZNeImaHMDeQF1319",
    "result_code": "R000",
    "status": "success",
    "message": "\"Payment Key\" has been generated successfully",
    "payment_key_expiry_time": "20200401000000",
    "pay_link_url": "https://pay3.veritrans.co.jp/pop/v1/account-registration-link-pay?payment_key=28GTzdVOZNeImaHMDeQF1319&client_key=client101"
}

失敗時のレスポンス

{
    "result_code":"RC01",
    "status":"failure",
    "message":"Invalid \"Order ID\""
}

レスポンスパラメータ

パラメータ 説明
pay_link_url
string(256) (optional)		 POPが生成したカード登録画面のリンクURL。
エラー発生時は返戻されません。

POPから返戻されるHTTPステータスコードについては、HTTPステータスコードを参照してください。

結果コード

バックエンド

バックエンドのレスポンスで返戻される結果コードです。

結果コード 説明
R000 Successful transaction
RA01 Application Error - VeriTransで原因不明のエラーが発生した場合
RD01 Database Error - VeriTransのデータベース処理でエラーが発生した場合
RC01 “Order ID"が無効です
RC07 "Success URL"が無効です
RC08 "Failure URL"が無効です
RC09 "Incomplete URL"が無効です
RC10 "Push URL"が無効です
RC17 マーチャント認証に失敗しました。POP_SERVER_KEYをご確認ください
RC20 取引がすでに存在しています
RC21 利用できない決済方法です
RC22 3Dセキュア（本人認証）は契約が無いため、ご利用いただけません
RC26 "Dummy"が無効です
RC28 "Card - MPI"が無効です
RC30 サポートしていない"Media Type"です
RC31 必須パラメータが不足しています
RC32 GETメソッドは対応していません
RC43 JSON文字列が無効です
RC44 テストアカウントでは、"Dummy"に"true"を設定してください
RC2A "PayNow Account ID"が無効です
RC2P ワンクリック継続課金の契約がございません
RC2Q 会員情報の検証に失敗しました。エラーの詳細は、VeriTransまでお問い合わせください
RC2R ダミー取引で作成した会員は本番取引ではご利用いだたけません。また、本番取引で作成した会員はダミー取引ではご利用いただけません
RC5A "Customer Email Address"が無効です
RC5B "Customer Name"が無効です
RC5J "Card - 3D Secure Version"が無効です
RC5M "Cardholder Email Address"が無効です
RC5N "Cardholder Home Phone Number"が無効です
RC5O "Cardholder Mobile Phone Number"が無効です
RC5P "Cardholder Work Phone Number"が無効です
RC5Q "Cardholder Home Phone Number Country Code"が無効です
RC5R "Cardholder Mobile Phone Number Country Code"が無効です
RC5S "Cardholder Work Phone Number Country Code"が無効です

改訂履歴

v1.4

2024/5/29

「バックエンド」の「リクエスト」の「カード登録用パラメータ」に3Dセキュア（本人認証）に関する記載を追加しました。

結果コードを更新しました。

v1.3

2024/3/13

接続先ドメインをpay3.veritrans.co.jpに変更しました。

MAP(Merchant Administration Portal)のリンクの接続先ドメインをadmin3.veritrans.co.jpに変更しました。

v1.2

2021/10/25

「バックエンド」の「リクエスト」の「カード登録用パラメータ」に3ds_versionの記載を追加しました。

3ds_versionに関する結果コードを追加しました。

v1.1

2020/1/20

リンク生成機能と登録結果の記載を追加しました。

TLSのサポート対象を変更しました。

v1.0

2018/08/22

新規作成。

Copyright © 2024 DG Financial Technology, Inc., a Digital Garage company. All rights reserved.
Digital Garage Group