VeriTrans4G エポスかんたん決済ご利用ガイド

VeriTrans4G 開発ガイド別冊
エポスかんたん決済ご利用ガイド
Ver. 1.0.1 （2023 年 09 月～）

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

VeriTrans4G エポスかんたん決済ご利用ガイド

目次
第1章

本ガイドの内容 ..................................................................................................................................... 2

本ガイドの内容 ............................................................................................................................................................ 2
著作権、および問い合わせ先 ....................................................................................................................................... 2
改訂履歴 ..................................................................................................................................................................... 2第2章

概要...................................................................................................................................................... 3

第3章

MDK の処理概要................................................................................................................................... 4

機能一覧（決済要求コマンド） ....................................................................................................................................... 4
決済処理シーケンス..................................................................................................................................................... 5第4章

結果通知受信処理 ................................................................................................................................ 7

結果通知受信処理の対象 ............................................................................................................................................ 7

第5章

インターフェイス詳細 ............................................................................................................................. 8

エポスかんたん決済 .................................................................................................................................................... 8
決済申込 ................................................................................................................................................................................... 8
消費者ブラウザから店舗側の完了画面へリダイレクトする時のクエリパラメータ .............................................................................. 9
売上 .........................................................................................................................................................................................11
キャンセル ............................................................................................................................................................................... 12

共通 .......................................................................................................................................................................... 13
検索 ........................................................................................................................................................................................ 13

結果通知電文............................................................................................................................................................ 17
結果通知電文の概要 ............................................................................................................................................................... 17
エポスかんたん決済の結果通知電文 ........................................................................................................................................ 18

第6章

その他 補足事項 ............................................................................................................................... 19

売上およびキャンセルに関する注意事項 .................................................................................................................... 19
売上およびキャンセルの要求可能期間...................................................................................................................................... 19
部分売上の実現方法および部分キャンセルに関する注意事項 ................................................................................................... 19

エポスのクーポンやポイントを利用した決済に関する注意点 ........................................................................................ 19
検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態） ................................................................... 19
ペンディングが発生した取引に関する補足 .................................................................................................................. 20

第7章

導入・テストに関する補足 .................................................................................................................... 21

決済申込時のエラーをシミュレートする ....................................................................................................................... 21
売上・キャンセル時のエラーをシミュレートする ............................................................................................................ 23

1

VeriTrans4G エポスかんたん決済ご利用ガイド

第1章 本ガイドの内容
本ガイドの内容
本ガイドは、株式会社 DG フィナンシャルテクノロジーが提供する VeriTrans4G の「エポスかんたん決済」をインターネット店舗等でご利用頂くため、専用ソフトウェア MDK（Merchant Development Kit）を導入する開発者向けのガイドです。

著作権、および問い合わせ先[著作権]
本ドキュメントの著作権は株式会社 DG フィナンシャルテクノロジーが保有しています。
Copyright © 2023 DG Financial Technology, Inc., a Digital Garage company. All rights reserved.
[お問い合わせ先]株式会社 DG フィナンシャルテクノロジー ベリトランス テクニカルサポート
電子メール：

tech-support@veritrans.jp

改訂履歴2020/12 ：Ver1.0.0 リリース
2023/09 ：Ver1.0.1 リリース
社名変更
3-2 決済処理シーケンス 【エポスかんたん決済：決済申込時の処理】「4.申込結果通知」を「4.決済結果通知」に修正「4.決済結果通知」と「6.決済結果通知」の部分に説明を追加
決済結果通知(PUSH)の受信を必須とするよう修正
5.1.2 消費者ブラウザから店舗側の完了画面へリダイレクトする時のクエリパラメータ
結果通知取得の重要性を追記「この改ざんチェックは必須ではありませんが」の「必須ではありませんが」を削除
5.3.2 エポスかんたん決済の結果通知電文
結果通知取得の重要性を追記
通知タイミングが２つという記載を削除「5 txnType」 の説明 「決済申込完了通知」を「決済結果通知」に修正

2

VeriTrans4G エポスかんたん決済ご利用ガイド

第2章 概要エポスかんたん決済は、加盟店様のサイトで購入された商品の代金をエポス Net のアカウントを利用して決済できるサービスです。



エポス Net の ID・パスワードだけの簡単な支払い方法です。



カード番号や有効期限を入力しなくてもお買い物が可能です。

決済の画面遷移のイメージを以下に示します。

3

VeriTrans4G エポスかんたん決済ご利用ガイド

第3章 MDK の処理概要
機能一覧（決済要求コマンド）
使用可能な決済要求コマンドを下記表に示します。
決済要求種類/コマンド
決済申込 （与信）/Authorize
決済申込 （与信＋売上）/Authorize
売上/Capture
キャンセル/Cancel

概要
決済の申込（オーソリ※１）を要求します。
決済の申込（オーソリ）と売上を同時に要求します。
申込済み取引の売上確定を要求します。
全額売上のみとなります※２。
決済をキャンセルします。
決済金額を超えない範囲で、キャンセル金額を指定できます（部分キャンセル）※2。
表 1 使用可能なコマンド一覧※１ 申込（与信または与信＋売上）の際には、消費者のエポス Net の ID に紐づいたクレジットカードで与信（オーソリ）取得が行われます。
※２ 部分売上の実現方法・部分キャンセルをご利用の際は、必ず「6.1.2 部分売上の実現方法および部分キャンセルに関する注意事項」をご参照ください。

