導入
概要
カード登録機能では、カードの有効性を確認するために少額の与信(2円)のみを実行し、カード情報をVeriTransに登録します。
カード情報は、本機能のご利用時に指定した取引IDに紐付けられます。
また、本機能のご利用時に会員IDを指定することで、カード情報は指定した会員IDに紐付けられます。
取引IDや会員IDに紐づけられたカード情報は、MDKやMAP(Merchant Administration Portal)を使用することで、決済等に利用することが可能です。
- 消費者様はカード登録操作を実施します。
- ECサイトはPOPのAPIにリクエストを送信し
payment_key
を取得します。- POPはレスポンスで
payment_key
を返戻します。- ECサイトはhtmlページを作成し、消費者様のブラウザへ返戻します。
- ECサイトが作成したJavaScriptで
pop.pay(payment_key, options)
を呼び出します。消費者様はカード情報を入力し、登録ボタンをクリックします。POP JSはカード情報をPOPに送信します。- POPはリクエストを処理し、結果を返戻します。このとき、POP JSは、ECサイトが作成したJavaScriptコールバックまたはリクエストパラメータで指定されたURLを呼び出します。
- POPはカード登録結果をECサイトに通知します。
バックエンド
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リクエストに設定します。
Content-Type: application/json; charset=utf-8
Authorization: Basic AUTH_STRING
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)からもご利用いただけます。
エンドポイント
Registration Link
https://pay3.veritrans.co.jp/pop/v1/account-registration-link
リクエスト
HTTPメソッド
POST
リクエストヘッダ
リクエストに設定するヘッダの詳細はリクエストヘッダを参照してください。
リクエストパラメータ
以下のパラメータを除いて、バックエンドのリクエストパラメータのすべてのパラメータを設定できます。
success_url
failure_url
incomplete_url
レスポンス
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。 エラー発生時は返戻されません。 |
HTTPステータスコード
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セキュア(本人認証)に関する記載を追加しました。
mpi
パラメータの説明に注意文を追加。cardholderEmail
、cardholderHomePhoneNumber
、cardholderHomePhoneNumberCountry
、cardholderMobilePhoneNumber
、cardholderMobilePhoneNumberCountry
、cardholderWorkPhoneNumber
、cardholderWorkPhoneNumberCountry
のパラメータを追加。- 3Dセキュア(本人認証)有効時に、
paynow_account_id
を指定できるように変更。
結果コードを更新しました。
RC5M
、RC5N
、RC5O
、RC5P
、RC5Q
、RC5R
、RC5S
を追加。RC2O
を削除。
v1.3
2024/3/13
接続先ドメインをpay3.veritrans.co.jp
に変更しました。
- 「バックエンド」の「エンドポイント」の「Payment Key」。
- 「リンク生成機能」の「エンドポイント」の「Registration Link」。
- 「リンク生成機能」の「レスポンス」サンプルコードの「pay_link_url」。
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
新規作成。