コンビニ決済
本ドキュメントについて
本ガイドの内容
本ガイドは、株式会社DGフィナンシャルテクノロジーが提供するVeriTrans4Gを利用するための専用ソフトウェアMDK（Merchant Development Kit）をインターネット店舗などに導入する開発者向けのガイドです。VeriTrans4G コンビニ決済にて使用する電文のインターフェース詳細について記載しています。
VeriTrans4Gの詳細については、『VeriTrans4G 開発ガイド』を参照して下さい。
尚、インターフェース詳細は、決済サービス毎に提供していますので、当該決済サービスのインターフェース詳細を参照して下さい。
インターフェース詳細
本章では、各決済にて使用する電文（Dto）について説明します。以下の表に記載されているフィールドは、店舗様にて利用可能なフィールドです。
各電文（Dto）には、以下の表に記載されていないフィールドが定義されている場合がありますが、以下の表に記載されていないフィールドは店舗様では使用することはできません。
共通
-
「設定」欄の内容は以下の通りです。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※、※n（条件は説明欄、または欄外に記入）
- 応答電文 ...
- 必ず返戻：○ 処理成功時のみ返戻：△ 返戻なし：× その他条件付：※
-
orderId（取引ID）について
店舗で任意に採番してください。申込処理毎に付ける必要があります。他の取引IDと重複しないよう採番してください。他決済サービスとも重複できません。
また、テスト取引で使用した取引IDを、本番取引で再度使用することはできません。
取引IDには、半角英数字以外に"-"（ハイフン）、"_"（アンダースコア）も使用可能です。
申込
要求電文 ： CvsAuthorizeRequestDto
| 要求電文 ： CvsAuthorizeRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceOptionType | サービスオプションタイプ（コンビニタイプ） | 右記参照 |
"sej" ： セブン-イレブン ※上記以外のコンビニは、加盟店様のご契約内容により以下の2つのパターンに分かれます。
（パターン１） ファミリーマートとの接続形態が「直接接続」の場合
どちらのパターンを利用できるかは、MAPのダッシュボードの「サービス利用情報」より確認できます。 |
○ |
| orderId | 取引ID | 半角英数字100桁以内 | 「2-1 共通」の 「orderId（取引ID）について」を参照 | ○ |
| amount | 金額 | 半角数字6桁以内 |
1以上299,999以下。
※0円、または30万円以上の金額を設定した場合、エラーが発生するか、コンビニ店舗で支払受付を拒否される可能性があります。 |
○ |
| name1 | 氏名1 | 全角20バイト以内 | 顧客姓 文字列のサイズは、全角1文字を2バイトとみなした数値です。20バイトの場合は全角文字10桁となります。 ※詳細は「3.1 コンビニ決済 使用可能文字一覧」参照。 |
○ |
| name2 | 氏名2 | 全角20バイト以内 | 顧客名 文字列のサイズは、全角1文字を2バイトとみなした数値です。20バイトの場合は全角文字10桁となります。 ※詳細は「3.1 コンビニ決済 使用可能文字一覧」参照。 |
○ |
| telNo | 電話番号 | 半角数字13桁以内右記参照 | 顧客電話番号 数字のみは11桁以内、ハイフン含みは13桁以内 例） 0311112222、03-1111-2222、09011112222、090-1111-2222 ※econ, lawsonの場合は、電話番号8桁未満は指定不可。 ※famima, sej, otherの場合は、5桁未満は指定不可。 ※電話番号は固定値としないでください。 ※電話番号でなくても規定の桁数の数字であれば問題はありません。電話番号の設定が難しい場合は、固定値ではない数字の文字列を設定してください。 |
○ |
| payLimit | 支払期限 | 半角数字10桁 右記参照 |
YYYY/MM/DD の形式 sej ： 当日～150日後を指定可能 famima ： 当日～60日後を指定可能 lawson ： 当日～60日後を指定可能 econ ： 当日～60日後を指定可能 other ： 当日～365日後を指定可能 |
○ |
| payLimitHhmm | 支払期限時分 | 半角数字5桁 右記参照 |
HHMMまたはHH:MMの形式
※未指定の場合の期限は、期限日当日の23:59までとなります。 |
△ |
| pushUrl | プッシュURL | URLに使用可能な半角文字256桁以内 | 入金通知先URLを指定
※未指定の場合は、MAPの「各種設定変更」で設定した入金通知URLに通知されます。 |
△ |
| paymentType | 支払区分 | "0"固定 右記参照 |
※現在はリザーブパラメーターのため無条件に "0" を設定 |
○ |
| free1 | 備考1 | 文字列 詳細は右記 |
備考欄（商品詳細などに利用する） sej ： 使用不可 famima ： 任意（38バイト） lawson ： 任意（50バイト） econ ： 任意（50バイト） other ： 任意（32バイト） |
※ |
| free2 | 備考2 | 文字列 詳細は右記 |
備考欄（商品詳細などに利用する） sej ： 使用不可 famima ： 任意（38バイト） lawson ： 使用不可 econ ： 使用不可 other ： 任意（32バイト） |
※ |
応答電文 ： CvsAuthorizeResponseDto
| 応答電文 ： CvsAuthorizeResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ | 半角英数字10桁以内 | 要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード | 半角英数字32文字以内 | "success" ： 正常終了 "failure" ： 異常終了 "pending" ： 保留 |
○ |
| vResultCode | 詳細結果コード | 半角英数字16文字 | 処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ | 文字列1024 バイト以内 | 処理結果を日本語で表示します。 | ○ |
| marchTxn | 電文ID | 文字列100桁以内 | 決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。 |
○ |
| orderId | 取引ID | 半角英数字100文字以内 | 決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID | 文字列100桁以内 | 決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| receiptNo | 受付番号 | 文字列32文字以内 | 正常に決済請求が完了した際に返戻されるコンビニの受付番号 sej ： 払込票番号（13桁） 注）セブン-イレブンのレギュレーション上、払込票番号のみを消費者に案内することは、2027年12月末で禁止となります。必ず払込票URL(haraikomiUrl)を表示するようにしてください。 famima ： 企業コード（5桁）-注文番号（12桁）lawson ： 受付番号（6桁） econ ： 受付番号（6桁） other ： オンライン決済番号（11桁） |
△ |
| haraikomiUrl | 払込票URL | 半角英数字256文字以内 |
コンビニから返される払込票URL。 sej ： 消費者の利用端末PC・スマートフォンを判別して表示します。 注）表示方法については必ず、「3-3セブン-イレブンの払込票URLの表示について」をご参照下さい。 other ： PC、スマートフォンでの表示・支払に対応しています。famima ： スマートフォン用画面を表示します。 lawson ： 各コンビニでのお支払い方法を説明する画面を表示します。 econ ： 各コンビニでのお支払い方法を説明する画面を表示します。 ※lawson、econは、ご契約のタイミングによりURLが返戻されない設定になっていることがあります。返戻されない場合は、カスタマーサポート（vt-support@veritrans.jp）までご連絡ください。 |
※ |
| txnVersion | MDK バージョン | 半角英数字5桁 | 電文のバージョン ※問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
キャンセル
コンビニ決済では、支払い前の申込に対するキャンセルが可能です。
消費者がコンビニエンスストアで支払いを行った後のキャンセルはできませんのでご注意ください。
要求電文 ： CvsCancelRequestDto
| 要求電文 ： CvsCancelRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceOptionType | 決済サービスオプション | 右記参照 | 申込の要求電文で指定した値 | ○ |
| orderId | 取引ID | 半角英数字100桁以内 | 決済請求時に採番した取引ID | ○ |
応答電文 ： CvsCancelResponseDto
| 応答電文：CvsCancelResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ | 半角英数字10桁以内 | 要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード | 半角英数字32文字以内 | "success" ： 正常終了
"failure" ： 異常終了 "pending" ： 保留 | ○ |
| vResultCode | 詳細結果コード | 半角英数字16文字 | 処理の結果を詳細に表すコード
4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 | ○ |
| merrMsg | エラーメッセージ | 文字列1024バイト以内 | 処理結果を日本語で表示します。 | ○ |
| marchTxn | 電文ID | 文字列100桁以内 | 決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID
１つの取引IDに対して、複数のIDが付与されます。 | ○ |
| orderId | 取引ID | 半角英数字100文字以内 | 決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID | 文字列100桁以内 | 決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| txnVersion | MDKバージョン | 半角英数字5桁 | 電文のバージョン
問題発生時などに用いますが、通常ご利用になることはありません。 | ○ |
結果通知
結果通知電文の概要
実装方法の詳細につきましては、弊社より提供しているサンプルプログラムをご参照ください。
■ 機能概要
決済サーバーから店舗システムへ決済の結果通知を行います。
通知は、HTTPのPOSTを利用します。
※プロトコルはHTTP（Port：80）、HTTPS（Port：443）に対応しています。
処理の概要については『VeriTrans4G 開発ガイド（MDKモジュール方式）』（開発ガイド本体）をご参照ください。
■ HMACについて
POSTにてデータを通知するとき、リクエストヘッダーにHMACを設定します。
また、HMAC値は、リクエストボディから算出します。
アルゴリズムは「HmacSHA256」が設定されます。
| フィールド名 | 設定値 |
|---|---|
| content-hmac | h={アルゴリズム名};s={CCID};v={HMAC値} |
■ 結果通知受信処理結果について
決済サーバーからの通知に対して店舗側システムがHTTPステータスコード200番台を返戻した場合、受信処理が正常に終了したものと判断します。200番台以外のコードを返した場合は、受信失敗と判断し、一定期間、通知を繰り返します。
- 通常はHTTPステータスコード"200"を返戻してください。
- 規定の回数失敗した場合は、通知処理が停止しますのでご注意ください。
- 決済サーバー側で"200"もしくは200番台のコードを受信できなかった場合、通知が繰り返し送信されます。同じ通知が複数回届いた場合も受信処理が正常に行われるように実装してください。
- HTTPステータスコード200番台以外を返戻する際、HTTPリダイレクト(3xxの要求)のコードは返却しないようにしてください。3xxが返戻された場合、リダイレクト先へのアクセスが行われますが、正常にPOSTすることはできません。また、リトライも行われなくなる可能性があります。
結果通知のタイミング
コンビニ決済における結果通知電文の通知タイミングは、下記となります。
| No. | 通知機能 | 通知タイミング | 注意事項 |
|---|---|---|---|
| 1 | 入金通知 | 決済サーバーが、決済センターからの入金完了情報（消費者の支払完了情報）を受け取り、該当の入金が完了したと判断したタイミングで送信します。 | 支払期限切れの通知はありません。 |
以下に、コンビニの決済通知項目を示します。
| 項番 | フィールド名 | 項目名 | 書式・制限 | 説明 |
|---|---|---|---|---|
| 1 | numberOfNotify | 通知件数 | 半角数字4桁以内 | １回の送信に含まれる取引の件数を示します。初回の通知は必ず1件となります。 結果通知に対してHTTPステータスコード200番台が返戻されなかった場合はリトライを実施しますが、リトライ時はリトライ対象の取引を複数件まとめて送信します。 1度に通知可能な件数は50件で、51件以上の場合は次回の通知になります。 |
| 2 | pushTime | 送信時刻 | 半角数字14桁 | 決済サーバーから通知した時刻 YYYYMMDDhhmmss形式 |
| 3 | pushId | 識別ID | 半角数字8桁 | プッシュ処理を行うたびに採番されるID 注） 他の決済サービスで使用されたIDと重複する場合があります。 |
| 通知件数分下記の項番（4～9）を繰り返す。尚、フィールド名の後ろに4ケタの連番（0000～0049）を付与する。 | ||||
| 4 | orderId | 取引ID | 半角英数字100桁以内 | |
| 5 | cvsType | CVSタイプ | 半角英数字10桁以内 |
消費者が入金を行ったコンビニチェーンを示す以下の値を設定 ※上記以外のコンビニは、加盟店様のご契約内容により以下の2つのパターンに分かれます。 （パターン１） ファミリーマートとの接続形態が「直接接続」の場合 （パターン２） ファミリーマートとの接続形態が「イーコンテクスト経由接続」の場合 |
| 6 | receiptNo | 受付番号 | 半角英数字32桁以内 | |
| 7 | receiptDate | 完了日時 | 半角数字14桁 | 消費者側で支払が完了した時刻（YYYYMMDDhhmmss形式） |
| 8 | rcvAmount | 入金金額 | 半角数字6桁以内 | |
| 9 | dummy | ダミー決済フラグ | 半角数字1桁 | ダミーデータを示す場合は"1"を設定 |
- pushId（識別ID）は、他の決済サービスで使用されたIdと重複する場合がありますので、ユニークキーとして処理しないようにしてください。
- 項目の並び順は、必ずしも表の順序とは一致しません。
- 結果通知は将来的にフィールドが追加される可能性がございます。上記に定義されたフィールド名以外のフィールドが連携された場合でもエラーとならないようご注意ください。
その他 補足事項
使用可能文字一覧
コンビニ決済の下記全角項目にて、JIS基本漢字（JIS X 0208）で使用可能な文字の範囲を以下に表します。
使用可能文字の範囲外の文字を使用した場合、処理結果が正常の場合でも文字化けが発生する可能性があります。
■ 氏名1（name1）、氏名2（name2）
| 区点 | 内容 |
|---|---|
| 01区 | 長音符 ー 同の字点 々 一の字点 ヽ ヾ ゝ ゞ
ノノ字点 〃 しめ 〆 |
| 03区 | 数字・アルファベット |
| 04区 | 平仮名 |
| 05区 | カタカナ |
| 16区～47区 | 第一水準漢字 |
| 48区～84区 | 第二水準漢字 |
利用可能なコンビニタイプの確認方法
利用可能なコンビニタイプ（serviceOptionType）は、MAPのダッシュボードの「サービス利用情報」－「コンビニ」で確認することができます。
ファミリーマートとの接続形態が「直接接続」の加盟店様の場合
図中に表示されている番号は、以下のコンビニタイプ（serviceOptionType）に対応しています。
| 番号 | 表示名 | コンビニタイプ | 支払可能なコンビニエンスストア |
|---|---|---|---|
| 01 | セブンイレブン | sej | セブン-イレブン |
| 02 | ローソン・セイコーマートその他 | lawson | ローソン、ミニストップ、セイコーマート |
| 03 | ファミリーマート | famima | ファミリーマート |
| 04 | デイリーヤマザキ | other | デイリーヤマザキ、ヤマザキデイリーストア |
ファミリーマートとの接続形態が「イーコンテクスト経由接続」の加盟店様の場合
図中に表示されている番号は、以下のコンビニタイプ（serviceOptionType）に対応しています。
| 番号 | 表示名 | コンビニタイプ | 支払可能なコンビニエンスストア |
|---|---|---|---|
| 01 | セブンイレブン | sej | セブン-イレブン |
| 04 | デイリーヤマザキ | other | デイリーヤマザキ、ヤマザキデイリーストア |
| 05 | ローソン・ファミリーマートその他 | econ | ローソン、ファミリーマート、ミニストップ、セイコーマート |
セブン-イレブンの払込票URLの表示について
セブン-イレブンが発行する払込票URL（haraikomiUrl）へのアクセス時には、レスポンスヘッダーに以下の値が設定されます。
- X-Frame-Options: SAMEORIGIN
- Content-Security-Policy: frame-ancestors 'self'
- Pragma: no-cache
- Cache-Control: no-cache
このため、サイト内のiframe等による埋め込みはブラウザ側でブロックされ、払込票を表示することができません。
必ず新しいウインドウや別タブ（window.open）で開くか、直接リンクを表示して画面遷移させるように実装してください。
（レスポンスヘッダーに関する補足説明）
X-Frame-Options: SAMEORIGIN
このヘッダーは、クリックジャッキング攻撃を防ぐために、ウェブページが<frame> <iframe> <embed>または<object>タグ内で表示されるのを制御します。
SAMEORIGINが設定されている場合、異なるドメインからの正規のフレーム埋め込みも制限されます。
Content-Security-Policy: frame-ancestors 'self'
クリックジャッキングやその他のクロスサイトスクリプティング（XSS）攻撃を防ぐために、どの親ソースがページを埋め込めるかを制御します。
frame-ancestors 'self'は、X-Frame-Options: SAMEORIGINと同様に、ページが自身のオリジンからのページによってのみ埋め込まれるようにします。