4

VeriTrans4G エポスかんたん決済ご利用ガイド

決済処理シーケンス【エポスかんたん決済：決済申込時の処理】

図 3-2-1 MDK 利用時システム処理概要図（エポスかんたん決済 決済申込）

No.

基本機能

処理説明

1

決済申込要求EC サイト上の決済導入部に渡された決済申込情報を電文化し、決済サーバーに送信します。

2

結果応答の受信

決済サーバーから返戻された結果を受信します。結果が決済可能の場合、「3. リダイレクト指示」を実施します。消費者ブラウザに返す情報(※1)は決済サーバーより返戻された結果に含まれます。

3

リダイレクト指示

決済サーバーにより返戻された情報を用いて、消費者ブラウザにエポスかんたん決済のログイン画面へのリダイレクト指示を送信します。

5VeriTrans4G エポスかんたん決済ご利用ガイド
4

決済結果通知(PUSH)

この通知は、決済申込により与信が成功した場合のみ通知されます(※2)。
決済サーバーから PUSH 通知先 URL に POST で通知しますので、決済結果を受け取り、注文データ等に反映します。
確実に決済結果が取得できるように必ず決済結果通知（PUSH）を受信してください。

5

完了画面要求消費者ブラウザから結果を受信し、完了画面を送信します(※2)。

6

決済結果通知(PUSH)

消費者側の状況により通信断や誤ってブラウザを閉じる、といったケースでエポスからのリダイ
レクト(完了処理要求)が発生しなかった場合、決済サーバー側の処理で決済結果を確認しPUSH 送信を行います。
確実に決済結果が取得できるように必ず決済結果通知（PUSH）を受信してください。

※1 Form を Submit(POST)する HTML コンテンツが返戻されます。HTML コンテンツには、Form を自動 Submit する JavaScript が含まれていますので、そのまま消費者に送信すれば（JavaScript を利用可能な端末では）自動で画面遷移します。
※2 消費者側の状況により通信断や誤ってブラウザを閉じる、といったケースではこのシーケンスは発生しません。

【エポスかんたん決済：売上要求時の処理】

図 3-2-2 MDK 利用時システム処理概要図（エポスかんたん決済 売上要求）

No.

基本機能

処理説明

1

売上要求

売上の対象となる取引情報を電文化し、決済サーバーに送信します。

2

結果応答

決済サーバーより結果応答を受信します。

【エポスかんたん決済：キャンセル要求時の処理】

図 3-2-3 MDK 利用時システム処理概要図（エポスかんたん決済 キャンセル要求）

No.
1

基本機能
キャンセル要求

処理説明
キャンセルの対象となる取引情報を電文化し、決済サーバーに送信します。
部分キャンセルは決済金額が 0 円になるまで繰り返し実施可能です。

2

結果応答

決済サーバーより結果応答を受信します。

6

VeriTrans4G エポスかんたん決済ご利用ガイド

第4章 結果通知受信処理
結果通知受信処理の対象
エポスかんたん決済の結果通知受信処理の対象は以下の機能です。

決済サービス名
エポスかんたん決済

決済申込（与信/与信売上）
○

売上

キャンセル

－

－

表 2 通知対象一覧

通信電文仕様（共通部）および店舗受信後応答仕様は、『開発ガイド』をご参照ください。
エポスかんたん決済固有の通知電文インターフェイスにつきましては、「5.3.2 エポスかんたん決済の結果通知電文」をご参照ください。

7

VeriTrans4G エポスかんたん決済ご利用ガイド

第5章 インターフェイス詳細
ここではエポスかんたん決済サービスで利用する MDK インターフェイス項目を説明します。

■「設定」欄の内容は以下の通りです。
要求電文 … 必須項目：○

任意項目：△

設定不可：×

応答電文 … 必ず返戻：○

処理成功時のみ返戻：△

その他条件付：※ （条件は説明欄、または欄外に記入）

返戻なし：×

その他条件付：※■orderId（取引 ID）について店舗で任意に採番してください。申込処理毎に付ける必要があります。他の取引 ID と重複しないよう採番してください。他決済サービスとも重複できません。
また、テスト取引で使用した取引 ID を、本番取引で再度使用することはできません。
取引 ID には、半角英数字以外に“-”（ハイフン）、“_”（アンダースコア）も使用可能です。

エポスかんたん決済
決済申込
要求電文 ： EposAuthorizeRequestDto
フィールド名

項目名

書式・制限

説明

設
定

半角英数字
100 桁以内
半角数字
1 桁－8 桁

店舗側で採番した取引 ID を指定○

決済金額（合計金額）を指定

○

売上フラグ

右記参照

△

customerId

加盟店顧客 ID

半角英数字記号32 バイト以内"true"： 与信・売上"false"： 与信のみ （デフォルト値）※ 指定が無い場合は、与信のみとなります。
店舗側サイトにて該当顧客を一意に識別する ID。
以下の記号が使用可能です。
“.”(ピリオド)、“,”(カンマ)、“/”(スラッシュ)、“:”(コロン)、“_”(アンダースコア)、“?”(疑問符)、“&”(アンパサンド)、“#”(シャープ)、“%”(パーセント)、“=”(イコール)、”-“(ハイフン)

