BankPay
本ガイドの内容
本ガイドの内容
本ガイドは、株式会社DGフィナンシャルテクノロジーが提供するVeriTrans4GのBankPayサービス(※1)をインターネット店舗等に導入するための、開発者向けのガイドです。
※1） Pay-easy（ペイジー）とは別の決済サービスとなりますので、間違えのないようご注意ください。
BankPayサービス概要
BankPayサービスの概要
BankPayサービスは、事前に銀行の口座情報を登録し、登録した口座情報を用いて決済を行うサービスです。
- 口座情報の登録は、銀行毎のページにリダイレクトして実施します。
- 口座情報を登録することで、決済の度に口座情報を入力する必要がなくなります。
- 口座登録なしで決済のみの実施はできません。
課金種別（都度決済、随時決済、チャージ）
BankPayサービスにおいて、課金種別は「都度決済」・「随時決済」・「チャージ」で区別されます。
【共通】
-
事前に会員登録, 口座登録を実施しておき、決済は加盟店からリクエストする必要があります
※随時決済の場合でも自動で決済は行われず、加盟店からリクエストする必要があります。
- 登録した会員・口座情報はすべての課金種別で利用可能です。
- 一度登録した会員・口座情報は、基本的に削除するまでは繰り返し決済にご利用いただけます。
【都度決済機能】
加盟店が提供する商品もしくはサービスを購入する毎に、口座引落を行う決済が該当します。
【随時決済機能】
加盟店と消費者が事前に取り決めた条件(金額や日時等)にのっとり、利用者による購入手続きなく口座引き落としを行う決済が該当します。
【チャージ】
BankPayでは、チャージの類型を前払式支払手段（ハウス）／前払式支払手段（オープン）／資金移動の３つとし、定義は以下の通りとなっています。
（前払式支払手段と資金移動の区分は資金決済に関する法律の例によります）
-
チャージ(ハウス)：
- バリュー提供者自身またはバリュー提供者自身と資本関係のあるグループ会社のサービス対価としてのみ利用可能なバリューチャージ
- バリュー提供者と提携する特定一社または当該特定一社と資本関係のあるグループ会社のサービス対価としてのみ利用可能なバリューチャージ
（例：電子マネーの発行者＝バリュー提供者）
-
チャージ(オープン)：
チャージ（ハウス）に該当しない前払式支払手段の取引
（例：バリュー提供者と提携する複数の提携先のサービス対価として利用可能なバリューへのチャージ取引） -
チャージ(資金移動)：
資金移動者へのチャージであり、チャージしたバリューは提携先のすべての加盟店で利用可能かつ現金として引き出したり、別のサービスの会員に送金することが可能。
MDKの処理概要
機能一覧（決済要求コマンド）
使用可能な決済要求コマンドを下記表に示します。
| 決済要求種類 /コマンド |
概要 |
|---|---|
|
決済申込 （与信＋売上） /Authorize |
決済の申し込みと売上を同時に要求します。 事前に会員および銀行口座情報の登録が必要になります。 |
|
返金 /Refund |
売上済の取引に対し、返金を要求します。 ※全額返金のみ可能 |
|
会員登録 /MemberAdd |
会員の登録を要求します。 |
|
会員情報更新 /MemberUpdate |
会員情報の更新を要求します。 |
|
会員削除 /MemberDelete |
会員の削除を要求します。 |
|
口座入力情報取得 /PrepareAccountAdd |
口座情報入力画面を表示するために必要な情報を取得します。 口座登録の遷移については「3-2 決済処理シーケンス」の【口座登録処理】および 「6-2会員登録での遷移について」を参照してください。 |
|
口座登録 /AccountAdd |
口座の登録を行うための画面に遷移するために必要な情報を取得します。 |
|
口座削除 /AccountDelete |
口座の削除を要求します。 |
|
口座照会 /AccountGet |
口座情報の照会を要求します。 |
決済処理シーケンス
【決済申込処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 決済申込要求 | 決済申込の対象となる取引情報を電文化し、決済サーバーに送信します。 |
| 2 | 決済申込応答 | 決済サーバーより結果応答を受信します。 |
【返金処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 返金要求 | 返金の対象となる取引情報を電文化し、決済サーバーに送信します。 |
| 2 | 返金応答 | 決済サーバーより結果応答を受信します。 |
【会員登録処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 会員登録要求 | 会員登録に必要な情報を電文化し、決済サーバーに送信します。 |
| 2 | 会員登録応答 | 決済サーバーより結果応答を受信します。 |
【会員情報更新処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 会員情報更新要求 | 会員情報更新に必要な情報を電文化し、決済サーバーに送信します。 |
| 2 | 会員情報更新応答 | 決済サーバーより結果応答を受信します。 |
【会員削除処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 会員削除要求 | 会員削除に必要な情報を電文化し、決済サーバーに送信します。 |
| 2 | 会員削除応答 | 決済サーバーより結果応答を受信します。 |
【口座登録処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 銀行選択画面の表示 | 口座登録を行う銀行を選択する画面を加盟店が作成します。 |
| 2 | 口座入力情報取得要求 | 口座情報入力取得に必要な情報を電文化し、決済サーバーに送信します。 |
| 3 | 結果応答 | 決済サーバーからの応答から口座情報入力画面に必要な項目を確認し、口座情報入力画面を作成します。 |
| 4 | 口座情報入力画面の表示 | 口座登録に必要な情報を入力するための画面を表示します。 |
| 5 | リダイレクトパラメータ要求 | 口座情報を入力後、口座登録処理に必要な情報を取得します。 この処理は非同期通信（Ajaxなど）で実施し、「6. 口座登録要求」に不要なパラメータ（口座番号などの口座情報）は加盟店様サイトに送信しないように注意してください。 また、ここで取得するパラメータには有効期限が存在します。口座情報入力中に有効期限が切れることを防ぐため、口座情報入力後にこの処理を実施するようにしてください。 |
| 6 | 口座登録要求 | 口座登録に必要な情報を電文化し、決済サーバーに送信します。 |
| 7 | 結果応答 | 口座情報以外の口座登録に必要な情報を受信します。 |
| 8 | リダイレクトパラメータ応答 | 加盟店サーバーから受信したリダイレクトに必要なパラメータと、画面上で入力済みの口座情報を用いて次の処理に進みます。 |
| 9 | 口座登録処理結果通知 | BankPayへ口座登録処理を開始するための要求を行います。 詳細は「6.1.3 BankPayへの遷移処理」を参照してください。 |
| 10 | 口座登録処理結果通知 |
口座登録結果を受け取り、加盟店システムに反映します。
完了画面要求は、消費者の端末（PCやスマートフォン）のネットワーク環境の問題や、誤操作（ブラウザやタブを閉じてしまう等）により、正しく行われない可能性がありますので、必ずこの通知を受信してください。 なお、結果通知と完了画面要求のリダイレクト結果が加盟店に届く順番は保証されていません。どちらが先に届いても問題とならないようにご対応ください。 |
| 11 | 完了画面要求 | 決済サーバーから応答されたBankPayの口座登録結果を加盟店の画面などに表示し、消費者に結果をお伝えください。 |
【口座削除処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 口座削除要求 | 口座削除に必要な情報を電文化し、決済サーバーに送信します。 |
| 2 | 口座削除応答 | 決済サーバーより結果応答を受信します。 |
【口座照会処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 口座照会要求 | 口座照会に必要な情報を電文化し、決済サーバーに送信します。 |
| 2 | 口座照会応答 | 決済サーバーより結果応答を受信します。 |
結果通知受信処理
結果通知受信処理の対象
BankPayの結果通知受信処理の対象は以下の機能です。
| コマンド名 | 送信有無 |
|---|---|
| 決済申込 | － |
| 返金 | － |
| 会員登録 | － |
| 会員情報更新 | － |
| 会員削除 | － |
| 口座登録 | ○ |
| 口座削除 | － |
| 口座照会 | － (※1) |
※1) 口座照会の対象の会員IDにおいて、登録中の口座が存在していた場合は登録結果を確認し、登録結果が確定した場合は口座登録と同様に結果通知を送信します。
通信電文仕様（共通部）および店舗様受信後応答仕様は、『開発ガイド』をご参照ください。
BankPay固有の通知電文インターフェイスにつきましては、「5-3 結果通知電文」の「5.3.2 BankPayの結果通知電文」をご参照ください。
インターフェイス詳細
ここではBankPayサービスで利用するMDKインターフェイス項目を説明します。
-
「設定」欄の内容は以下の通りです。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※、※n（条件は説明欄、または欄外に記入）
- 応答電文 ...
- 必ず返戻：○ 返戻しないケースあり：△ 返戻なし：× その他条件付：※
-
orderId（取引ID）について
店舗様で任意に採番してください。申込、再与信処理毎に付ける必要があります。他の取引IDと重複しないよう採番してください。他決済サービスとも重複できません。
また、テスト取引で使用した取引IDを、本番取引で再度使用することはできません。
取引IDには、半角英数字以外に"-"（ハイフン）、"_"（アンダースコア）も使用可能です。 -
応答電文について
応答電文には、本書に記載されていないフィールド（パラメータ）も存在しますが、通常は、記載されているフィールド以外は加盟店の方で意識する必要はございません。
BankPay
決済申込
| 要求電文 ： BankPayAuthorizeRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 100桁以内 |
店舗側で採番した取引IDを指定 上記「orderId（取引ID）について」参照 |
○ |
| amount | 決済金額 | 半角数字 7桁以内 |
決済金額を指定 - 1 以上かつ 9999999(7桁) 以下 |
○ |
| memberId | 会員ID | 半角英数字 100桁以内 |
会員登録を行った店舗側で会員を一意に表す会員IDを指定します。 | ○ |
| accountId | 口座ID | 半角英数字 100桁以内 |
会員IDに紐づく口座IDを指定します。 | ○ |
| accountingType | 課金種別 | 右記参照 | "0"：都度決済 "1"：随時決済 "2"：チャージ（オープン） "3"：チャージ（ハウス） "4"：チャージ（資金移動） |
○ |
| terminalId | 端末機識別番号 | 半角数字 13桁 |
店舗POSなどの決済端末を識別する値を指定 チャージのみの利用の場合は、一意な値を設定して問題ございません。 流通決済事業者コードを設定可能な場合は先頭5桁に設定することをお勧めします。 流通事業者コード： https://www.dsri.jp/code/credit/ |
○ |
| storeId | 店舗ID | 半角英数字 5桁 |
任意の店舗IDを指定 | △ |
| storeName | 店舗名 | 文字列 50桁以内 |
利用者アプリ表示用の店舗名 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ |
| 応答電文 ： BankPayAuthorizeResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ | 半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 "pending"：保留 |
○ |
| vResultCode | 詳細結果コード | 半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ | 文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ |
| marchTxn | 電文ID | 文字列 100桁以内 |
決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。 |
○ |
| orderId | 取引ID | 半角英数字 100 桁以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID | 文字列 100桁以内 |
決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| txnVersion | MDK バージョン | 半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| merchantTransactionId | 加盟店処理通番 | 半角英数字 100 桁以内 |
BankPayで取引を一意に識別するID | △ |
| centerTransactionId | 決済センター側の処理通番 | 半角英数字 36桁 |
BankPayにて採番する処理通番 | △ |
| bankApprovalNum | 承認番号 | 半角英数字 7 桁以内 |
金融機関にて採番する承認番号 | △ |
| bankProcessingId | 決済処理通番 | 半角英数字 7桁 |
金融機関にて採番する決済処理通番 | △ |
| centerProcessingDatetime | 決済センター処理日時 | 半角数字 14桁 |
BankPay側で処理された日時を返却します。 （YYYYMMDDhhmmss形式） |
△ |
返金
| 要求電文 ： BankPayRefundRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 100桁以内 |
決済申込で指定した値を設定します。 | ○ |
| amount | 返金金額 | 半角数字 7桁以内 |
返金金額を指定。
※全額返金のみ可能。 |
△ |
| terminalId | 端末機識別番号 | 半角数字 13桁 |
店舗POSなどの決済端末を識別する値を指定 チャージのみの利用の場合は、一意な値を設定して問題ございません。 流通決済事業者コードを設定可能な場合は先頭5桁に設定することをお勧めします。 流通事業者コード： https://www.dsri.jp/code/credit/ ※未指定時は決済申込で指定した値を使用 |
△ |
| storeId | 店舗ID | 半角英数字 5桁 |
任意の店舗IDを指定 | △ |
| storeName | 店舗名 | 文字列 50桁以内 |
利用者アプリ表示用の店舗名 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ |
| 応答電文 ： BankPayRefundResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ |
半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 "pending"：保留 |
○ |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ |
文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ |
| marchTxn | 電文ID |
文字列 100桁以内 |
決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。 |
○ |
| orderId | 取引ID |
半角英数字 100桁以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID |
文字列 100桁以内 |
決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| txnVersion | MDK バージョン |
半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| memberId | 会員ID |
半角英数字 100桁以内 |
決済申込時に指定した会員ID | △ |
| accountId | 口座ID |
半角英数字 100桁以内 |
決済申込時に指定した口座ID | △ |
| accountingType | 課金種別 | 右記参照 | 決済申込時に指定した課金種別 | △ |
| terminalId | 端末機識別番号 |
半角数字 13桁 |
要求電文で指定した端末識別番号 | △ |
| merchantTransactionId | 加盟店処理通番 |
半角英数字 100 桁以内 |
BankPayで取引を一意に識別するID | △ |
| centerTransactionId | 決済センター側の処理通番 |
半角英数字 36桁 |
BankPayにて採番する処理通番 | △ |
| bankApprovalNum | 承認番号 |
半角英数字 7 桁以内 |
金融機関にて採番する承認番号 | △ |
| bankProcessingId | 決済処理通番 |
半角英数字 7桁 |
金融機関にて採番する決済処理通番 | △ |
| centerProcessingDatetime | 決済センター処理日時 |
半角数字 14桁 |
BankPay側で処理された日時を返却します。 （YYYYMMDDhhmmss形式） |
△ |
会員登録
| 要求電文 ： BankPayMemberAddRequestDto | |||||
|---|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 | |
| memberId | 会員ID |
半角英数字 100桁以内 |
加盟店側で会員を一意に表す顧客IDを指定します。 "-"（ハイフン）、"_"（アンダースコア）も使用可能です。 |
○ | |
| userTerminalId | 利用者端末識別ID |
半角英数字 32桁 |
利用者の端末を識別するIDを指定します。 スマホなどのデバイスを識別するためのUUIDなどの情報を指定してください。EC利用などの場合は一意なランダムな値を指定してください。 |
○ | |
| userName | 氏名 |
文字列 20桁以内 |
会員の氏名を入力します。 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ | |
| userNameKana | カナ氏名 |
文字列 40桁以内 |
会員のカナ名を入力します。 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ | |
| birthDate | 生年月日 |
半角数字 8桁 |
会員の生年月日を入力します。 書式はYYYYMMDD。 例)20220531 |
△ | |
| gender | 性別 |
半角英字 1桁 |
会員の性別を入力します。 -"M":男 -"F":女 |
△ | |
| zipcode | 郵便番号 |
半角数字記号 8桁以内 |
会員の郵便番号を入力します。 "-"（ハイフン）有でも無でも指定可能です。 |
△ | |
| address | 住所 |
文字列 60桁以内 |
会員の住所を入力します。 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ | |
| telNumber | 電話番号 |
半角数字記号 16桁以内 |
会員の電話番号を入力します。 "-"（ハイフン）有でも無でも指定可能です。 |
△ | |
| mobileNumber | 携帯番号 |
半角数字記号 16桁以内 |
会員の携帯番号を入力します。 "-"（ハイフン）有でも無でも指定可能です。 |
△ | |
| emailAddress | メールアドレス |
半角英数字記号 300桁以内 |
会員のメールアドレスを入力します。 | △ | |
| emailAddress2 | メールアドレス2 |
半角英数字記号 300桁以内 |
会員のメールアドレスが2つある場合2つ目を入力します。 | △ | |
| remarks | 摘要 |
文字列 100桁以内 |
会員についての備考項目を入力します。 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ | |
| 応答電文 ： BankPayMemberAddResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ |
半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ |
文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ |
| txnVersion | MDK バージョン |
半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 | △ |
| memberId | 会員ID |
半角英数字 100桁以内 |
リクエストされた値 | △ |
| merchantUserId | 顧客ID |
半角英数字 60桁以内 |
BankPayで会員を一意に識別するID | △ |
| centerTransactionId | 決済センター側の処理通番 |
半角英数字 36桁 |
BankPayにて採番する処理通番 | △ |
| centerProcessingDatetime | 決済センター処理日時 |
半角数字 14桁 |
BankPay側で処理された日時を返却します。 （YYYYMMDDhhmmss形式） |
△ |
会員情報更新
| 要求電文 ： BankPayMemberUpdateRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| memberId | 会員ID |
半角英数字 100桁以内 |
会員登録で指定した値を設定します。 | ○ |
| userTerminalId | 利用者端末識別ID |
半角英数字 32桁 |
利用者の端末を識別するIDを指定します。 スマホなどのデバイスを識別するためのUUIDなどの情報を指定してください。EC利用などの場合は一意なランダムな値を指定してください。 |
△ |
| userName | 氏名 |
文字列 20桁以内 |
会員の氏名を入力します。 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ |
| userNameKana | カナ氏名 |
文字列 40桁以内 |
会員のカナ名を入力します。 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ |
| birthDate | 生年月日 |
半角数字 8桁 |
会員の生年月日を入力します。 書式はYYYYMMDD。 例)20220531 |
△ |
| gender | 性別 |
半角英字 1桁 |
会員の性別を入力します。 "M" ：男 "F" ：女 |
△ |
| zipcode | 郵便番号 |
半角数字記号 8桁以内 |
会員の郵便番号を入力します。 "-"（ハイフン）有でも無でも指定可能です。 |
△ |
| address | 住所 |
文字列 60桁以内 |
会員の住所を入力します。 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ |
| telNumber | 電話番号 |
半角数字記号 16桁以内 |
会員の電話番号を入力します。 "-"（ハイフン）有でも無でも指定可能です。 |
△ |
| mobileNumber | 携帯番号 |
半角数字記号 16桁以内 |
会員の携帯番号を入力します。 "-"（ハイフン）有でも無でも指定可能です。 |
△ |
| emailAddress | メールアドレス |
半角英数字記号 300桁以内 |
会員のメールアドレスを入力します。 | △ |
| emailAddress2 | メールアドレス2 |
半角英数字記号 300桁以内 |
会員のメールアドレスが2つある場合2つ目を入力します。 | △ |
| remarks | 摘要 |
文字列 100桁以内 |
会員についての備考項目を入力します。 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△ |
| 応答電文 ： BankPayMemberUpdateResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ |
半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ |
文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ |
| txnVersion | MDK バージョン |
半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 | △ |
| memberId | 会員ID |
半角英数字 100桁以内 |
リクエストされた値 | △ |
| centerTransactionId | 決済センター側の処理通番 |
半角英数字 36桁 |
BankPayにて採番する処理通番 | △ |
| centerProcessingDatetime | 決済センター処理日時 |
半角数字 14桁 |
BankPay側で処理された日時を返却します。 （YYYYMMDDhhmmss形式） |
△ |
会員削除
| 要求電文 ： BankPayMemberDeleteRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| memberId | 会員ID |
半角英数字 100桁以内 |
会員登録で指定した値を設定します。 | ○ |
| 応答電文 ： BankPayMemberDeleteResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ |
半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ |
文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ |
| txnVersion | MDK バージョン |
半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 | △ |
| memberId | 会員ID |
半角英数字 100桁以内 |
リクエストされた値 | △ |
| centerTransactionId | 決済センター側の処理通番 |
半角英数字 36桁 |
BankPayにて採番する処理通番 | △ |
| centerProcessingDatetime | 決済センター処理日時 |
半角数字 14桁 |
BankPay側で処理された日時を返却します。 （YYYYMMDDhhmmss形式） |
△ |
口座入力情報取得
| 要求電文 ： BankPayPrepareAccountAddRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| memberId | 会員ID |
半角英数字 100桁以内 |
会員登録で指定した値を設定します。 | ○ |
| accountId | 口座ID |
半角英数字 100桁以内 |
会員ＩＤに対して口座を一意に表す口座IDを指定します。 "-"（ハイフン）、"_"（アンダースコア）も使用可能です。 |
○ |
| bankCode | 銀行コード |
半角数字 4桁 |
登録口座の銀行コードを入力します。 | ○ |
| successUrl | 決済完了時URL |
URLに使用可能な半角文字
256桁以内 |
口座登録完了後に、店舗側サイトに画面遷移を戻すためのURLを指定します。
※未指定の場合は、MAP（Merchant Administrator Portal）から登録申請した値を使用。 |
△ |
| errorUrl | 決済エラー時URL |
URLに使用可能な半角文字
256桁以内 |
口座登録エラー時に、店舗側サイトに画面遷移を戻すためのURLを指定します。
※未指定の場合は、MAP（Merchant Administrator Portal）から登録申請した値を使用。 |
△ |
| pushUrl | プッシュ先URL |
URLに使用可能な半角文字
256桁以内 |
プッシュURLを指定します。
※未指定の場合は、MAP（Merchant Administrator Portal）から登録申請した値を使用。 |
△ |
| 応答電文 ： BankPayPrepareAccountAddResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ |
半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ |
文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ |
| txnVersion | MDK バージョン |
半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 | △ |
| memberId | 会員ID |
半角英数字 100桁以内 |
要求電文に設定した値 | △ |
| accountId | 口座ＩＤ |
半角英数字 100桁以内 |
要求電文に設定した値 | △ |
| branchCodeFlag | 支店コード入力要否 |
半角英字 5桁以内 |
口座の支店コード入力要否を返却します。 "true"：入力が必要 "false"：入力が不要 |
△ |
| depositTypeFlag | 預金種目入力要否 |
半角英字 5桁以内 |
口座の預金種目入力要否を返却します。 "true"：入力が必要 "false"：入力が不要 |
△ |
| accountNumFlag | 口座番号入力要否 |
半角英字 5桁以内 |
口座の口座番号入力要否を返却します。 "true"：入力が必要 "false"：入力が不要 |
△ |
| accountNameFlag | 口座名義人名入力要否 |
半角英字 5桁以内 |
口座の口座名義人名入力要否を返却します。 "true"：入力が必要 "false"：入力が不要 |
△ |
| centerTransactionId | 決済センター側の処理通番 |
半角英数字 36桁 |
BankPayにて採番する処理通番 | △ |
| centerProcessingDatetime | 決済センター処理日時 |
半角数字 14桁 |
BankPay側で処理された日時を返却します。 （YYYYMMDDhhmmss形式） |
△ |
口座登録
口座登録処理を完了させるためには、口座登録コマンド実施後にBankPayへの遷移が必要になります。
詳細については、「6.1.3 BankPayへの遷移処理」を参照してください。
| 要求電文 ： BankPayAccountAddRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| memberId | 会員ID |
半角英数字 100桁以内 |
口座入力情報取得で指定した値を設定します。 | ○ |
| accountId | 口座ID |
半角英数字 100桁以内 |
口座入力情報取得で指定した値を設定します。 | ○ |
| 応答電文 ： BankPayAccountAddResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ |
半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ |
文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ |
| txnVersion | MDK バージョン |
半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 | △ |
| preparedProcessId | 口座入力情報取得の処理通番 |
半角英数字 100桁以内 |
口座入力情報取得時に決済サーバーにて採番されたprocessId。 | △ |
| memberId | 会員ID |
半角英数字 100桁以内 |
要求電文に設定した値 | △ |
| accountId | 口座ＩＤ |
半角英数字 100桁以内 |
要求電文に設定した値 | △ |
| bankpayAccountsRegisterUrl | BankPay口座登録URL |
URLに使用可能な半角文字
256桁以内 |
BankPayへの遷移に必要な項目。 BankPayに遷移するために使用してください。 |
△ |
| accountLabel | 口座ラベル |
文字列 50桁以内 |
BankPayへの遷移に必要な項目。 | △ |
| backUrl | 戻り先URL |
URLに使用可能な半角文字
256桁以内 |
BankPayへの遷移に必要な項目。 | △ |
| customerAccessToken | 会員用アクセストークン |
半角英数字 32桁 |
BankPayへの遷移に必要な項目。 | △ |
| processorAuthenticationKeyIndex | Pay事業者認証鍵世代番号 |
半角数字 2桁 |
BankPayへの遷移に必要な項目。 | △ |
| mac | メッセージ認証コード |
半角英数字 44桁 |
BankPayへの遷移に必要な項目。 | △ |
消費者ブラウザから店舗側の確認画面へリダイレクトする時のパラメータ
| リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗側へリダイレクト(POST)される内容 | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success" ：正常終了 "failure" ：異常終了 |
○ |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 | △ |
| memberId | 会員ID |
半角英数字 100桁以内 |
要求電文に設定した値 | △ |
| accountId | 口座ＩＤ |
半角英数字 100桁以内 |
要求電文に設定した値 | △ |
| bankCode | 銀行コード |
半角数字 4桁 |
登録された銀行コードを返却します。 | △ |
| branchCode | 支店コード |
半角数字 3桁 |
登録された支店コードを返却します。 | △ |
| depositType | 預金種目 |
半角数字 1桁 |
登録された預金種目を返却します。 "1": 普通口座 "2": 当座口座 |
△ |
| maskedAccountNum |
マスクされた 口座番号 |
半角数字記号 7桁 |
登録された口座番号(マスクした値)を返却します。 | △ |
| maskedAccountName |
マスクされた 口座名義人名 |
文字列 30文字以内 |
登録された口座名義人名(マスクした値)を返却します。 | △ |
| txnType | トランザクションタイプ |
文字列 32文字以内 |
実行したコマンド名。 "AccountAdd"：口座登録結果通知 |
△ |
| centerTransactionId | 決済センター側の処理通番 |
半角英数字 36桁 |
BankPayにて採番する処理通番 | △ |
| centerProcessingDatetime | 決済センター処理日時 |
半角数字 14桁 |
BankPay側で処理された日時を返却します。 （YYYYMMDDhhmmss形式） |
△ |
| vAuthInfo |
改ざんチェック用 ハッシュ値 |
文字列 右記参照 |
下記文字列を連結し、SHA-256によって算出したハッシュ値 ・マーチャントCCID ・パラメータ値の連結文字列（authParams が示す順序で連結） ・パスワード 尚、パラメータ値を連結する際は、パラメータ名や区切り文字は含めず、パラメータ値のみを連結しています。連結した文字列をバイナリに変換する際の文字エンコーディングは、UTF-8を使用しています。 |
〇 |
| authParams | ハッシュ値算出パラメータ順序 |
文字列 右記参照 |
vAuthInfo のハッシュ値を算出する元とした文字列の、パラメータの連結順序を示す値
パラメータ名のカンマ区切り文字列をBase64エンコードしています。デコードを行うと文字列が復元されます。 例) "orderId,vResultCode,mstatus" "mstatus,orderId,vResultCode" （順序は固定ではないため、リクエスト受信のたびに動的に処理する必要があります。） |
○ |
（重要）
これらのパラメータはブラウザを経由して連携されるため、画面遷移が正常に行われないケースでは取得することができません。そのため、決済サーバーから直接送信される「5-3 結果通知電文」の受信と組み合わせて確実に結果を取得してください。
vAuthInfoおよびauthParamsを利用した改ざんチェックについて
決済サーバーから消費者ブラウザを経由して店舗側の結果画面に遷移（リダイレクト）しますが、ここで店舗側システムが受け取ったパラメータが改ざんされていないことを検証するためのパラメータが、vAuthInfoとauthParamsです。
店舗側システムで算出したハッシュ値が、パラメータより取得したvAuthInfoと一致している場合は、パラメータは改ざんされていない、とみなすことができます。
この改ざんチェックは、悪意を持った第三者によって、不正なリダイレクト電文を受信する可能性がありますので、実装を強く推奨しています。
パラメータは将来的に追加される可能性がございます。上記に定義されたフィールド名以外のフィールドが連携された場合でもエラーとならないようご注意ください。
口座削除
| 要求電文 ： BankPayAccountDeleteRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| memberId | 会員ID |
半角英数字 100桁以内 |
口座登録で指定した値を設定します。 | ○ |
| accountId | 口座ID |
半角英数字 100桁以内 |
口座登録で指定した値を設定します。 | ○ |
| 応答電文 ： BankPayAccountDeleteResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ |
半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ |
文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ |
| txnVersion | MDK バージョン |
半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 | △ |
| memberId | 会員ID |
半角英数字 100桁以内 |
要求電文に設定した値 | △ |
| accountId | 口座ＩＤ |
半角英数字 100桁以内 |
要求電文に設定した値 | △ |
| centerTransactionId | 決済センター側の処理通番 |
半角英数字 36桁 |
BankPayにて採番する処理通番 | △ |
| centerProcessingDatetime | 決済センター処理日時 |
半角数字 14桁 |
BankPay側で処理された日時を返却します。 （YYYYMMDDhhmmss形式） |
△ |
口座照会
| 要求電文 ： BankPayAccountGetRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| memberId | 会員ID |
半角英数字 100桁以内 |
照会対象の会員IDを指定します。 | ○ |
| accountId | 口座ID |
半角英数字 100桁以内 |
照会対象の口座IDを指定します。 未指定の場合は、会員IDに紐づくすべての口座の情報を取得します。 |
△ |
| 応答電文 ： BankPayAccountGetResponseDto | |||||
|---|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 | |
| serviceType | 決済サービスタイプ |
半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ | |
| mstatus | 処理結果コード |
半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ | |
| vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ | |
| merrMsg | エラーメッセージ |
文字列 1024 byte以内 |
処理結果を日本語で表示 | ○ | |
| processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 | △ | |
| txnVersion | MDK バージョン |
半角英数字 5桁 |
電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ | |
| memberId | 会員ID |
半角英数字 100桁以内 |
要求電文に設定した値 | △ | |
| accountId | 口座ID |
半角英数字 100桁以内 |
要求電文に設定した値 | △ | |
| accounts | 口座情報の配列 | BankPayAccountの配列 | △ | ||
| accountId | 口座ID |
半角英数字 100桁以内 |
会員IDに紐づく口座ID | △ | |
| maskedAccountNum | 口座番号(マスクした値) |
半角数字記号 7桁 |
口座番号(マスクした値) | △ | |
| bankCode | 銀行コード |
半角数字 4桁 |
銀行コード | △ | |
| branchCode | 支店コード |
半角数字 3桁 |
支店コード | △ | |
| depositType | 預金種目 |
半角数字 1桁 |
預金種目 "1": 普通口座 "2": 当座口座 |
△ | |
| isValid | 有効区分 |
半角英字 5桁以内 |
"true"：有効 "false"：無効 本パラメータが"false"の場合は決済に利用できませんので、口座削除の実施を推奨します。 |
△ | |
| maskedAccountName | 口座名義人名(マスクした値) |
文字列 30文字以内 |
口座名義人名(マスクした値)
※現在の仕様では設定されることはありません。 |
△ | |
共通
検索
-
「設定」欄の内容は以下の通りとなります。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※（条件は説明欄に記入）
- 応答電文 ...
- 必ず返戻：○ 該当取引存在時に返戻：△ 返戻なし：× その他条件付：※
-
複数指定は0～の添字を指定します。
例）exparam.serviceTypeCd[0]=card&exparam.serviceTypeCd[1]=BankPay -
ワイルドカードは値の一部と"*"を組み合わせて検索します。"*"のみの指定はできません。
例）exparam.searchParameters.common.orderId=123*
| 要求電文 ： SearchRequestDto | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ※ 以下は、共通の検索要求フィールドです。 | ||||||||||||
| 検索フィールド名 | 検索項目名 | 書式・制限 |
複数 指定 |
ﾜｲﾙﾄﾞ ｶｰﾄﾞ |
説明 | 設定 | ||||||
| requestId | リクエストID | 半角英数字記号128文字以内 | リクエストIDを指定します。指定した場合は、それ以外のパラメータは指定できなくなります。 | △ | ||||||||
| serviceTypeCd | 決済サービスタイプ | 右記参照 | ○ |
検索対象の決済を指定します。未指定の場合は、全決済が検索対象となります。 "bankpay"： BankPay |
△ | |||||||
| newerFlag | 最新トランザクションフラグ | 右記参照 |
成功、失敗に関係なく、最新トランザクションのみを検索する場合に使用します。 "true"： 1取引内の最新トランザクションのみ検索 "false"： 全てのトランザクションを検索 ※指定しない場合は"false"になります。 |
△ | ||||||||
| containDummyFlag | ダミー決済対象フラグ | 右記参照 |
ダミー取引も検索する場合に使用します。 "true"： ダミー取引も検索する "false"： ダミー取引は検索しない ※指定しない場合は"false"になります。 |
△ | ||||||||
| maxCount | 検索最大件数 | 1～1000 |
取得したい検索結果の最大件数です。未指定の場合、最大値となります。
※短時間で大量の検索を繰り返すような処理は決済サーバーに負荷が掛かりますのでご遠慮頂けますようお願いします。 |
△ | ||||||||
| common 共通 | ||||||||||||
| orderId | 取引ID | 半角英数字100桁以内 | ○ | 検索したい取引IDを指定します。 | △ | |||||||
| orderStatus | 取引決済状態 | 右記参照 | ○ |
以下のいずれかを指定します。 " initial "：初期状態 " end "：終了 " pending "：保留 " validation_error "：検証エラー " expired "：期限切れ " error "：エラー |
△ | |||||||
| command | コマンド | 右記参照 | ○ |
決済で使用するコマンドを指定します。 " Authorize "：申込（与信または与信＋売上） " Refund "：返金 |
△ | |||||||
| mstatus | ステータスコード |
右記参照 | ○ |
決済結果として返戻されるステータスコードを指定します。 " success "：成功 " failure "：失敗 " pending "：保留 |
△ | |||||||
| txnDatetime.from | 取引日（From） | 文字列12桁 |
取引日時の範囲（From）を指定します。 YYYYMMDDhhmm形式 |
△ | ||||||||
| txnDatetime.to | 取引日（To） | 文字列12桁 |
取引日時の範囲（To）を指定します。 YYYYMMDDhhmm形式 |
△ | ||||||||
| amount.from | 金額（From） | 数字12桁以内 | 決済金額の範囲（From）を指定します。 | △ | ||||||||
| amount.to | 金額（To） | 数字12桁以内 | 決済金額の範囲（To）を指定します。 | △ | ||||||||
| ※ 以下は、BankPay固有の検索要求フィールドです。 | ||||||||||||
| BankPay BankPay | ||||||||||||
| detailOrderType | 詳細オーダー決済状態 | 右記参照 | ○ |
※「detailOrderType」の詳細は7-1検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）を参照 |
△ | |||||||
| detailCommandType | 詳細コマンドタイプ | 右記参照 | ○ |
※「detailCommandType」の詳細は7-1検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）を参照 |
△ | |||||||
| centerTransactionId | 決済センターのトランザクション管理ID |
半角英数字 36 桁以内 |
決済センターがトランザクション毎に発番するIDを指定します。 | △ | ||||||||
| memberId | 会員ID | 半角英数字 100桁以内 |
会員IDを指定します。 | △ | ||||||||
| accountId | 口座ID | 半角英数字 100桁以内 |
会員IDに紐づく口座IDを指定します。
※口座IDを設定する場合は、会員IDの指定が必須です。 |
※ | ||||||||
| 応答電文 ： SearchResponseDto | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ※ 以下は、共通の検索結果フィールドです。 | ||||||||||||
| 検索フィールド名 | 検索項目名 | 書式・制限 | 説明 | 設定 | ||||||||
| result | 処理結果 | － | ○ | |||||||||
| serviceType | サービスタイプ | 右記参照 | "search" | ○ | ||||||||
| mstatus | 処理結果コード | 半角英数字32文字以内 |
処理の結果ステータスが格納されます。 "success"：正常終了 "failure"：異常終了 |
○ | ||||||||
| vResultCode | 詳細結果コード | 半角英数字16文字 |
処理の結果を詳細に表すコードとなります。 詳細は『結果コード一覧』を参照下さい。 |
○ | ||||||||
| overMaxCountFlag | 最大件数超えフラグ | 右記参照 |
検索対象データが要求電文で指定した検索最大件数より多いかどうかを表します。 "true"： 最大件数以上 "false"： 最大件数未満 |
△ | ||||||||
| searchCount | 検索結果件数 | 0～1000 | 検索結果件数（オーダー件数）が格納されます。 | △ | ||||||||
| orderInfos | オーダー情報リスト | 複数のオーダー情報（orderInfo）が格納されます。 | △ | |||||||||
| orderInfo | オーダー情報 | － | 検索条件に該当した取引の情報が該当件数分繰り返されます。0～1000件（要求電文で指定した検索最大件数まで）となります。 | △ | ||||||||
| index | インデックス | 0～999 | 検索された情報のインデックスが格納されます。 | △ | ||||||||
| serviceTypeCd | 決済サービスタイプ | 右記参照 |
決済の種類が格納されます。 "bankpay"： BankPay |
△ | ||||||||
| orderId | 取引ID | 文字列 | 取引の取引IDが格納されます。 | △ | ||||||||
| orderStatus | 取引決済状態 | 右記参照 |
決済の状態が格納されます。 " initial "：初期状態 " end "：終了 " end_presentation "：画面遷移正常終了 " pending "：保留 " validation_error "：検証エラー " expired "：期限切れ " error "：エラー ※このフィールドは、取引IDに関連する注文データの状態を完全に表現するものではありません。サービスタイプによっては詳細な状態遷移を別のフィールドに保持している場合がありますので、店舗側システムの用途に合わせてsuccessDetailTxnTypeや、決済固有の状態フィールドをご参照ください。 |
△ | ||||||||
| lastSuccessTxnType | 最終成功トランザクションタイプ | 文字列 | 直近の成功したコマンド名が格納されます。 | △ | ||||||||
| successDetailTxnType | 詳細トランザクションタイプ | 文字列 |
取引の詳細な状態が格納されます。 検索要求電文の各決済の detailOrderType参照。 |
△ | ||||||||
| properOrderInfo | 固有オーダー情報 | － | 各決済サービスの固有オーダー情報が格納されます。後述の一覧参照。 | △ | ||||||||
| transactionInfos | 決済トランザクションリスト | － | 複数の決済トランザクション情報（transactionInfo）が格納されます。 | △ | ||||||||
| transactionInfo | 決済トランザクション情報 | － | 検索条件に該当した取引の情報が該当件数分繰り返されます。 | △ | ||||||||
| txnId | トランザクション管理ID | 文字列 | 決済サーバーが採番する管理IDとなります。 | △ | ||||||||
| command | コマンド | 文字列 |
実行されたコマンド名が格納されます。
※MDKで要求したコマンドだけでなく、決済サーバーの内部処理コマンドも含まれます。 |
△ | ||||||||
| mstatus | 処理結果コード | 半角英数字32文字以内 |
処理の結果ステータスが格納されます。 "success"：正常終了 "failure"：異常終了 "pending"：保留 |
△ | ||||||||
| vResultCode | 詳細結果コード | 文字列16桁 |
処理の結果を詳細に表すコードとなります。 詳細は『結果コード一覧』を参照下さい。 |
△ | ||||||||
| txnDatetime | 取引日時 | 文字列23桁 |
取引日時が格納されます。 YYYY-MM-DD hh:mi:ss.mmm形式 |
△ | ||||||||
| amount | 金額 | 半角数字12桁以内 | 決済した金額が格納されます。 | △ | ||||||||
| properTransactionInfo | 固有トランザクション情報 | － | 各決済サービスの固有トランザクション情報が格納されます。後述の一覧参照。 | △ | ||||||||
|
☆ 以下の情報は、上記 「固有オーダー情報」 「固有トランザクション情報」 内の階層にセットされます。 |
||||||||||||
| ※ 以下は、BankPay固有の検索結果フィールドです。 | ||||||||||||
| properOrderInfo | BankPay 固有オーダー情報 | |||||||||||
| accountingType | 課金種別 | 右記参照 |
決済申込時に指定した課金種別 "0"：都度決済 "1"：随時決済 "2"：チャージ（オープン） "3"：チャージ（ハウス） "4"：チャージ（資金移動） |
△ | ||||||||
| authorizeAmount | 申込金額 |
半角数字 7桁以内 |
決済申込時に指定した金額 | △ | ||||||||
| balance | 残高 |
半角数字 7桁以内 |
現在の残高 | △ | ||||||||
| memberId | 会員ID |
半角英数字 100桁以内 |
会員ID | △ | ||||||||
| accountId | 口座ID |
半角英数字 100桁以内 |
会員IDに紐づく口座ID | △ | ||||||||
| authorizeDatetime | 決済申込日時 |
半角数字 14桁 |
決済申込日時 YYYYMMDDhhmmss形式 |
△ | ||||||||
| refundDatetime | 返金日時 |
半角数字 14桁 |
返金日時 YYYYMMDDhhmmss形式 |
△ | ||||||||
| properTransactionInfo | BankPay 固有トランザクション情報 | |||||||||||
| bankpayErrorCode | BankPayエラーコード |
半角英数字 7 桁 |
BankPay側から返戻されたエラーコードが格納されます。 | △ | ||||||||
| centerTransactionId | 決済センターのトランザクション管理ID |
半角英数字 36 桁以内 |
決済センタートランザクション単位に発番するID | △ | ||||||||
| detailCommandType | 詳細コマンドタイプ | 文字列 |
※「detailCommandType」の詳細は「7-1検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）」を参照 |
△ | ||||||||
| storeId | 店舗ID |
半角英数字 5桁 |
決済申込もしくは返金時に指定した店舗ID | △ | ||||||||
| terminalId | 端末機識別番号 |
半角数字 13桁 |
決済申込もしくは返金時に指定した端末機識別番号 | △ | ||||||||
| bankpayRequestDatetime | 決済センターへの要求日時 |
半角数字 14桁 |
決済センターへの要求日時が格納されます。 YYYYMMDDhhmmss形式 |
△ | ||||||||
| bankpayResponseDatetime | 決済センターからの返戻日時 |
半角数字 14桁 |
決済センターからの返戻日時が格納されます。 YYYYMMDDhhmmss形式 |
△ | ||||||||
結果通知電文
結果通知電文の概要
実装方法の詳細につきましては、弊社より提供しているサンプルプログラムをご参照ください。
-
機能概要
決済サーバーから店舗様システムへ決済の結果通知を行います。
通知は、HTTPのPOSTを利用します。※プロトコルはHTTP（Port：80）、HTTPS（Port：443）に対応しています。
処理の概要については「第4章 結果通知受信処理」をご参照ください。 -
HMACについて
POSTにてデータを通知するとき、リクエストヘッダーにHMACを設定します。
また、HMAC値は、リクエストボディから算出します。
アルゴリズムは「HmacSHA256」が設定されます。表 5.1 リクエストヘッダーに設定するHMACフィールド フィールド名 設定値 content-hmac h={アルゴリズム名};s={CCID};v={HMAC値} -
結果通知受信処理結果について
決済サーバーからの通知に対して店舗様システムがHTTPステータスコード"200"を返戻した場合、受信処理が正常に終了したものと判断します。"200"以外のコードを返した場合は、受信失敗と判断し、一定期間、通知を繰り返します。※ 規定の回数失敗した場合は、通知処理が停止しますのでご注意ください。
BankPayの結果通知電文
BankPayにおける結果通知電文の通知タイミングは、下記となります。
| No. | 通知機能 | 通知タイミング | 注意事項 |
|---|---|---|---|
| 1 | 口座登録結果通知 （AccountAdd） |
口座登録が確定（成功、失敗）したタイミングで送信します。 口座登録が中断した場合は、成功、失敗が確定したタイミングで通知を行います。 |
以下に、BankPayの結果通知項目を示します。
| 項番 | フィールド名 | 項目名 | 書式・制限 | 説明 |
|---|---|---|---|---|
| 1 | numberOfNotify | 通知件数 | 半角数字4桁以内 |
1度に通知可能な件数は100件、 101件以上は次回通知 |
| 2 | pushTime | 送信時刻 | 半角数字14桁 |
決済サーバーから通知した時刻 yyyyMMddHHmmss形式 |
| 3 | pushId | 識別ID | 半角数字8桁 |
プッシュ処理を行うたびに採番されるID。
注） 他の決済サービスで使用されたIDと重複する場合があります。 |
| 通知件数分下記の項番（4～14）を繰り返す。尚、フィールド名の後ろに4ケタの連番（0000～0999）を付与する。 | ||||
| 4 | txnType | トランザクションタイプ |
文字列 32文字以内 |
実行したコマンド名。 "AccountAdd"：口座登録結果通知 |
| 5 | txnTime | 処理日時 | 半角数字14桁 | yyyyMMddHHmmss形式 |
| 6 | vResultCode | 詳細結果コード |
半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
| 7 | mstatus | 処理ステータス | 半角英数字8桁以内 |
"success"：正常終了 "failure"：異常終了 |
| 8 | dummy | ダミー決済フラグ | 半角数字1桁 | ダミー取引を示す場合は"1"を設定します。 |
| 9 | processId | 処理通番 |
半角英数字 100桁以内 |
決済サーバーにて採番する処理通番。 |
| 10 | memberId | 会員ID |
半角英数字 100桁以内 |
リクエストされた値 |
| 11 | accountId | 口座ID |
半角英数字 100桁 |
リクエストされた値 |
| 12 | bankCode | 銀行コード |
半角数字 4桁 |
登録された銀行コードを返却します。 |
| 13 | branchCode | 支店コード |
半角数字 3桁 |
登録された支店コードを返却します。 |
| 14 | depositType | 預金種目 |
半角数字 1桁 |
登録された預金種目を返却します。 "1": 普通口座 "2": 当座口座 |
| 15 | maskedAccountNum | 口座番号 |
半角数字記号 7桁 |
登録された口座番号(マスクした値)を返却します。 |
| 16 | maskedAccountName | 口座名義人名 |
文字列 30文字以内 |
登録された口座名義人名(マスクした値)を返却します。 |
| 17 | centerTransactionId | 決済センター側の処理通番 |
半角英数字 36桁 |
BankPayにて採番する処理通番 |
| 18 | centerProcessingDatetime | 決済センター処理日時 |
半角数字 14桁 |
BankPay側で処理された日時を返却します。YYYYMMDDhhmmss形式 |
- pushId（識別ID）は、他の決済サービスで使用されたIdと重複する場合がありますので、ユニークキーとして処理しないようにしてください。
- 項目の並び順は、必ずしも表の順序とは一致しません。
- 結果通知は将来的にフィールドが追加される可能性がございます。上記に定義されたフィールド名以外のフィールドが連携された場合でもエラーとならないようご注意ください。
- 口座登録失敗時や、途中離脱のリカバリ処理などにより口座登録結果が確定した場合は、パラメータの設定値が空になるケースが存在します。
ご利用上の注意事項
会員登録での遷移について
銀行選択画面
消費者が口座を登録する際、銀行毎に入力が必要な情報が異なります。
そのため、まずは銀行を選択する画面を表示して、銀行選択後は「5.1.6 口座入力情報取得」コマンドを実施して、入力が必要な項目を取得します。
口座情報入力画面
「6.1.1 銀行選択画面」で取得した情報をもとに、口座登録に必要な情報を入力するための画面を表示します。
口座情報入力後、「5.1.7 口座登録」コマンドを実施して、BankPayへの登録に必要な情報を取得します。
「5.1.7 口座登録」コマンドの実施時に、ブラウザから加盟店様サイトにリクエストをする際に、口座情報（金融機関名を除く）を送信しないように、非同期通信（Ajaxなど）を用いてコマンドの実施に必要な情報だけを加盟店様サイトにリクエストするようにしてください。
BankPayのガイドライン上でも口座情報は所有しないことを推奨しており、通過だけでもセキュリティのリスクは存在するため、非保持・非通過を推奨しています。
BankPayへの遷移処理
「6.1.2 口座情報入力画面」で取得した情報をもとに、BankPayへの遷移を実施します。
電文仕様
| 項目 | 仕様 |
|---|---|
| 遷移先URL | 「5.1.7 口座登録」コマンドのレスポンスパラメータの"bankpayAccountsRegisterUrl"の値 |
| HTTP Version | 1.1 |
| HTTP Metohd | POST |
| Encode | UTF-8 |
| content-type | application/x-www-form-urlencoded |
※その他のリクエストヘッダについてはRFCに準じて設定してください。
パラメータ
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
|---|---|---|---|---|
| bankCode | 銀行コード |
半角数字 4桁 |
「5.1.6 口座入力情報取得」コマンドで"bankCode"に指定した値 | ○ |
| branchCode | 支店コード |
半角数字 3桁 |
口座情報入力画面で入力した値 | △(※1) |
| depositType | 預金種目 |
半角数字 1桁 |
口座情報入力画面で入力した値 "1": 普通口座 "2": 当座口座 |
△(※1) |
| accountNum | 口座番号 |
半角数字 7桁 |
口座情報入力画面で入力した値 | △(※1) |
| accountName | 口座名義人名 |
全角英数カナ記号 30桁以内 |
口座情報入力画面で入力した値 使用可能文字については「7-2 使用可能文字」を参照してください。 |
△(※1) |
| accountLabel | 口座ラベル |
文字列 50桁以内 |
「5.1.7 口座登録」コマンドのレスポンスパラメータの"accountLabel"の値 | ○ |
| backURL | 戻り先URL |
URLに使用可能な半角文字
256桁以内 |
「5.1.7 口座登録」コマンドのレスポンスパラメータの"backUrl"の値 | ○ |
| cAccessToken | 会員用アクセストークン |
半角英数字 32桁 |
「5.1.7 口座登録」コマンドのレスポンスパラメータの"customerAccessToken "の値 | ○ |
| processorAuthenticationKeyIndex | Pay事業者認証鍵世代番号 |
文字列 2桁 |
「5.1.7 口座登録」コマンドのレスポンスパラメータの"processorAuthenticationKeyIndex"の値 | ○ |
| mac | メッセージ認証 コード |
文字列 44桁 |
「5.1.7 口座登録」コマンドのレスポンスパラメータの"mac"の値 | ○ |
※1) 「5.1.6 口座入力情報取得」コマンドのレスポンスで"true"となっている項目は必須
リクエストサンプル
<form method="post" action="https://example.com/hogehoge">
<input type="hidden" name="bankCode" value="0000">
<input type="hidden" name="branchCode" value="001">
<input type="hidden" name="depositType" value="1">
<input type="hidden" name="accountNum" value="1234567">
<input type="hidden" name="accountName" value="テストタロウ">
<input type="hidden" name="accountLabel" value="test">
<input type="hidden" name="backURL" value="https://example.com/fugafuga">
<input type="hidden" name="cAccessToken" value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">
<input type="hidden" name="processorAuthenticationKeyIndex" value="01">
<input type="hidden" name="MAC" value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">
</form>会員・口座の登録について
同一口座の登録について
複数の会員で同一の口座を登録した場合、新しく登録した方は利用可能となりますが、先に登録した方は利用不可となります。
利用不可となった口座は、口座照会コマンドのレスポンスパラメータの「isValid」が"false"となりますので、利用不可となった口座は口座削除コマンドを実施することを推奨します。
例） memberId1に紐づくaccountId1と同じ口座情報をmemberId2に紐づけて口座登録を実施
| 会員ID | 口座ID | 銀行 | 口座番号 | 有効区分 |
|---|---|---|---|---|
| memberId1 | accountId1 | ABC銀行 | 1111111 | true |
| accountId2 | DEF銀行 | 2222222 | true | |
| memberId2 | accountId3 | ABC銀行 | 3333333 | true |
| 会員ID | 口座ID | 銀行 | 口座番号 | 有効区分 |
|---|---|---|---|---|
| memberId1 | accountId1 | ABC銀行 | 1111111 | false |
| accountId2 | DEF銀行 | 2222222 | true | |
| memberId2 | accountId3 | ABC銀行 | 3333333 | true |
| accountId4 | ABC銀行 | 1111111 | true |
登録可能な口座数の上限について
会員毎に紐づけ可能な口座情報は最大8口座となります。
返金可能期間について
返金処理は決済申込を実施した当日中のみ可能です。
ただし、金融機関のサービス利用時間外などの理由により、当日中であってもエラーとなる可能性はございます。
その他 補足事項
検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）
決済サーバーでは、システム内部データとして詳細コマンド（処理要求の種類）と詳細な決済状態（その取引がどのような状態にあるか）を管理しています。
通常の運用では、店舗様システムではこれらの内部情報を利用する必要はありませんが、店舗様システムにおいて取引の状態検索が必要なケースや、障害等のお問い合わせ時の参照情報として、これらの内部データをSearchコマンドで公開しています。
下表にSearchコマンドにて利用可能な内部データの一覧を示します。
| 詳細コマンドタイプ | 詳細オーダー決済状態 | ||
|---|---|---|---|
| 論理名 | 値 | 論理名 | 値 |
| 売上（与信売上） | AuthCapture | 与信売上 | AuthCapture |
| 取消（与信売上） | VoidAuthCapture | 取消（与信売上） | VoidAuthCapture |
注） 一覧に記載していないコマンドタイプと状態も存在します。
使用可能文字
BankPayで使用可能な文字を以下の表の通りです。
氏名(userName)、カナ氏名(userNameKana)、住所(address)、摘要(remarks)
| 型 | 使用可能文字 |
|---|---|
| 半角数字 | 0 1 2 3 4 5 6 7 8 9 |
| 半角英字 | A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z |
| 半角カナ | ｱ ｲ ｳ ｴ ｵ ｶ ｷ ｸ ｹ ｺ ｻ ｼ ｽ ｾ ｿ ﾀ ﾁ ﾂ ﾃ ﾄ ﾅ ﾆ ﾇ ﾈ ﾉ ﾊ ﾋ ﾌ ﾍ ﾎ ﾏ ﾐ ﾑ ﾒ ﾓ ﾔ ﾕ ﾖ ﾗ ﾘ ﾙ ﾚ ﾛ ﾜ ｦ ﾝ ｧ ｨ ｩ ｪ ｫ ｯ ｬ ｭ ｮ ﾞ ﾟ |
| 半角記号 | ! " # $ % & ' ( ) * + , - . / @ [ \ ] ^ _ ` { | } ~ 半角スペース |
| 全角文字 | Unicode3.0.0 までに収録されている文字 |
口座名義人(accountName)
| 型 | 使用可能文字 |
|---|---|
| 全角数字 | ０ １ ２ ３ ４ ５ ６ ７ ８ ９ |
| 全角英字 | Ａ Ｂ Ｃ Ｄ Ｅ Ｆ Ｇ Ｈ Ｉ Ｊ Ｋ Ｌ Ｍ Ｎ Ｏ Ｐ Ｑ Ｒ Ｓ Ｔ Ｕ Ｖ Ｗ Ｘ Ｙ Ｚ ａ ｂ ｃ ｄ ｅ ｆ ｇ ｈ ｉ ｊ ｋ ｌ ｍ ｎ ｏ ｐ ｑ ｒ ｓ ｔ ｕ ｖ ｗ ｘ ｙ ｚ |
| 全角カナ | ア イ ウ エ オ カ キ ク ケ コ サ シ ス セ ソ タ チ ツ テ ト ナ ニ ヌ ネ ノ ハ ヒ フ ヘ ホ マ ミ ム メ モ ヤ ユ ヨ ラ リ ル レ ロ ワ ヲ ン ヴ ガ ギ グ ゲ ゴ ザ ジ ズ ゼ ゾ ダ ヂ ヅ デ ド バ ビ ブ ベ ボ パ ピ プペ ポ ァ ィ ゥ ェ ォ ヵ ヶ ッ ャ ュ ョ ヮ |
| 全角記号 | （ ） ー 全角スペース ※金融機関によって、上記以外に使える記号も存在します。 |
※口座名義人について、銀行毎の使用不可の文字は以下の表の通りです（2022/12/16時点）
今後BankPayに対応した銀行については、上記の表に記載があっても使用不可の可能性がございますので、ご注意ください。
| 銀行 | 型 | 使用不可文字 |
|---|---|---|
|
三菱UFJ銀行
※先頭に使用不可 |
全角数字 | すべて |
| 全角カナ | ヲ ァ ィ ゥ ェ ォ ャ ュ ョ ッ ヵ ヶ ヮ | |
| 全角記号 | ）全角スペース | |
| 住信SBIネット銀行 | 全角数字 | すべて |
| 全角英字 | すべて | |
| 全角カナ | ヵ ヶ ヮ |
導入・テストに関する補足
決済サーバーに接続し、テストを実施するための各種手続き・手順の詳細につきましては、『導入テストガイド』を参照してください。
口座登録時の画面遷移をシミュレートする
弊社では、BankPayのテストのための疑似環境を提供しております。 ダミー取引で「6.1.3 BankPayへの遷移処理」を実施すると、口座登録の認証画面のイメージが表示されます。
口座登録の認証画面からの遷移先の対応表を以下に記載します。
| 認証画面 | 決済結果画面からの遷移先 |
|---|---|
| 成功 | 決済完了時URL |
| 処理結果NGを引き渡す | 決済エラー時URL |
| 不正なパラメータを引き渡す | 決済サーバーのエラー画面 |
Authorie, Refundコマンドのエラーをシミュレートする
Authorize、Refundコマンドの要求金額（"amount"）の一の位の値を調整することで、意図的にエラーを発生させることができます。
（Refundコマンドで金額を指定しない場合は、対象取引の返金可能金額が要求金額に相当します。）
要求金額の下一桁と、返戻されるvResultCodeの対応表を以下に記載します。
| 金額の 下1桁 |
Authorize （決済申込） |
Refund （返金） |
|---|---|---|
| 0 | B001（成功） | B001（成功） |
| 1 | BGD1（失敗） | |
| 2 | BE50（ペンディング） | |
| 3 | BGD1（失敗） | B001（成功） |
| 4 | BE50（ペンディング） | |
| 5 | B001（成功） | |
| 6 | ||
| 7 | ||
| 8 | ||
| 9 |
会員系コマンドのエラーをシミュレートする
MemberAdd、MemberUpdate、MemberDeleteコマンドの会員ID（"memberId"）の末尾1文字の値を調整することで、意図的にエラーを発生させることができます。
会員IDの末尾1文字と、返戻されるvResultCodeの対応表を以下に記載します。
| 会員IDの 末尾1文字 |
MemberAdd （会員登録） |
MemberUpdate （会員情報更新） |
MemberDelete （会員削除） |
|---|---|---|---|
| 0 | B001（成功） | B001（成功） | B001（成功） |
| 1 | BGD2（失敗） | ||
| 2 | B001（成功） | ||
| 3 | BGD2（失敗） | ||
| 4 | B001（成功） | ||
| 5 | BGD2（失敗） | ||
| 6 | B001（成功） | ||
| 7 | |||
| 8 | |||
| 9 | |||
| その他の文字 |
口座系コマンドのエラーをシミュレートする
PrepareAccountAdd、AccountAdd、AccountDelete、AccountGetコマンドの口座ID（"accountId"）の末尾1文字の値を調整することで、意図的にエラーを発生させることができます。
口座IDの末尾1文字と、返戻されるvResultCodeの対応表を以下に記載します。
|
口座IDの 末尾1文字 |
PrepareAccountAdd （口座入力情報取得） |
AccountAdd （口座登録） |
AccountDelete （口座削除） |
AccountGet （口座照会） |
|---|---|---|---|---|
| 0 | B001（成功） | B001（成功）※1 | B001（成功） | B001（成功）※2 |
| 1 | BGD3（失敗） | |||
| 2 | B001（成功） | |||
| 3 | BGD3（失敗） | |||
| 4 | B001（成功）※1 | |||
| 5 | BGD3（失敗） | |||
| 6 | B001（成功） | |||
| 7 | BGD3（失敗） | |||
| 8 | B001（成功）※2 | |||
| 9 | ||||
| その他の文字 |
※1 口座登録の認証画面への遷移については、「8-1 口座登録時の画面遷移をシミュレートする」を参照してください。
※2 口座照会コマンドで取得できる口座情報は、口座登録で入力した値ではなく固定値となります。
ダミー取引で登録した会員・口座情報のデータ保持期間について
ダミー取引にて登録した会員・口座情報のデータ保持期間は、取引データの保持期間と同様になります（会員登録をした日から算出）。