ファミペイ
本ガイドについて
本ガイドの内容
本ガイドは、(株)DGフィナンシャルテクノロジーが提供するVeriTrans4Gのファミペイサービスをインターネット店舗等に導入するための、WEBアプリケーション開発者向けのガイドです。
ファミペイサービス概要
ファミペイサービスは、加盟店様のサイトで購入された商品の代金を、ファミペイのユーザIDで決済できるサービスです。
- ファミペイ利用登録を行ったユーザが利用できる、パスワードのみの簡単な支払い方法です。
- 事前にチャージして支払いする方法となります。
- チャージ方法は、店舗のレジでチャージする方法や、ファミマＴカード（クレジットカード）をアプリに登録してクレジットカードでチャージする方法などがあります。
利用可能なチャージ方法やチャージ手順についてはファミペイサイトの情報やアプリをご参照ください。
決済の画面遷移のイメージを以下に示します。
MDKの処理概要
機能一覧（決済要求コマンド）
使用可能な決済要求コマンドを下記表に示します。
| 決済要求種類 /コマンド |
概要 |
|---|---|
| 申込 （与信＋売上） /Authorize |
決済の申し込み（オーソリ）と売上を同時に要求します。 |
| キャンセル /Cancel |
決済を取消（キャンセル）します。 取消金額は全額のみとなります。 |
決済処理シーケンス
【ファミペイ：決済申込時の処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 決済申込要求 | ECサイトに渡された決済申込情報を電文化し、決済サーバーに送信します。 |
| 2 | 結果応答の受信 | 決済サーバーから返戻された結果を受信します。結果が成功（決済可能）の場合、「3. リダイレクト指示」を実施します。消費者ブラウザに返すリダイレクト先のURLが決済サーバーより返戻された結果に含まれます。 |
| 3 | リダイレクト指示 | 決済サーバーにより返戻されたリダイレクト先のURL（決済URL）を用いて、消費者ブラウザにファミペイの決済URLへのリダイレクト指示を送信します。※1 |
| 4 | 申込結果通知（PUSH） | この通知は、決済申込により与信が成功した場合のみ通知されます。 MAP（Merchant Administration Portal）の契約情報確認・変更のページより登録申請した結果通知受信URLに、決済サーバーよりPOSTで通知されますので、決済結果を受け取り、注文データ等に反映します。 |
| 5 | 完了画面要求 |
消費者ブラウザから結果を受信し、完了画面を送信します。
消費者側の状況により通信断や誤ってブラウザを閉じる、といったケースではこのシーケンスは発生しません。確実に決済結果が取得できるように必ず【４．申込結果通知(PUSH)】を受信してください。 なお、申込結果通知と完了画面要求のリダイレクト結果が加盟店に届く順番は保証されていません。どちらが先に届いても問題とならないようにご対応ください |
※1 HTTPレスポンスヘッダ（Locationヘッダ）にリダイレクト先URLを設定し、HTTPステータスコード＝302でリダイレクトするか、JavaScriptを利用してリダイレクト先URLに自動遷移させてください。
【ファミペイ：キャンセル処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 取消要求 | キャンセルの対象となる取引情報を電文化し、決済サーバーに送信します。 |
| 2 | 結果応答 | 決済サーバーより結果応答を受信します。 |
結果通知受信処理
結果通知受信処理の対象
ファミペイの結果通知受信処理の対象は以下の機能です。
| 決済サービス名 | 決済申込 （与信売上） |
キャンセル |
|---|---|---|
| ファミペイ | ○ | － |
通信電文仕様（共通部）および店舗受信後応答仕様は、『開発ガイド』をご参照ください。
ファミペイ固有の通知電文インターフェースにつきましては、「5.3.2 ファミペイの結果通知電文」をご参照ください。
インターフェース詳細
ここではファミペイサービスで利用するMDKインターフェース項目を説明します。
-
「設定」欄の内容は以下の通りです。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※、※n（条件は説明欄、または欄外に記入）
- 応答電文 ...
- 必ず返戻：○ 処理成功時のみ返戻：△ 返戻なし：× その他条件付：※
-
orderId（取引ID）について
店舗で任意に採番してください。申込処理毎に付ける必要があります。他の取引IDと重複しないよう採番してください。他決済サービスとも重複できません。
また、テスト取引で使用した取引IDを、本番取引で再度使用することはできません。
取引IDには、半角英数字以外に"-"（ハイフン）、"_"（アンダースコア）も使用可能です。※他決済サービスと「書式・制限」が異なりますので、ご注意ください。
-
応答電文について
応答電文には、本書に記載されていないフィールド（パラメータ）も存在しますが、通常は、記載されているフィールド以外は加盟店様の方で意識する必要はございません。
5-1 ファミペイ
申込
| 要求電文：CvspayAuthorizeRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 27桁以内 |
店舗側で採番した取引IDを指定
※決済事業者にこの項目を連携するため、他決済サービスと異なる「書式・制限」になります。 |
○ |
| serviceOptionType | サービスオプションタイプ | 右記参照 | 利用するサービスオプションタイプを指定 "famipay"：ファミペイ |
○ |
| amount | 決済金額 | 半角数字 8桁以内 |
決済金額（合計金額）を指定 | ○ |
| withCapture | 売上フラグ | 右記参照 | "true"：与信同時売上
※指定が無い場合は、与信同時売上となります。 |
△ |
| payType | 決済種別 | 半角数字 1桁 |
決済種別を指定 "0"：オンライン決済 ※指定が無い場合は、オンライン決済となります。 |
△ |
| 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）から登録申請した値を使用。 ※本パラメータは店舗側システムの開発時にのみ利用されることを想定しており、ダミー取引で指定可能です。 |
※ |
| 応答電文：CvspayAuthorizeResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ | 半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード | 半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照ください。 |
○ |
| merrMsg | エラーメッセージ | 文字列 1024バイト以内 |
処理結果を日本語で表示します。 | ○ |
| marchTxn | 電文ID | 文字列 100桁以内 |
決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID 1つの取引IDに対して、複数のIDが付与されます。 |
○ |
| orderId | 取引ID | 半角英数字 100桁以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID | 半角英数字 100桁以内 |
決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| txnVersion | MDKバージョン | 半角英数字5桁 | 電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| redirectUrl | リダイレクトURL | 文字列 | 決済事業者が提供する決済URL。 決済申込を行った場合は、こちらのURLにそのまま遷移させます。 |
△ |
消費者ブラウザから店舗側の完了画面へリダイレクトする時のクエリパラメータ
| リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗へリダイレクト（GET）される内容 | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード | 半角英数4桁 | 処理の結果を詳細に表すコード 詳細は『結果コード一覧』を参照ください。 |
○ |
| orderId | 取引ID | 半角英数字100文字以内 | 決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| txnType | トランザクションタイプ | 文字列 右記参照 |
通知対象となるトランザクションのタイプが設定されます。 "Authorize" |
○ |
| cvspayOrderId | 決済事業者 取引番号 |
半角英数字12文字以内 | 決済事業者側で発番された取引番号
※mstatus=failureの場合は設定されません。 |
△ |
| vAuthInfo | 改ざんチェック用 ハッシュ値 |
文字列 右記参照 |
下記文字列を連結し、SHA-256によって算出したハッシュ値
|
○ |
| authParams | ハッシュ値算出 パラメータ順序 |
文字列 右記参照 |
vAuthInfoのハッシュ値を算出する元とした文字列の、パラメータの連結順序を示す値 パラメータ名のカンマ区切り文字列をBase64エンコードしています。デコードを行うと文字列が復元されます。 例） "orderId,vResultCode,mstatus" "mstatus,orderId,vResultCode" （順序は固定ではないため、リクエスト受信のたびに動的に処理する必要があります。） |
○ |
これらのパラメータはブラウザを経由して連携されるため、画面遷移が正常に行われないケースでは取得することができません。そのため、決済サーバーから直接送信される「5-3 結果通知電文」の受信と組み合わせて確実に結果を取得するようにしてください。
決済サーバーから消費者ブラウザを経由して店舗側の結果画面に遷移（リダイレクト）しますが、ここで店舗側システムが受け取ったクエリパラメータが改ざんされていないことを検証するためのパラメータが、vAuthInfoとauthParamsです。
店舗側システムで算出したハッシュ値が、クエリパラメータより取得したvAuthInfoと一致している場合は、パラメータは改ざんされていない、とみなすことができます。
この改ざんチェックは、悪意を持った第三者によって、不正なリダイレクト電文を受信する可能性がありますので、実装を強く推奨しています。
実装方法の詳細につきましては、弊社より提供しているサンプルプログラムをご参照ください。
取消
| 要求電文：CvspayCancelRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 100桁以内 |
上記「orderId（取引ID）について」参照 | ○ |
| serviceOptionType | サービスオプションタイプ | 右記参照 | 利用するサービスオプションタイプを指定 "famipay"：ファミペイ |
○ |
| 応答電文：CvspayCancelResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ | 半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 "pending"：保留 |
○ |
| vResultCode | 詳細結果コード | 半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照ください。 |
○ |
| merrMsg | エラーメッセージ | 文字列 1024バイト以内 |
処理結果を日本語で表示します。 | ○ |
| marchTxn | 電文ID | 文字列 100桁以内 |
決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID 1つの取引IDに対して、複数のIDが付与されます。 |
○ |
| orderId | 取引ID | 半角英数字 100文字以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID | 文字列 100桁以内 |
決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| txnVersion | MDKバージョン | 半角英数字5桁 | 電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| cancelReqDatetime | 取消要求日時 | 半角数字14桁 | YYYYMMDDhhmmss形式 | △ |
| balance | 残高 | 半角数字7桁以内 | 現在の決済金額を返します。 | △ |
| cancelPoint | キャンセルポイント数 | 半角数字10桁以内 | キャンセルしたポイント数 | △ |
| balancePoint | ポイント残高 | 半角数字10桁以内 | ポイント利用キャンセル後の通常ポイント残高 | △ |
共通
検索
-
「設定」欄の内容は以下の通りとなります。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※（条件は説明欄に記入）
- 応答電文 ...
- 必ず返戻：○ 該当取引存在時に返戻：△ 返戻なし：× その他条件付：※
-
複数指定は0～の添字を指定します。
例）exparam.serviceTypeCd[0]=card&exparam.serviceTypeCd[1]=cvspay -
ワイルドカードは値の一部と"*"を組み合わせて検索します。"*"のみの指定はできません。
例）exparam.searchParameters.common.orderId=123* -
通常の検索の他、マスタ情報取得が可能です。マスタ情報取得時のインターフェースは後記します。
| 要求電文：SearchRequestDto | |||||||
|---|---|---|---|---|---|---|---|
| ※以下は、共通の検索要求フィールドです。 | |||||||
| 検索フィールド名 | 検索項目名 | 書式・制限 | 複数指定 | ﾜｲﾙﾄﾞｶｰﾄﾞ | 説明 | 設定 | |
| requestId | リクエストID | 半角英数字記号 128文字以内 |
リクエストIDを指定します。指定した場合は、それ以外のパラメータは指定できなくなります。 | △ | |||
| serviceTypeCd | 決済サービスタイプ | 右記参照 | ○ | 検索対象の決済を指定します。未指定の場合は、全決済が検索対象となります。 "cvspay"：cvspay（ファミペイ） |
△ | ||
| 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"：申込 "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）を指定します。 | △ | |||
| ※以下は、ファミペイ固有の検索要求フィールドです。 | |||||||
| cvspay ファミペイ | |||||||
| detailOrderType | 詳細オーダー決済状態 | 右記参照 | ○ | ※「detailOrderType」の詳細は「6-2 検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）」を参照 | △ | ||
| detailCommandType | 詳細コマンドタイプ | 右記参照 | ○ | ※「detailCommandType」の詳細は「6-2 検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）」を参照 | △ | ||
| cvspayType | cvspay種別 | 右記参照 | ○ | cvspayの種別を指定する。 ※現在は、"famipay"（ファミペイ）のみ |
△ | ||
| payType | 決済種別 | 右記参照 | ○ | 決済種別を指定する。 ※現在は、"0"（オンライン）のみ |
△ | ||
| cvspayOrderId | 決済事業者 取引番号 |
文字列 12桁以内 |
決済事業者側で発番された取引番号 | △ | |||
| 応答電文：SearchResponseDto | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| ※以下は、共通の検索結果フィールドです。 | |||||||||
| 検索フィールド名 | 検索項目名 | 書式・制限 | 説明 | 設定 | |||||
| result | 処理結果 | － | ○ | ||||||
| serviceType | サービスタイプ | 右記参照 | "search" | ○ | |||||
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
処理の結果ステータスが格納されます。 "success"：正常終了 "failure"：異常終了 |
○ | |||||
| vResultCode | 詳細結果コード | 半角英数字 16文字 |
処理の結果を詳細に表すコードとなります。 詳細は『結果コード一覧』を参照ください。 |
○ | |||||
| merrMsg | エラーメッセージ | 文字列1024 バイト以内 |
処理結果を日本語で表示します。 | △ | |||||
| overMaxCountFlag | 最大件数超えフラグ | 右記参照 | 検索対象データが要求電文で指定した検索最大件数より多いかどうかを表します。 "true"： 最大件数以上 "false"： 最大件数未満 |
△ | |||||
| searchCount | 検索結果件数 | 0～1000 | 検索結果件数（オーダー件数）が格納されます。 | △ | |||||
| orderInfos | オーダー情報リスト | 複数のオーダー情報（orderInfo）が格納されます。 | △ | ||||||
| orderInfo | オーダー情報 | － | 検索条件に該当した取引の情報が該当件数分繰り返されます。0～1000件（要求電文で指定した検索最大件数まで）となります。 | △ | |||||
| index | インデックス | 0～999 | 検索された情報のインデックスが格納されます。 | △ | |||||
| serviceTypeCd | 決済サービスタイプ | 右記参照 | 決済の種類が格納されます。 "cvspay"：cvspay（ファミペイ） |
△ | |||||
| 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 | ファミペイ 固有オーダー情報 | ||||||||
| cvspay種別 | cvsType | 文字列 | 決済申込時に指定したcvspay種別 | △ | |||||
| 決済種別 | payType | 文字列 | 決済申込時に指定した決済種別 | △ | |||||
| 与信同時売上フラグ | withCapture | 文字列 | 決済申込時に指定した与信同時売上フラグ | △ | |||||
| 申込金額 | authorizeAmount | 半角数字 7桁以内 |
決済申込時に指定した金額 | △ | |||||
| 残高 | balance | 半角数字 7桁以内 |
残高（現在の決済金額） | △ | |||||
| 決済申込日時 | authorizeDatetime | 文字列 14桁 |
決済申込日時 YYYYMMDDhhmmss形式 |
△ | |||||
| 決済事業者取引番号 | cvspayOrderId | 文字列 12桁以内 |
決済事業者側で発番された取引番号 | △ | |||||
| properTransactionInfo | ファミペイ 固有トランザクション情報 | ||||||||
| 決済センターエラーコード | cvspayResultCode | 文字列 | 決済センターから返却されたエラーコードが格納されます。 | △ | |||||
| 決済事業者取消取引番号 | cvspayCancelOrderId | 文字列 12桁以内 |
決済取消時に決済事業者側で発番された取引番号 | △ | |||||
| 詳細コマンドタイプ | detailCommandType | 文字列 |
※「detailCommandType」の詳細は「6-2 検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）」」を参照 |
△ | |||||
| 決済センターへの要求日時 | cvspayRequestDatetime | 文字列14文字 | 決済センターへの要求日時が格納されます。 YYYYMMDDhhmmss形式 |
△ | |||||
| 決済センターからの返戻日時 | cvspayResponseDatetime | 文字列14文字 | 決済センターからの返戻日時が格納されます。 YYYYMMDDhhmmss形式 |
△ | |||||
結果通知電文
結果通知電文の概要
実装方法の詳細につきましては、弊社より提供しているサンプルプログラムをご参照ください。
-
機能概要
決済サーバーから店舗システムへ決済の結果通知を行います。
通知は、HTTPのPOSTを利用します。※プロトコルはHTTP（Port：80）、HTTPS（Port：443）に対応しています。
処理の概要については『結果通知受信処理』をご参照ください。 -
HMACについて
POSTにてデータを通知するとき、リクエストヘッダーにHMACを設定します。
また、HMAC値は、リクエストボディから算出します。
アルゴリズムは「HmacSHA256」が設定されます。表2 リクエストヘッダーに設定するHMACフィールド フィールド名 設定値 content-hmac h={アルゴリズム名};s={CCID};v={HMAC値} -
結果通知受信処理結果について
決済サーバーからの通知に対して店舗側システムがHTTPステータスコード"200"を返戻した場合、受信処理が正常に
終了したものと判断します。"200"以外のコードを返した場合は、受信失敗と判断し、一定期間、通知を繰り返します。※返戻した場合、受信処理が正常に終了したものと判断します。
ファミペイの結果通知電文
ファミペイにおける結果通知電文の通知タイミングは、ファミペイ側で決済申込みが成立したタイミング（決済サーバーからの要求が成功したタイミング）となります。この時点では、店舗側の完了画面URLへの遷移はまだ行われていません。
消費者が画面遷移の途中で離脱した場合や、通信環境の問題で画面遷移時にタイムアウトが発生した場合には、最終遷移先の完了画面URLまで到達しない場合がありますので、このような場合にも、決済サーバーからの通知を店舗側システムで受信して頂くことで、決済が成立したことを検知することができます。
| No. | 通知機能 | 通知タイミング | 注意事項 |
|---|---|---|---|
| 1 | 決済申込完了通知 （Authorize） ※ブラウザを介する通信 |
決済申込が成立（成功）したタイミングで送信されます。 | 決済申込が失敗した場合は送信されません。 |
以下に、ファミペイの結果通知項目を示します。
| 項番 | フィールド名 | 項目名 | 書式・制限 | 説明 |
|---|---|---|---|---|
| 1 | numberOfNotify | 通知件数 | 半角数字4桁以内 | 1度に通知可能な件数は100件、 101件以上は次回通知 |
| 2 | pushTime | 送信時刻 | 半角数字14桁 | 決済サーバーから通知した時刻 yyyyMMddHHmmss形式 |
| 3 | pushId | 識別ID | 半角数字8桁 | プッシュ処理を行うたびに採番されるID。 注）他の決済サービスで使用されたIDと重複する場合があります。 |
| 通知件数分下記の項番（4～11）を繰り返します。なお、フィールド名の後ろに4ケタの連番（0000～0999）を付与する。 | ||||
| 4 | orderId | 取引ID | 半角英数字100桁以内 | 取引ID |
| cvspayType | cvspay種別 |
※右記の説明を参照 |
利用するcvspay種別
※現在は、"famipay"（ファミペイ）のみ |
|
| 9 | cvspayOrderId | 決済事業者取引番号 | 半角英数字12桁以内 | 決済事業者側で発番された取引番号 |
| 5 | txnType | トランザクションタイプ | ※右記の説明を参照 | "Authorize"：決済申込完了通知 |
| 6 | txnTime | 処理日時 | 半角数字14桁 | yyyyMMddHHmmss形式 |
| 7 | vResultCode | 詳細結果コード | 半角英数字4桁 | 処理結果コードの詳細は、 『結果コード一覧』をご参照ください。 |
| 8 | mstatus | 処理ステータス | 半角英数字8桁以内 | "success"：正常終了 （fairureの場合は通知されません。） |
| 10 | dummy | ダミー決済フラグ | 半角数字1桁 | ダミー取引を示す場合は"1"を設定します。 |
- pushId（識別ID）は、他の決済サービスで使用されたIdと重複する場合がありますので、ユニークキーとして処理しないようにしてください。
- 項目の並び順は、必ずしも表の順序とは一致しません。
その他 補足事項
キャンセルに関する注意事項
キャンセルの要求可能期間
ファミペイにおける、キャンセルの要求可能期間を下表に示します。
| 要求種類 | 要求可能期間 |
|---|---|
| キャンセル | 決済申込成功から60日間 |
検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）
決済サーバーでは、システム内部データとして詳細コマンド（処理要求の種類）と詳細な決済状態（その取引がどのような状態にあるか）を管理しています。
通常の運用では、店舗様システムではこれらの内部情報を利用する必要はありませんが、店舗様システムにおいて取引の状態検索が必要なケースや、障害等のお問い合わせ時の参照情報として、これらの内部データをSearchコマンドで公開しています。
下表にSearchコマンドにて利用可能な内部データの一覧を示します。
| 詳細コマンドタイプ | コマンド成功時の詳細オーダー決済状態 | ||
|---|---|---|---|
| 論理名 | 値 | 論理名 | 値 |
| 決済認可 | PreAuth | 決済申込 | Init |
| 決済中止 | QuitAuth | 決済中止 | QuitAuth |
| 与信売上 | AuthCapture | 与信売上 | AuthCapture |
| 取消（与信売上） | VoidAuthCapture | 取消（与信売上） | VoidAuthCapture |
注）一覧に記載していないコマンドタイプと状態も存在します。
導入・テストに関する補足
決済サーバーに接続し、テストを実施するための各種手続き・手順の詳細につきましては、『導入テストガイド』を参照してください。
決済申込時の画面遷移をシミュレートする
弊社では、ファミペイのテストのための疑似環境を提供しています。
Authorizeコマンドの結果として返戻されたリダイレクトURL（CvspayAuthorizeResponseDto.redirectUrl）に消費者のブラウザを遷移させると、以下の疑似環境が表示されます。
ファミペイの認証画面のイメージが表示されますので、そのまま「ログイン」ボタンをクリックして次の画面に遷移します。
ファミペイの注文内容確認画面が表示されます。
赤枠の設定項目にシミュレートしたい内容を設定し、確定ボタンをクリックすることで以降の遷移を確認することができます。
設定内容と遷移先についての対応表を以下に記載します。
| 結果選択 | リスト選択 （失敗時のエラー内容選択） |
遷移先 |
|---|---|---|
| 成功 | - | 加盟店の決済完了画面に遷移します。 |
| 失敗 | 残高不足エラー | 決済時にエラーとなる場合のシミュレートです。 残高不足エラーメッセージが表示され、キャンセルボタンのみ表示されます。 キャンセルボタンをクリックすると、加盟店のキャンセル画面へ遷移します。 |
| 不正パラメータ （AuthorizeNotify） |
パラメータエラーにより、決済エラーとなる場合のシミュレートです。 疑似環境のシステムエラー画面に遷移します。 |
決済申込・取消コマンドのエラーをシミュレートする
AuthorizeとCancelコマンドの要求金額（"amount"）の下一桁の値を調整することで、意図的にエラーを発生させることができます。
要求金額の下一桁と、返戻されるvResultCodeの対応表を以下に記載します。
| 金額の 下1桁 |
Authorize （申込み） |
Cancel （取消） |
|---|---|---|
| 0 | 4001（成功） | 4001（成功） |
| 1 | 4GD1（エラー） | |
| 2 | 4ED1（エラー） | |
| 3 | 4001（成功） | |
| 4 | ||
| 5 | ||
| 6 | 4GD3（エラー） | |
| 7 | 4ED2（ペンディング） | |
| 8 | 4001（成功） | |
| 9 |
返戻されるエラーコード（vResultCode）につきましては、今後、予告なしに変更させて頂く場合がございます。