successUrl

決済完了時 URL

URL に使用可能な
半角文字
256 桁以内

決済成功時に、店舗側サイトに画面遷移を戻すための URL を指定（クエリパラメータ指定可）※未指定の場合は、MAP（Merchant Administrator Portal）から登録申請した値を使用※本パラメータ、もしくは MAP からの登録が必須となります。

△

cancelUrl

決済キャンセル時URL

URL に使用可能な
半角文字
256 桁以内

決済成功時に、店舗側サイトに画面遷移を戻すための URL を指定（クエリパラメータ指定可）※未指定の場合は、MAP（Merchant Administrator Portal）から登録申請した値を使用※本パラメータ、もしくは MAP からの登録が必須となります。

△

errorUrl

決済エラー時 URL

URL に使用可能な
半角文字
256 桁以内

決済エラー時に、店舗側サイトに画面遷移を戻すための URL を指定（クエリパラメータ指定可）※未指定の場合は、MAP（Merchant Administrator Portal）から登録申請した値を使用※本パラメータ、もしくは MAP からの登録が必須となります。

△

orderId

取引 ID

amount

決済金額

withCapture○8VeriTrans4G エポスかんたん決済ご利用ガイド
pushUrl

プッシュ URL

URL に使用可能な
半角文字
256 桁以内

プッシュ URL を指定（クエリパラメータ指定可）※未指定の場合は、MAP（Merchant Administrator Portal）から登録申請した値を使用※本パラメータ、もしくは MAP からの登録が必須となります。

△

応答電文 ： EposAuthorizeResponseDto
フィールド名

項目名

書式・制限

説明

設
定

serviceType

決済サービスタイプ

半角英数字
10 桁以内要求電文を送信した決済サービスタイプ○

mstatus

処理結果コード

半角英数字
32 文字以内"success"：正常終了"failure"：異常終了○

vResultCode

詳細結果コード

半角英数字
16 文字

○

merrMsg

エラーメッセージ

marchTxn

電文 ID

文字列
1024 バイト以内
文字列
100 桁以内

処理の結果を詳細に表すコード
4 桁ずつ 4 つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。
詳細は『結果コード一覧』を参照下さい。
処理結果を日本語で表示します。

○

orderId

取引 ID

決済サーバーにて決済処理電文（内部処理も含む）毎に付与する ID
１つの取引 ID に対して、複数の ID が付与されます。
決済要求時に店舗様にて任意に採番し送信された取引 ID

custTxn

取引毎に付く ID

決済サーバーがオーダー（取引 ID）と紐付ける為に採番する
ID○

txnVersion

MDK バージョン

半角英数字 5 桁○

responseContents

レスポンス
コンテンツ

文字列

電文のバージョン問題発生時などに用いますが、通常ご利用になることはありません。
決済申込み成功時に返戻される、店舗様側でコンシューマに対して返戻する HTML コンテンツ。
自動でエポスが提供するページに遷移するための JavaScriptを含みますので、そのままの内容を消費者のブラウザに返戻するようにしてください。このとき、コンテンツの文字コードは
必ず Shift_JIS に設定してください。

半角英数字
100 文字以内
文字列
100 桁以内○○※

消費者ブラウザから店舗側の完了画面へリダイレクトする時のクエリパラメータ
リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(GET)される内容
フィールド名

項目名

書式・制限

説明

設
定

mstatus

処理結果コード

半角英数字
32 文字以内"success" ：正常終了"failure" ：異常終了○

vResultCode

詳細結果コード

半角英数 16 桁○

orderId

取引 ID

半角英数字 100 文字以内

処理の結果を詳細に表すコード
4 桁ずつ 4 つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。
詳細は『結果コード一覧』を参照下さい。
決済要求時に店舗様にて任意に採番し送信された取引 ID

txnType

トランザクション
タイプ

文字列
右記参照

通知対象となるトランザクションのタイプが設定されます。
"Authorize"○

eposOrderId

エポス取引 ID

半角英数字 13 文字

エポス側で取引を一意に表す ID

○

○

9

VeriTrans4G エポスかんたん決済ご利用ガイド
useCredit

クレジット利用額

半角数字
1 桁－8 桁

消費者がエポスの画面で入力したクレジット利用額△

useCoupon

クーポン利用額

半角数字
1 桁－8 桁

消費者がエポスの画面で入力したクーポン利用額△

usePoint

ポイント利用額

半角数字
1 桁－8 桁

消費者がエポスの画面で入力したポイント利用額△

vAuthInfo

改ざんチェック
用
ハッシュ値

文字列
右記参照

○

authParams

ハッシュ値算出
パラメータ順序

文字列
右記参照

下記文字列を連結し、SHA-256 によって算出したハッシュ値
・マーチャント CCID
・パラメータ値の連結文字列（authParams が示す順序で連結）・パスワード尚、パラメータ値を連結する際は、パラメータ名や区切り文字は含めず、パラメータ値のみを連結しています。連結した文字列をバイナリに変換する際の文字エンコーディングは、UTF-8 を使用
しています。
vAuthInfo のハッシュ値を算出する元とした文字列の、パラメータの連結順序を示す値
パラメータ名のカンマ区切り文字列を Base64 エンコードしています。デコードを行うと文字列が復元されます。
例)"orderId,vResultCode,mstatus""mstatus,orderId,vResultCode"（順不同のため、リクエスト受信の度に動的に処理して下さい。）

