エポスかんたん決済
本ガイドの内容
本ガイドの内容
本ガイドは、(株)DGフィナンシャルテクノロジーが提供するVeriTrans4Gの「エポスかんたん決済」をインターネット店舗等でご利用頂くため、専用ソフトウェアMDK（Merchant Development Kit）を導入する開発者向けのガイドです。
概要
エポスかんたん決済は、加盟店様のサイトで購入された商品の代金をエポスNetのアカウントを利用して決済できるサービスです。
- エポスNetのID・パスワードだけの簡単な支払い方法です。
- カード番号や有効期限を入力しなくてもお買い物が可能です。
決済の画面遷移のイメージを以下に示します。
MDKの処理概要
機能一覧（決済要求コマンド）
使用可能な決済要求コマンドを下記表に示します。
| 決済要求種類 /コマンド |
概要 |
|---|---|
| 決済申込 （与信） /Authorize |
決済の申込（オーソリ※１）を要求します。 |
| 決済申込 （与信＋売上） /Authorize |
決済の申込（オーソリ）と売上を同時に要求します。 |
| 売上 /Capture |
申込済み取引の売上確定を要求します。 全額売上のみとなります※２。 |
| キャンセル /Cancel |
決済をキャンセルします。 決済金額を超えない範囲で、キャンセル金額を指定できます（部分キャンセル）※2。 |
※１ 申込（与信または与信＋売上）の際には、消費者のエポスNetのIDに紐づいたクレジットカードで与信（オーソリ）取得が行われます。
※２ 部分売上の実現方法・部分キャンセルをご利用の際は、必ず「6.1.2 部分売上の実現方法および部分キャンセルに関する注意事項」をご参照ください。
決済処理シーケンス
【エポスかんたん決済：決済申込時の処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 決済申込要求 | ECサイト上の決済導入部に渡された決済申込情報を電文化し、決済サーバーに送信します。 |
| 2 | 結果応答の受信 | 決済サーバーから返戻された結果を受信します。結果が決済可能の場合、「3. リダイレクト指示」を実施します。消費者ブラウザに返す情報(※1)は決済サーバーより返戻された結果に含まれます。 |
| 3 | リダイレクト指示 | 決済サーバーにより返戻された情報を用いて、消費者ブラウザにエポスかんたん決済のログイン画面へのリダイレクト指示を送信します。 |
| 4 | 決済結果通知(PUSH) |
この通知は、決済申込により与信が成功した場合のみ通知されます(※2)。 決済サーバーからPUSH通知先URLにPOSTで通知しますので、決済結果を受け取り、注文データ等に反映します。 確実に決済結果が取得できるように必ず決済結果通知（PUSH）を受信してください。 |
| 5 | 完了画面要求 | 消費者ブラウザから結果を受信し、完了画面を送信します(※2)。 |
| 6 | 決済結果通知(PUSH) | 消費者側の状況により通信断や誤ってブラウザを閉じる、といったケースでエポスからのリダイレクト(完了処理要求)が発生しなかった場合、決済サーバー側の処理で決済結果を確認しPUSH送信を行います。
確実に決済結果が取得できるように必ず決済結果通知（PUSH）を受信してください。 |
※1 FormをSubmit(POST)するHTMLコンテンツが返戻されます。HTMLコンテンツには、Formを自動SubmitするJavaScriptが含まれていますので、そのまま消費者に送信すれば（JavaScriptを利用可能な端末では）自動で画面遷移します。
※2 消費者側の状況により通信断や誤ってブラウザを閉じる、といったケースではこのシーケンスは発生しません。
【エポスかんたん決済：売上要求時の処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 売上要求 | 売上の対象となる取引情報を電文化し、決済サーバーに送信します。 |
| 2 | 結果応答 | 決済サーバーより結果応答を受信します。 |
【エポスかんたん決済：キャンセル要求時の処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | キャンセル要求 | キャンセルの対象となる取引情報を電文化し、決済サーバーに送信します。 部分キャンセルは決済金額が0円になるまで繰り返し実施可能です。 |
| 2 | 結果応答 | 決済サーバーより結果応答を受信します。 |
結果通知受信処理
結果通知受信処理の対象
エポスかんたん決済の結果通知受信処理の対象は以下の機能です。
| 決済サービス名 | 決済申込 （与信/与信売上） |
売上 | キャンセル |
|---|---|---|---|
| エポスかんたん決済 | ○ | － | － |
通信電文仕様（共通部）および店舗受信後応答仕様は、『開発ガイド』をご参照ください。
エポスかんたん決済固有の通知電文インターフェイスにつきましては、「5.3.2エポスかんたん決済の結果通知電文」をご参照ください。
インターフェイス詳細
ここではエポスかんたん決済サービスで利用するMDKインターフェイス項目を説明します。
-
「設定」欄の内容は以下の通りです。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※ （条件は説明欄、または欄外に記入）
- 応答電文 ...
- 必ず返戻：○ 処理成功時のみ返戻：△ 返戻なし：× その他条件付：※
-
orderId（取引ID）について
店舗で任意に採番してください。申込処理毎に付ける必要があります。他の取引IDと重複しないよう採番してください。他決済サービスとも重複できません。
また、テスト取引で使用した取引IDを、本番取引で再度使用することはできません。
取引IDには、半角英数字以外に"-"（ハイフン）、"_"（アンダースコア）も使用可能です。
エポスかんたん決済
決済申込
| 要求電文 ： EposAuthorizeRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 100桁以内 |
店舗側で採番した取引IDを指定 |
○ |
| amount | 決済金額 | 半角数字 1桁－8桁 |
決済金額（合計金額）を指定 | ○ |
| withCapture | 売上フラグ | 右記参照 | "true"： 与信・売上 "false"： 与信のみ （デフォルト値） ※ 指定が無い場合は、与信のみとなります。 |
△ |
| customerId | 加盟店顧客ID | 半角英数字記号 32バイト以内 |
店舗側サイトにて該当顧客を一意に識別するID。 以下の記号が使用可能です。 "."(ピリオド)、","(カンマ)、"/"(スラッシュ)、":"(コロン)、 "_"(アンダースコア)、"?"(疑問符)、"&"(アンパサンド)、 "#"(シャープ)、"%"(パーセント)、"="(イコール)、"-"(ハイフン) |
○ |
| successUrl | 決済完了時URL | URLに使用可能な半角文字 256桁以内 |
決済成功時に、店舗側サイトに画面遷移を戻すためのURLを指定（クエリパラメータ指定可）
※未指定の場合は、MAP（Merchant Administrator Portal）から登録申請した値を使用 |
△ |
| cancelUrl | 決済キャンセル時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）から登録申請した値を使用 |
△ |
| 応答電文 ： EposAuthorizeResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ | 半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード | 半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ | 文字列 1024 バイト以内 |
処理結果を日本語で表示します。 | ○ |
| marchTxn | 電文ID | 文字列 100桁以内 |
決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。 |
○ |
| orderId | 取引ID | 半角英数字 100文字以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID | 文字列 100桁以内 |
決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| txnVersion | MDK バージョン | 半角英数字5桁 | 電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| responseContents | レスポンス コンテンツ |
文字列 | 決済申込み成功時に返戻される、店舗様側でコンシューマに対して返戻するHTMLコンテンツ。 自動でエポスが提供するページに遷移するためのJavaScriptを含みますので、そのままの内容を消費者のブラウザに返戻するようにしてください。このとき、コンテンツの文字コードは必ずShift_JISに設定してください。 |
※ |
消費者ブラウザから店舗側の完了画面へリダイレクトする時のクエリパラメータ
| リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(GET)される内容 | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
"success" ：正常終了 "failure" ：異常終了 |
○ |
| vResultCode | 詳細結果コード | 半角英数16桁 | 処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| orderId | 取引ID | 半角英数字100文字以内 | 決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| txnType | トランザクションタイプ | 文字列 右記参照 |
通知対象となるトランザクションのタイプが設定されます。 "Authorize" |
○ |
| eposOrderId | エポス取引ID | 半角英数字13文字 | エポス側で取引を一意に表すID | ○ |
| useCredit | クレジット利用額 | 半角数字 1桁－8桁 |
消費者がエポスの画面で入力したクレジット利用額 | △ |
| useCoupon | クーポン利用額 | 半角数字 1桁－8桁 |
消費者がエポスの画面で入力したクーポン利用額 | △ |
| usePoint | ポイント利用額 | 半角数字 1桁－8桁 |
消費者がエポスの画面で入力したポイント利用額 | △ |
| vAuthInfo | 改ざんチェック用 ハッシュ値 |
文字列 右記参照 |
下記文字列を連結し、SHA-256によって算出したハッシュ値
|
○ |
| authParams | ハッシュ値算出パラメータ順序 | 文字列 右記参照 |
vAuthInfo のハッシュ値を算出する元とした文字列の、パラメータの連結順序を示す値 パラメータ名のカンマ区切り文字列をBase64エンコードしています。デコードを行うと文字列が復元されます。 例) "orderId,vResultCode,mstatus" "mstatus,orderId,vResultCode" （順不同のため、リクエスト受信の度に動的に処理して下さい。） |
○ |
これらのパラメータはブラウザを経由して連携されるため、画面遷移が正常に行われないケースでは取得することができません。そのため、決済サーバーから直接送信される「5-3 結果通知電文」の受信と組み合わせて確実に結果を取得するようにしてください。
決済サーバーから消費者ブラウザを経由して店舗側の結果画面に遷移（リダイレクト）しますが、ここで店舗側システムが受け取ったクエリパラメータが改ざんされていないことを検証するためのパラメータが、vAuthInfoとauthParamsです。
店舗側システムで算出したハッシュ値が、クエリパラメータより取得したvAuthInfoと一致している場合は、パラメータは改ざんされていない、とみなすことができます。
この改ざんチェックは、悪意を持った第三者によって、不正なリダイレクト電文を受信する可能性がありますので、実装を強く推奨しています。
売上
| 要求電文 ： EposCaptureRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 100桁以内 |
売上対象の取引IDを指定 | ○ |
| 応答電文 ： EposCaptureResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| 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桁 | 電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
キャンセル
| 要求電文 ： EposCancelRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 100桁以内 |
上記「orderId（取引ID）について」参照 | ○ |
| amount | 減額金額 | 半角数字 1桁－8桁 |
減額する金額を指定。
※売上(与信同時売上)実施後の場合、指定できる金額は |
△ |
| 応答電文 ： EposCancelResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| 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桁 | 電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| balance | 残高 | 半角数字 1桁－8桁 |
現在の決済金額 | △ |
| useCredit | クレジット利用額 | 半角数字 1桁－8桁 |
クレジット利用額
※全額キャンセルの場合は0を返します。 |
※ |
| useCoupon | クーポン利用額 | 半角数字 1桁－8桁 |
クーポン利用額
※全額キャンセルの場合は0を返します。 |
※ |
| usePoint | ポイント利用額 | 半角数字 1桁－8桁 |
ポイント利用額
※全額キャンセルの場合は0を返します。 |
※ |
※成功時のみ返戻する項目ですが、決済センターの処理により、成功時でも返戻されない場合があります。
共通
検索
-
「設定」欄の内容は以下の通りとなります。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※（条件は説明欄に記入）
- 応答電文 ...
- 必ず返戻：○ 該当取引存在時に返戻：△ 返戻なし：× その他条件付：※
-
複数指定は0～の添字を指定します。
例）exparam.serviceTypeCd[0]=card&exparam.serviceTypeCd[1]=rakuten -
ワイルドカードは値の一部と"*"を組み合わせて検索します。"*"のみの指定はできません。
例）exparam.searchParameters.common.orderId=123* 通常の検索の他、マスタ情報取得が可能です。マスタ情報取得時のインターフェイスは後記します。
| 要求電文 ： SearchRequestDto | |||||||
|---|---|---|---|---|---|---|---|
|
※ 以下は、共通の検索要求フィールドです。 |
|||||||
| 検索フィールド名 | 検索項目名 | 書式・制限 | 複数 指定 |
ﾜｲﾙﾄﾞ ｶｰﾄﾞ |
説明 | 設定 | |
| requestId | リクエストID | 半角英数字記号128文字以内 | リクエストIDを指定します。指定した場合は、それ以外のパラメータは指定できなくなります。 | △ | |||
| serviceTypeCd | 決済サービスタイプ | 右記参照 | ○ | 検索対象の決済を指定します。未指定の場合は、全決済が検索対象となります。 "rakuten"： エポスかんたん決済 |
△ | ||
| newerFlag | 最新トランザクションフラグ | 右記参照 | 成功、失敗に関係なく、最新トランザクションのみを検索する場合に使用します。 "true"： 1取引内の最新トランザクションのみ検索 "false"： 全てのトランザクションを検索 ※指定しない場合は"false"になります。 |
△ | |||
| containDummyFlag | ダミー決済対象フラグ | 右記参照 | ダミー取引も検索する場合に使用します。 "true"： ダミー取引も検索する "false"： ダミー取引は検索しない ※指定しない場合は"false"になります。 |
△ | |||
| maxCount | 検索最大件数 | 1～1000 | 取得したい検索結果の最大件数です。未指定の場合、最大値となります。
※短時間で大量の検索を繰り返すような処理はサーバに負荷が掛かりますのでご遠慮頂けますようお願いします。 |
△ | |||
| common 共通 | |||||||
| orderId | 取引ID | 半角英数字100桁以内 | ○ | 検索したい取引IDを指定します。 | △ | ||
| orderStatus | 取引決済状態 | 右記参照 | ○ | 以下のいずれかを指定します。 " initial "：初期状態 " end "：終了 " end_presentation "：画面遷移正常終了 " pending "：保留 " validation_error "：検証エラー " expired "：期限切れ " error "：エラー |
△ | ||
| command | コマンド | 右記参照 | ○ | 決済で使用するコマンドを指定します。 " Authorize "：決済申込 " Capture "：売上 " Cancel "：キャンセル |
△ | ||
| 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）を指定します。 | △ | |||
|
※ 以下は、エポスかんたん決済固有の検索要求フィールドです。 |
|||||||
| epos エポスかんたん決済 | |||||||
| detailOrderType | 詳細オーダー決済状態 | 右記参照 | ○ |
※「detailOrderType」の詳細については、「6-3検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）」を参照 |
△ | ||
| detailCommandType | 詳細コマンドタイプ | 右記参照 | ○ |
※「detailCommandType」の詳細については、「6-3検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）」を参照 |
△ | ||
| eposOrdeId | エポス取引ID | 半角英数字13文字 | エポス側で取引を一意に表す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 | 決済サービスタイプ | 右記参照 | 決済の種類が格納されます。 "rakuten"： エポスかんたん決済 |
△ | ||||||||
| 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 | 固有トランザクション情報 | － |
各決済サービスの固有トランザクション情報が格納されます。後述の一覧参照。 | △ | ||||||||
| ☆ 以下の情報は、上記 「固有オーダー情報」 「固有トランザクション情報」 内の階層にセットされます。 | ||||||||||||
|
※ 以下は、エポスかんたん決済固有の検索結果フィールドです。 |
||||||||||||
| properOrderInfo | エポスかんたん決済 固有オーダー情報 | |||||||||||
| 与信同時売上フラグ | withCapture | 文字列 | 決済申込時に指定した与信同時売上フラグ | △ | ||||||||
| 申込金額 | authorizeAmount | 半角数字8桁以内 | 決済申込時に指定した金額 | △ | ||||||||
| 残高 | balance | 半角数字8桁以内 | 残高（現在の決済金額） | △ | ||||||||
| 決済申込日時 | authorizeDatetime | 文字列14桁 | 決済申込日時 YYYYMMDDhhmmss形式 |
△ | ||||||||
| エポス取引ID | eposOrderId | 半角英数字13文字 | エポス側で取引を一意に表すID | △ | ||||||||
| クレジット利用額 | useCredit | 半角数字 1桁－8桁 |
クレジット利用額 | △ | ||||||||
| クーポン利用額 | useCoupon | 半角数字 1桁－8桁 |
クーポン利用額 | △ | ||||||||
| ポイント利用額 | usePoint | 半角数字 1桁－8桁 |
ポイント利用額 | △ | ||||||||
| properTransactionInfo | エポスかんたん決済 固有トランザクション情報 | |||||||||||
| 詳細コマンドタイプ | detailCommandType | 文字列 |
※「detailCommandType」の詳細については、「6-3検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）」を参照 |
△ | ||||||||
| クレジット利用額 | useCredit | 半角数字 1桁－8桁 |
クレジット利用額 | △ | ||||||||
| クーポン利用額 | useCoupon | 半角数字 1桁－8桁 |
クーポン利用額 | △ | ||||||||
| ポイント利用額 | usePoint | 半角数字 1桁－8桁 |
ポイント利用額 | △ | ||||||||
| エポスへの要求日時 | eposRequestDatetime | 文字列14文字 | エポスへの要求日時が格納されます。 YYYYMMDDhhmmss形式 |
△ | ||||||||
| エポスからの返戻日時 | eposResponseDatetime | 文字列14文字 | エポスからの返戻日時が格納されます。 YYYYMMDDhhmmss形式 |
△ | ||||||||
結果通知電文
結果通知電文の概要
実装方法の詳細につきましては、弊社より提供しているサンプルプログラムをご参照ください。
-
機能概要
決済サーバーから店舗システムへ決済の結果通知を行います。
通知は、HTTPのPOSTを利用します。※プロトコルはHTTP（Port：80）、HTTPS（Port：443）に対応しています。
処理の概要については「結果通知受信処理」をご参照ください。 -
HMACについて
POSTにてデータを通知するとき、リクエストヘッダーにHMACを設定します。
また、HMAC値は、リクエストボディから算出します。
アルゴリズムは「HmacSHA256」が設定されます。
| フィールド名 | 設定値 |
|---|---|
| content-hmac | h={アルゴリズム名};s={CCID};v={HMAC値} |
■結果通知受信処理結果について
決済サーバーからの通知に対して店舗側システムがHTTPステータスコード"200"を返戻した場合、受信処理が正常に
終了したものと判断します。"200"以外のコードを返した場合は、受信失敗と判断し、一定期間、通知を繰り返します。
※ 返戻した場合、受信処理が正常に終了したものと判断します。
エポスかんたん決済の結果通知電文
エポスかんたん決済では、決済が成立しているのにもかかわらず、消費者が画面遷移の途中で離脱した場合や、通信環境の問題で画面遷移時にタイムアウトが発生した場合など、最終遷移先まで到達しない場合があります。
このような場合にも、決済サーバーからの通知を店舗側システムで受信して頂くことで、決済が成立したことを検知することができます。必ず結果通知を受信してください。
| No. | 通知種類 | 通知タイミング | 注意事項 |
|---|---|---|---|
| 1 | 決済結果通知 （Authorize） |
決済申込が成立（成功）したタイミングで送信されます。 | 決済申込が失敗した場合は送信されません。 |
以下に、エポスかんたん決済の結果通知項目を示します。
| 項番 | フィールド名 | 項目名 | 書式・制限 | 説明 |
|---|---|---|---|---|
| 1 | numberOfNotify | 通知件数 | 半角数字4桁以内 | 1度に通知可能な件数は100件、 101件以上は次回通知 |
| 2 | pushTime | 送信時刻 | 半角数字14桁 | ゲートウェイから通知した時刻 yyyyMMddHHmmss形式 |
| 3 | pushId | 識別ID | 半角数字8桁 | プッシュ処理を行うたびに採番されるID。 注） 他の決済サービスで使用されたIDと重複する場合があります。 |
| 通知件数分下記の項番（4～13）を繰り返す。尚、フィールド名の後ろに4ケタの連番（0000～0999）を付与する。 | ||||
| 4 | orderId | 取引ID | 半角英数字100桁以内 | 取引ID |
| 5 | txnType | トランザクションタイプ |
※右記の説明を参照 |
"Authorize"：決済結果通知 |
| 6 | txnTime | 処理日時 | 半角数字14桁 | yyyyMMddHHmmss形式 |
| 7 | vResultCode | 詳細結果コード | 半角英数字16桁 | 処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
| 8 | mstatus | 処理ステータス | 半角英数字8桁以内 | "success "：正常終了 "failure" ：異常終了 |
| 9 | eposOrderId | エポス取引ID | 半角英数字13文字 | エポス側で取引を一意に表すID |
| 10 | useCredit | クレジット利用額 | 半角数字 1桁－8桁 |
消費者がエポスの画面で入力したクレジット利用額 |
| 11 | useCoupon | クーポン利用額 | 半角数字 1桁－8桁 |
消費者がエポスの画面で入力したクーポン利用額 |
| 12 | usePoint | ポイント利用額 | 半角数字 1桁－8桁 |
消費者がエポスの画面で入力したポイント利用額 |
| 13 | dummy | ダミー決済フラグ | 半角数字1桁 | ダミー取引を示す場合は"1"を設定する。 |
- pushId（識別ID）は、他の決済サービスで使用されたIdと重複する場合がありますので、ユニークキーとして処理しないようにしてください。
- 項目の並び順は、必ずしも表の順序とは一致しません。
その他 補足事項
売上およびキャンセルに関する注意事項
売上およびキャンセルの要求可能期間
エポスかんたん決済における、売上およびキャンセルの要求可能期間を下表に示します。
| 要求種類 | 要求可能期間 |
|---|---|
| 売上 | 決済申込日（与信日）から180日間 |
| キャンセル | 売上前： 決済申込日（与信日）から180日間 売上後： 決済サーバーで取引データを保持している間 |
■売上・キャンセル時の注意点
決済申込は、最終の処理結果が反映されるまで時間がかかりますので、後続コマンドを実施する際は時間をおいてから実施してください。処理結果が反映される前にコマンドが実施されるとエラーが返戻されます。
部分売上の実現方法および部分キャンセルに関する注意事項
■ 部分売上
- 売上コマンドで、部分売上（与信額と異なる金額で売上）は実施できません。与信で確保した金額のうち一部を売り上げたい場合は、売上コマンドの実施前に（与信の）部分キャンセルを実施し、金額を変更してから売上コマンドを実施することで実現可能です。売上コマンド実施後に再度売上コマンドを実施することはできません。
■ 部分キャンセル
- 与信後の売上および与信同時売上後の部分キャンセルについては、クレジット利用額を超える値はキャンセルできません（クーポンやポイントで決済された金額分のキャンセルはできません）。売上金額を超えない範囲で、キャンセル金額を指定できます。
エポスのクーポンやポイントを利用した決済に関する注意点
エポスのポイントやクーポンを利用した決済では、消費者がエポスかんたん決済の購入画面で利用額を設定します。
以下に、エポスのポイントを利用した決済についての注意点を示します。
- 与信後の売上および与信同時売上後の部分キャンセルを実施する際に、クレジット利用額を超える値を指定するとエラーとなります。
検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）
管理サーバーでは、エポスかんたん決済のシステム内部データとして詳細コマンド（処理要求の種類）と詳細な決済状態（その取引がどのような状態にあるか）を管理しています。
通常の運用では、店舗様システムではこれらの内部情報を利用する必要はありませんが、店舗様システムにおいて取引の状態検索が必要なケースや、障害等のお問い合わせ時の参照情報として、これらの内部データをSearchコマンドで公開しています。
下表にSearchコマンドにて利用可能な内部データの一覧を示します。
| 詳細コマンドタイプ | コマンド成功時の詳細オーダー決済状態 | ||
|---|---|---|---|
| 論理名 | 値 | 論理名 | 値 |
| 与信準備 | ReadyAuth | 与信準備 | ReadyAuth |
| 与信 | Auth | 与信 | Auth |
| 与信売上 | AuthCapture | 与信 | AuthCapture |
| 売上 | PostAuth | 売上確定 | PostAuth |
| 取消(与信) | VoidAuth | 取消(与信) | VoidAuth |
| 取消(売上) | VoidPostAuth | 取消(売上) | VoidPostAuth |
| 取消(与信売上) | VoidAuthCapture | 取消(与信売上) | VoidAuthCapture |
注） 一覧に記載していないコマンドタイプと状態も存在します。
ペンディングが発生した取引に関する補足
ペンディングが発生した取引については、基本的には弊社で決済状況を確認し自動でステータスを更新しますので、時間を置いてから管理画面（MAP）の取引検索やSearchコマンド（検索）を利用して決済状況をご確認ください。
導入・テストに関する補足
決済サーバーに接続し、テストを実施するための各種手続き・手順の詳細につきましては、『導入テストガイド』を参照してください。
決済申込時のエラーをシミュレートする
弊社では、エポスかんたん決済のテストのための疑似環境を提供しています。
Authorizeコマンドの結果として返戻されたレスポンスコンテンツをブラウザに返戻すると、以下の疑似環境に自動的に遷移します。
エポスかんたん決済のログイン画面のイメージが表示されますので、そのまま「ログイン」ボタンをクリックするとお支払方法選択画面に遷移します。「ご利用サイトへ戻る」ボタンをクリックすると加盟店のキャンセル画面に遷移します(※)。
お支払方法選択画面では、クーポン額とポイント額の指定することが可能で、「次へ」ボタンをクリックすることで次の画面に遷移します。
「ログイン画面へ戻る」をクリックするとログイン画面に戻り、「ご利用サイトへ戻る」ボタンをクリックすると加盟店のキャンセル画面に遷移します(※)。
※加盟店のキャンセル画面に遷移する際のvResultCodeは"8GU1"となります。
お支払内容確認画面では、その後の処理のシミュレートしたい内容を選択し「支払う」ボタンをクリックすることで、以降の遷移を確認することができます。「内容を変更する」ボタンをクリックするとお支払方法選択画面に戻り、「ログイン画面へ戻る」をクリックするとログイン画面に戻ります。
設定内容と遷移先についての対応表を以下に記載します。
| 結果選択 | リスト選択 （失敗時のエラー内容選択） |
遷移先 |
|---|---|---|
| 成功 | - | 加盟店の決済完了画面に遷移します。 vResultCode：8001(成功) |
| 失敗 | 与信NG | 決済失敗となる場合のシミュレートです。 vResultCode：8G01(エラー) |
| システムエラー | 決済時にセンター側でシステムエラーとなる場合のシミュレートです。 vResultCode：8GU2(エラー) |
売上・キャンセル時のエラーをシミュレートする
CaptureおよびCancelコマンドの要求金額の下一桁の値を調整することで、意図的にエラーを発生させることができます。
要求金額の下一桁と、返戻されるvResultCodeの対応表を以下に記載します。
| 要求金額の 下1桁 |
Capture（売上） | Cancel（キャンセル） |
|---|---|---|
| 0 | 8001(成功) | 8001(成功) |
| 1 | 8GD2(エラー) | |
| 2 | 8ED1(ペンディング) | |
| 3 | 8002(みなし成功) | |
| 4 | 8001(成功) | 8GD2(エラー) |
| 5 | 8ED1(ペンディング) | |
| 6 | 8002(みなし成功)
※売上後の部分キャンセルの場合は、8ED1(ペンディング)になります。 |
|
| 7 | 8001(成功) | |
| 8 | ||
| 9 |
- 金額未指定の場合、全額が要求されたものとして動作します。
- ペンディングのケースの場合、一定時間経過後に成功に自動的に遷移します。ただし、売上後の部分キャンセルでペンディングになるケースでは、ペンディングからステータスが遷移することはございませんのでご注意ください。
例1 自動的に遷移するケース：
与信申込（1002円）成功 → 売上ペンディング → 一定時間経過後に売上成功の状態に遷移（キャンセル可能）
例2 自動的に遷移しないケース(売上後の部分キャンセルでペンディング)：
与信申込（1000円）成功 → 売上成功 → キャンセル（106円）ペンディング ※状態は変化しない - 返戻されるエラーコード（vResultCode）につきましては、今後、予告なしに変更させて頂く場合がございます。