○

（重要）


これらのパラメータはブラウザを経由して連携されるため、画面遷移が正常に行われないケースでは取得することができません。
そのため、決済サーバーから直接送信される「5-3 結果通知電文」の受信と組み合わせて確実に結果を取得するようにしてください。

vAuthInfo および authParams を利用した改ざんチェックについて
決済サーバーから消費者ブラウザを経由して店舗側の結果画面に遷移（リダイレクト）しますが、ここで店舗側システムが受け取ったクエリパラメータが改ざんされていないことを検証するためのパラメータが、vAuthInfo と authParams です。
店舗側システムで算出したハッシュ値が、クエリパラメータより取得した vAuthInfo と一致している場合は、パラメータは改ざんされていない、とみなすことができます。
この改ざんチェックは、悪意を持った第三者によって、不正なリダイレクト電文を受信する可能性がありますので、実装を強く推奨しています。
実装方法の詳細につきましては、弊社より提供しているサンプルプログラムをご参照ください。

10VeriTrans4G エポスかんたん決済ご利用ガイド

売上要求電文 ： EposCaptureRequestDto
フィールド名orderId

項目名
取引 ID

書式・制限
半角英数字
100 桁以内

説明
売上対象の取引 ID を指定

設
定○

応答電文 ： EposCaptureResponseDto
フィールド名

項目名

書式・制限

説明

設
定

serviceType

決済サービスタイプ

半角英数字
10 桁以内要求電文を送信した決済サービスタイプ○

mstatus

処理結果コード

半角英数字
32 文字以内"success"：正常終了"failure"：異常終了"pending"：保留○vResultCode

詳細結果コード

半角英数字
16 文字

○

merrMsg

エラーメッセージ

文字列1024 バイト以内

4 桁ずつ 4 つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。
詳細は『結果コード一覧』を参照下さい。
処理結果を日本語で表示します。

marchTxn

電文 ID

文字列
100 桁以内○

orderId

取引 ID

半角英数字
100 文字以内

決済サーバーにて決済処理電文（内部処理も含む）毎に付与する ID
１つの取引 ID に対して、複数の ID が付与されます。
決済要求時に店舗様にて任意に採番し送信された取引 ID

custTxn

取引毎に付く ID

文字列
100 桁以内

決済サーバーがオーダー（取引 ID）と紐付ける為に採番する
ID○

txnVersion

MDK バージョン

半角英数字 5 桁

電文のバージョン問題発生時などに用いますが、通常ご利用になることはあり
ません。

○

○

○

11

VeriTrans4G エポスかんたん決済ご利用ガイド

キャンセル
要求電文 ： EposCancelRequestDto
フィールド名

項目名

orderId

取引 ID

amount

減額金額

書式・制限
半角英数字
100 桁以内
半角数字
1 桁－8 桁説明

設定

上記「orderId（取引 ID）について」参照○

減額する金額を指定。
※売上(与信同時売上)実施後の場合、指定できる金額は”消費者がエポスの画面で入力したクレジット利用額”まで、もしくは全額になります。
※未指定時は全額キャンセルとなります。

△

応答電文 ： EposCancelResponseDto
フィールド名

項目名

書式・制限

説明

設
定

serviceType

決済サービスタイプ

半角英数字
10 桁以内要求電文を送信した決済サービスタイプ○

mstatus

処理結果コード

半角英数字
32 文字以内"success"：正常終了"failure"：異常終了"pending"：保留○vResultCode

詳細結果コード

半角英数字
16 文字

○

merrMsg

エラーメッセージ

marchTxn

電文 ID

文字列
1024 バイト以内
文字列
100 桁以内

処理の結果を詳細に表すコード
4 桁ずつ 4 つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。
詳細は『結果コード一覧』を参照下さい。
処理結果を日本語で表示します。

○

orderId

取引 ID

決済サーバーにて決済処理電文（内部処理も含む）毎に付与する ID
１つの取引 ID に対して、複数の ID が付与されます。
決済要求時に店舗様にて任意に採番し送信された取引 ID

custTxn

取引毎に付く ID

決済サーバーがオーダー（取引 ID）と紐付ける為に採番する
ID○

txnVersion

MDK バージョン

半角英数字 5 桁○

balance残高

半角数字
1 桁－8 桁

電文のバージョン問題発生時などに用いますが、通常ご利用になることはありません。
現在の決済金額

useCredit

クレジット利用額

半角数字
1 桁－8 桁

クレジット利用額※全額キャンセルの場合は 0 を返します。

※

useCoupon

クーポン利用額

半角数字
1 桁－8 桁クーポン利用額※全額キャンセルの場合は 0 を返します。

※

usePoint

ポイント利用額

半角数字
1 桁－8 桁ポイント利用額※全額キャンセルの場合は 0 を返します。

※

半角英数字
100 文字以内
文字列
100 桁以内○○△※成功時のみ返戻する項目ですが、決済センターの処理により、成功時でも返戻されない場合があります。

12VeriTrans4G エポスかんたん決済ご利用ガイド

共通
検索■「設定」欄の内容は以下の通りとなります。
要求電文 … 必須項目：○

任意項目：△

設定不可：×

応答電文 … 必ず返戻：○

該当取引存在時に返戻：△

その他条件付：※（条件は説明欄に記入）
返戻なし：×

その他条件付：※■複数指定は 0～の添字を指定します。
例）exparam.serviceTypeCd[0]=card&exparam.serviceTypeCd[1]=rakuten■ワイルドカードは値の一部と"*"を組み合わせて検索します。"*"のみの指定はできません。
例）exparam.searchParameters.common.orderId=123*■通常の検索の他、マスタ情報取得が可能です。マスタ情報取得時のインターフェイスは後記します。

要求電文 ： SearchRequestDto※ 以下は、共通の検索要求フィールドです。

検索フィールド名
requestId

検索項目名
リクエスト ID

serviceTypeCd

決済サービスタイプ

書式・制限

複数

ﾜｲﾙﾄﾞ

指定

ｶｰﾄﾞ

説明

半角英数字記号 128

リクエスト ID を指定します。指定した場合は、そ

文字以内

れ以外のパラメータは指定できなくなります。

右記参照

○

検索対象の決済を指定します。未指定の場合

設
定

△

△

は、全決済が検索対象となります。
"rakuten"： エポスかんたん決済
newerFlag

最新トランザクショ

右記参照

成功、失敗に関係なく、最新トランザクションの

ンフラグ

△

みを検索する場合に使用します。
"true"： 1 取引内の最新トランザクションのみ検索"false"： 全てのトランザクションを検索※指定しない場合は"false"になります。

containDummyFla

ダミー決済対象フラ

g

グ

右記参照

ダミー取引も検索する場合に使用します。

△"true"： ダミー取引も検索する"false"： ダミー取引は検索しない※指定しない場合は"false"になります。

maxCount

検索最大件数

1～1000

取得したい検索結果の最大件数です。未指定△の場合、最大値となります。
※短時間で大量の検索を繰り返すような処理はサーバに負荷が掛かりますのでご遠慮頂けますようお願いします。

commonorderId

共通
取引 ID

半角英数字 100 桁以○

検索したい取引 ID を指定します。

△

内
13

VeriTrans4G エポスかんたん決済ご利用ガイド
orderStatus

取引決済状態

右記参照○

以下のいずれかを指定します。

△" initial "：初期状態" end "：終了
" end_presentation "：画面遷移正常終了" pending "：保留" validation_error "：検証エラー" expired "：期限切れ" error "：エラー
command

コマンド

右記参照

○

決済で使用するコマンドを指定します。

△" Authorize "：決済申込" Capture "：売上
" Cancel "：キャンセル

mstatusステータスコード

右記参照○

決済結果として返戻されるステータスコードを指

△

定します。
" success "：成功" failure "：失敗
" pending "：保留txnDatetime.fr

取引日（From）

文字列 12 桁

取引日時の範囲（From）を指定します。

om△

YYYYMMDDhhmm 形式

txnDatetime.t

取引日（To）

文字列 12 桁

取引日時の範囲（To）を指定します。

o△

YYYYMMDDhhmm 形式

amount.from

金額（From）

数字 12 桁以内

決済金額の範囲（From）を指定します。

△

amount.to

金額（To）

数字 12 桁以内

決済金額の範囲（To）を指定します。

△※「detailOrderType」の詳細については、「6-3△※ 以下は、エポスかんたん決済固有の検索要求フィールドです。

epos

エポスかんたん決済

detailOrderTy

詳細オーダー決済

pe

状態

detailComman

詳細コマンドタイプ

右記参照○

検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）」を参照
右記参照

dType

○

※「detailCommandType」の詳細については、△「6-3 検索（Search）に関する補足（詳細コマンド
タイプ/詳細オーダー決済状態）」を参照

eposOrdeId

エポス取引 ID

半角英数字 13 文字

エポス側で取引を一意に表す ID△

14

VeriTrans4G エポスかんたん決済ご利用ガイド

応答電文 ： SearchResponseDto※ 以下は、共通の検索結果フィールドです。

検索フィールド名
result

検索項目名

書式・制限

説明

設
定

○
○

処理結果

－

serviceType

サービスタイプ

右記参照"search"mstatus

処理結果コード

半角英数字 32 文字処理の結果ステータスが格納されます。
“success”：正常終了“failure”：異常終了○以内
半角英数字 16 文字処理の結果を詳細に表すコードとなります。

○

vResultCode

詳細結果コード

詳細は『結果コード一覧』を参照下さい。

overMaxCountFlag

最大件数超えフラ

右記参照

グ
searchCount

検索結果件数orderInfos

オーダー情報リスト

orderInfo

オーダー情報検索対象データが要求電文で指定した検索最大件△数より多いかどうかを表します。
"true"： 最大件数以上 "false"： 最大件数未満
0～1000

検索結果件数（オーダー件数）が格納されます。
複数のオーダー情報（orderInfo）が格納されます。

－

検索条件に該当した取引の情報が該当件数分繰り△△△返されます。0～1000 件（要求電文で指定した検索
最大件数まで）となります。

△
△

index

インデックス

0～999

検索された情報のインデックスが格納されます。

serviceTypeCd

決済サービスタイプ

右記参照

決済の種類が格納されます。
"rakuten"： エポスかんたん決済

orderId

取引 ID

文字列

取引の取引 ID が格納されます。

△

orderStatus

取引決済状態

右記参照

決済の状態が格納されます。
" initial "：初期状態" end "：終了
" end_presentation "：画面遷移正常終了" pending "：保留" validation_error "：検証エラー" expired "：期限切れ" error "：エラー△※このフィールドは、取引 ID に関連する注文データの状態を完全に表現するものではありません。サービスタイプによっては詳細な状態遷移を別のフィールドに保持している場合がありますので、店舗側システムの用途に合わせて
successDetailTxnType や、決済固有の状態フィー
ルドをご参照ください。
lastSuccessTxnType

最終成功トランザク

文字列

直近の成功したコマンド名が格納されます。

△

文字列

取引の詳細な状態が格納されます。

△

ションタイプsuccessDetailTxnType

詳細トランザクショ
ンタイプ

properOrderInfo

固有オーダー情報

検索要求電文の各決済の detailOrderType 参照。
－

各決済サービスの固有オーダー情報が格納されま△す。後述の一覧参照。
transactionInfos

決済トランザクショ
ンリスト－

複数の決済トランザクション情報（transactionInfo）△

が格納されます。
15

VeriTrans4G エポスかんたん決済ご利用ガイド
transactionInfo

決済トランザクショ－

検索条件に該当した取引の情報が該当件数分繰り

ン情報
txnId

トランザクション管△返されます。
文字列

決済サーバーが採番する管理 ID となります。

△

文字列

実行されたコマンド名が格納されます。

△

理 IDcommand

コマンド※MDK で要求したコマンドだけでなく、決済サーバ
ーの内部処理コマンドも含まれます。
mstatus

処理結果コード

半角英数字 32 文字以内

処理の結果ステータスが格納されます。
“success”：正常終了“failure”：異常終了△“pending”：保留vResultCode

詳細結果コード

文字列 16 桁

処理の結果を詳細に表すコードとなります。

△

詳細は『結果コード一覧』を参照下さい。
txnDatetime

取引日時

文字列 23 桁

取引日時が格納されます。

△

YYYY-MM-DD hh:mi:ss.mmm 形式
amount金額

半角数字 12 桁以内決済した金額が格納されます。

properTransacti

固有トランザクショ－

各決済サービスの固有トランザクション情報が格納

onInfoン情報△△されます。後述の一覧参照。

☆ 以下の情報は、上記 「固有オーダー情報」 「固有トランザクション情報」 内の階層にセットされます。
※ 以下は、エポスかんたん決済固有の検索結果フィールドです。
properOrderInfo

エポスかんたん決済 固有オーダー情報

与信同時売上フラグ

withCapture

文字列

決済申込時に指定した与信同時売上フラグ

申込金額

authorizeAmount

半角数字 8 桁

決済申込時に指定した金額

△
△

残高

balance

残高（現在の決済金額）△

決済申込日時authorizeDatetime

決済申込日時△以内
半角数字 8 桁以内
文字列 14 桁

YYYYMMDDhhmmss 形式
エポス取引 ID

eposOrderId

半角英数字 13エポス側で取引を一意に表す ID△

クレジット利用額△

クーポン利用額△

ポイント利用額△※「detailCommandType」の詳細については、「6-3△文字
クレジット利用額

useCredit

半角数字
1 桁－8 桁クーポン利用額

useCoupon

半角数字
1 桁－8 桁ポイント利用額

usePoint

半角数字
1 桁－8 桁

properTransactionInfo
詳細コマンドタイプ

エポスかんたん決済 固有トランザクション情報
detailCommandType

文字列

検索（Search）に関する補足（詳細コマンドタイプ/
詳細オーダー決済状態）」を参照
クレジット利用額

useCredit

半角数字

クレジット利用額△

クーポン利用額△

ポイント利用額△

エポスへの要求日時が格納されます。

△

1 桁－8 桁クーポン利用額

useCoupon

半角数字
1 桁－8 桁ポイント利用額

usePoint

半角数字
1 桁－8 桁エポスへの要求日時

eposRequestDatetime

文字列 14 文字

YYYYMMDDhhmmss 形式
エポスからの返戻日時

eposResponseDatetime

文字列 14 文字

エポスからの返戻日時が格納されます。

△

YYYYMMDDhhmmss 形式

16

VeriTrans4G エポスかんたん決済ご利用ガイド

結果通知電文
結果通知電文の概要
実装方法の詳細につきましては、弊社より提供しているサンプルプログラムをご参照ください。



機能概要

決済サーバーから店舗システムへ決済の結果通知を行います。
通知は、HTTP の POST を利用します。
※ プロトコルは HTTP（Port：80）、HTTPS（Port：443）に対応しています。
処理の概要については「第 4 章 結果通知受信処理」をご参照ください。

HMAC について

POST にてデータを通知するとき、リクエストヘッダーに HMAC を設定します。
また、HMAC 値は、リクエストボディから算出します。
アルゴリズムは「HmacSHA256」が設定されます。
フィールド名content-hmac

設定値
h={アルゴリズム名};s={CCID};v={HMAC 値}
表 3 リクエストヘッダーに設定する HMAC フィールド

結果通知受信処理結果について

決済サーバーからの通知に対して店舗側システムが HTTP ステータスコード"200"を返戻した場合、受信処理が正常に終了したものと判断します。"200"以外のコードを返した場合は、受信失敗と判断し、一定期間、通知を繰り返します。
※

規定の回数失敗した場合は、通知処理が停止しますのでご注意ください。

17

VeriTrans4G エポスかんたん決済ご利用ガイド

エポスかんたん決済の結果通知電文
エポスかんたん決済では、決済が成立しているのにもかかわらず、消費者が画面遷移の途中で離脱した場合や、通信環境の問題
で画面遷移時にタイムアウトが発生した場合など、最終遷移先まで到達しない場合があります。
このような場合にも、決済サーバーからの通知を店舗側システムで受信して頂くことで、決済が成立したことを検知することができます。必ず結果通知を受信してください。

No.
1

通知種類
決済結果通知（Authorize）

通知タイミング
決済申込が成立（成功）したタイミングで送信
されます。

注意事項
決済申込が失敗した場合は送信されません。

表 4 エポスかんたん決済の結果通知一覧

以下に、エポスかんたん決済の結果通知項目を示します。

項

フィールド名

番

項目名

書式・制限

1

numberOfNotify

通知件数

半角数字 4 桁以内

2

pushTime

送信時刻

半角数字 14 桁

説明
1 度に通知可能な件数は 100 件、
101 件以上は次回通知
ゲートウェイから通知した時刻
yyyyMMddHHmmss 形式
プッシュ処理を行うたびに採番される ID。

3

pushId

識別 ID

半角数字 8 桁

注） 他の決済サービスで使用された ID と重複する場合があります。

通知件数分下記の項番（4～13）を繰り返す。尚、フィールド名の後ろに 4 ケタの連番（0000～0999）を付与する。

4

orderId

取引 ID

半角英数字 100 桁以内

取引 ID

5

txnType

トランザクションタイプ

※右記の説明を参照"Authorize"：決済結果通知

6

txnTime

処理日時

半角数字 14 桁

yyyyMMddHHmmss 形式

7vResultCode

詳細結果コード

半角英数字 16 桁処理の結果を詳細に表すコード
4 桁ずつ 4 つのブロックで構成され、各ブロック
でサービス毎の処理結果を表します。
詳細は『結果コード一覧』を参照下さい。
"success "：正常終了

8mstatus

処理ステータス

半角英数字 8 桁以内

9eposOrderId

エポス取引 ID

半角英数字 13 文字

エポス側で取引を一意に表す ID

クレジット利用額

半角数字

消費者がエポスの画面で入力したクレジット利

1 桁－8 桁用額

半角数字

消費者がエポスの画面で入力したクーポン利用

1 桁－8 桁額

半角数字

消費者がエポスの画面で入力したポイント利用

1 桁－8 桁額

半角数字 1 桁

ダミー取引を示す場合は"1"を設定する。

10
11
12
13

useCredit
useCoupon
usePoint
dummy

クーポン利用額
ポイント利用額
ダミー決済フラグ"failure"：異常終了（注意事項）


pushId（識別 ID）は、他の決済サービスで使用された Id と重複する場合がありますので、ユニークキーとして処理しないようにしてください。



項目の並び順は、必ずしも表の順序とは一致しません。

18

VeriTrans4G エポスかんたん決済ご利用ガイド

第6章 その他 補足事項
売上およびキャンセルに関する注意事項
売上およびキャンセルの要求可能期間
エポスかんたん決済における、売上およびキャンセルの要求可能期間を下表に示します。
要求種類

要求可能期間売上

決済申込日（与信日）から 180 日間

キャンセル

売上前： 決済申込日（与信日）から 180 日間
売上後： 決済サーバーで取引データを保持している間
表 3 売上およびキャンセルの要求可能期間■ 売上・キャンセル時の注意点
決済申込は、最終の処理結果が反映されるまで時間がかかりますので、後続コマンドを実施する際は時間をおいてから実施してください。処理結果が反映される前にコマンドが実施されるとエラーが返戻されます。

部分売上の実現方法および部分キャンセルに関する注意事項■ 部分売上

売上コマンドで、部分売上（与信額と異なる金額で売上）は実施できません。与信で確保した金額のうち一部を売り上げたい場合は、売上コマンドの実施前に（与信の）部分キャンセルを実施し、金額を変更してから売上コマンドを実施することで実現可能です。売上コマンド実施後に再度売上コマンドを実施することはできません。

■ 部分キャンセル


与信後の売上および与信同時売上後の部分キャンセルについては、クレジット利用額を超える値はキャンセルできません（クーポンやポ
イントで決済された金額分のキャンセルはできません）。売上金額を超えない範囲で、キャンセル金額を指定できます。

エポスのクーポンやポイントを利用した決済に関する注意点
エポスのポイントやクーポンを利用した決済では、消費者がエポスかんたん決済の購入画面で利用額を設定します。
以下に、エポスのポイントを利用した決済についての注意点を示します。


与信後の売上および与信同時売上後の部分キャンセルを実施する際に、クレジット利用額を超える値を指定するとエラーとなります。

検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）
管理サーバーでは、エポスかんたん決済のシステム内部データとして詳細コマンド（処理要求の種類）と詳細な決済状態（その取引がどのような状態にあるか）を管理しています。
通常の運用では、店舗様システムではこれらの内部情報を利用する必要はありませんが、店舗様システムにおいて取引の状態検索が必要なケースや、障害等のお問い合わせ時の参照情報として、これらの内部データを Search コマンドで公開しています。
下表に Search コマンドにて利用可能な内部データの一覧を示します。

19

VeriTrans4G エポスかんたん決済ご利用ガイド
詳細コマンドタイプ
論理名

コマンド成功時の詳細オーダー決済状態
値

論理名

値

与信準備

ReadyAuth

与信準備

ReadyAuth

与信

Auth

与信

Auth

与信売上

AuthCapture

与信

AuthCapture

売上

PostAuth

売上確定

PostAuth

取消(与信)VoidAuth

取消(与信)VoidAuth

取消(売上)

VoidPostAuth

取消(売上)

VoidPostAuth

取消(与信売上)

VoidAuthCapture

取消(与信売上)

VoidAuthCapture

表 6-5 詳細コマンドタイプと詳細オーダー決済状態
注） 一覧に記載していないコマンドタイプと状態も存在します。

ペンディングが発生した取引に関する補足
ペンディングが発生した取引については、基本的には弊社で決済状況を確認し自動でステータスを更新しますので、時間を置いてから管理画面（MAP）の取引検索や Search コマンド（検索）を利用して決済状況をご確認ください。

20

VeriTrans4G エポスかんたん決済ご利用ガイド

第7章 導入・テストに関する補足
決済サーバーに接続し、テストを実施するための各種手続き・手順の詳細につきましては、『導入テストガイド』を参照してください。

決済申込時のエラーをシミュレートする弊社では、エポスかんたん決済のテストのための疑似環境を提供しています。
Authorize コマンドの結果として返戻されたレスポンスコンテンツをブラウザに返戻すると、以下の疑似環境に自動的に遷移します。
エポスかんたん決済のログイン画面のイメージが表示されますので、そのまま「ログイン」ボタンをクリックするとお支払方法選択画面に遷移します。「ご利用サイトへ戻る」ボタンをクリックすると加盟店のキャンセル画面に遷移します(※)。

お支払方法選択画面では、クーポン額とポイント額の指定することが可能で、「次へ」ボタンをクリックすることで次の画面に遷移します。
「ログイン画面へ戻る」をクリックするとログイン画面に戻り、「ご利用サイトへ戻る」ボタンをクリックすると加盟店のキャンセル画面に遷移します(※)。
※加盟店のキャンセル画面に遷移する際の vResultCode は“8GU1”となります。

図 7-1 疑似環境（ダミーエポス－ログイン画面）

図 7-2 疑似環境（ダミーエポス－お支払方法選択画面）

21

VeriTrans4G エポスかんたん決済ご利用ガイド
お支払内容確認画面では、その後の処理のシミュレートしたい内容を選択し「支払う」ボタンをクリックすることで、以降の遷移を確認する
ことができます。「内容を変更する」ボタンをクリックするとお支払方法選択画面に戻り、「ログイン画面へ戻る」をクリックするとログイン画面に戻ります。

図 7-3 疑似環境（ダミーエポス－お支払内容確認画面）

設定内容と遷移先についての対応表を以下に記載します。
リスト選択
結果選択

遷移先
（失敗時のエラー内容選択）

成功

-

与信 NG

加盟店の決済完了画面に遷移します。
vResultCode：8001(成功)
決済失敗となる場合のシミュレートです。
vResultCode：8G01(エラー)失敗
システムエラー

決済時にセンター側でシステムエラーとなる場合のシミュレートです。
vResultCode：8GU2(エラー)22

VeriTrans4G エポスかんたん決済ご利用ガイド

売上・キャンセル時のエラーをシミュレートする
Capture および Cancel コマンドの要求金額の下一桁の値を調整することで、意図的にエラーを発生させることができます。
要求金額の下一桁と、返戻される vResultCode の対応表を以下に記載します。

要求金額のCaptureCancel下1桁（売上）（キャンセル）

08001(成功)

1

8GD2(エラー)2

8ED1(ペンディング)

38002(みなし成功)

8001(成功)

4

8GD2(エラー)

5

8ED1(ペンディング)
8002(みなし成功)6※売上後の部分キャンセルの場合は、8001(成功)

8ED1(ペンディング)になります。

788001(成功)9

金額未指定の場合、全額が要求されたものとして動作します。

ペンディングのケースの場合、一定時間経過後に成功に自動的に遷移します。ただし、売上後の部分キャンセルでペンディングになるケースでは、ペンディングからステータスが遷移することはございませんのでご注意ください。
例 1 自動的に遷移するケース：
与信申込（1002 円）成功 → 売上ペンディング → 一定時間経過後に売上成功の状態に遷移（キャンセル可能）例 2 自動的に遷移しないケース(売上後の部分キャンセルでペンディング)：与信申込（1000 円）成功 → 売上成功 → キャンセル（106 円）ペンディング ※状態は変化しない



返戻されるエラーコード（vResultCode）につきましては、今後、予告なしに変更させて頂く場合がございます。

23