銀聯（UPOP）

本ガイドについて

本ガイドの内容

本ガイドは、(株)DGフィナンシャルテクノロジーが提供するVeriTrans4Gを利用するための専用ソフトウェアMDK（Merchant Development Kit）をインターネット店舗などに導入する開発者向けのガイドです。VeriTrans4G銀聯ネット決済（UPOP）にて使用する電文のインターフェース詳細について記載しています。
VeriTrans4Gの詳細については、『VeriTrans4G 開発ガイド』を参照して下さい。
尚、インターフェース詳細は、決済サービス毎に提供していますので、当該決済サービスのインターフェース詳細を参照して下さい。

インターフェース詳細

本章では、各決済にて使用する電文（Dto）について説明します。以下の表に記載されているフィールドは、店舗様にて利用可能なフィールドです。

各電文（Dto）には、以下の表に記載されていないフィールドが定義されている場合がありますが、以下の表に記載されていないフィールドは店舗様では使用することはできません。

共通

「設定」欄の内容は以下の通りです。

要求電文 ...
必須項目：○　　任意項目：△　　設定不可：×　　その他条件付：※、※n（条件は説明欄、または欄外に記入）

応答電文 ...
必ず返戻：○　　処理成功時のみ返戻：△　　返戻なし：×　　その他条件付：※
orderId（取引ID）について

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

与信

要求電文：UpopAuthorizeRequestDto

要求電文：UpopAuthorizeRequestDto
フィールド名	項目名	書式・制限	説明	設定
orderId	取引ID	半角英数字100桁以内	上記「orderId（取引ID）について」参照	○
amount	決済金額	半角数字12桁以内	決済金額（日本円） 1 以上 999,999,999,999 以下	○
withCapture	売上フラグ	右記参照	"true"：与信・売上 "false"：与信のみ ※ 指定が無い場合は、デフォルト値（与信のみ）が指定されます。	△
termUrl	決済結果戻り先URL	URLに使える文字256桁以内	決済完了後に、店舗側へ遷移を戻すためのURLを指定	○
customerIp	消費者IPアドレス	IPの使える文字40桁以内	消費者側のIPアドレスを指定（例：111.111.111.111） ※IPV6の形式も対応しています。	○

応答電文：UpopAuthorizeResponseDto

応答電文：UpopAuthorizeResponseDto
フィールド名	項目名	書式・制限	説明	設定
serviceType	サービスタイプ	右記参照	要求電文を送信した決済サービスタイプ "upop"	○
mstatus	処理結果コード	半角英数字32文字以内	"success" ：正常終了 "failure" ：異常終了	○
vResultCode	詳細結果コード	半角英数16桁	処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。詳細は『結果コード一覧』を参照下さい。	○
merrMsg	エラーメッセージ	文字列300桁以内	処理結果を日本語で表示します。	○
custTxn	トランザクションID(取引毎につけるID)	文字列100桁以内	決済サーバーがオーダー（取引ID）と紐付ける為に採番するID	○
marchTxn	電文ID	文字列100桁以内	決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。	○
orderId	取引ID	半角英数字100桁以内	決済要求時に店舗様にて任意に採番し送信された取引ID	○
txnVersion	MDKバージョン	文字列5 桁	電文のバージョン問題発生時などに用いますが、通常ご利用になることはありません。	○
entryForm	UPOPリダイレクト用HTMLフォーム文字列	文字列4096桁以内	銀聯へリダイレクトするためのHTML この文字列はURLエンコードされています。銀聯の画面に自動遷移するためのJavaScript を含みますので、URLデコード後の文字列をそのまま消費者のブラウザに返戻してください。返戻するコンテンツの文字コードはUTF-8として返戻する必要があります。	△

結果リダイレクト

リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(POST)される内容

リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(POST)される内容
フィールド名	項目名	書式・制限	説明	設定
serviceType	サービスタイプ	右記参照	要求電文を送信した決済サービスタイプ "upop"	○
authInfo	認証情報	右記参照	受信データが自店舗のデータかどうかを検証するための文字列。 (弊社から提供するサンプルに当文字列による店舗認証の方法が入っていますので参照してください)	○
mstatus	処理結果コード	半角英数字32文字以内	"success" ：正常終了 "failure" ：異常終了 "pending" ：保留状態	○
vResultCode	詳細結果コード	半角英数16桁	処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。詳細は『結果コード一覧』を参照下さい。	○
merrMsg	エラーメッセージ	文字列300桁以内	処理結果を日本語で表示します。	○
custTxn	トランザクションID(取引毎につけるID)	文字列100桁以内	決済サーバーがオーダー（取引ID）と紐付ける為に採番するID	○
orderId	取引ID	半角英数字100桁以内	決済要求時に店舗様にて任意に採番し送信された取引ID	○
txnDatetimeJp	決済時刻（日本時間）	半角数字14 桁固定	決済日時（日本時間） YYYYMMDDhhmmssの形式（例 20130728181905）	△
txnDatetimeCn	決済時刻（中国時間）	半角数字14 桁固定	決済日時（中国時間） YYYYMMDDhhmmssの形式（例 20130728171905）	△
capturedAmount	元売上金額	半角数字12桁以内	元売上金額	△
settleAmount	清算金額	半角数字12桁以内	清算金額	△
settleDate	清算日付	右記参照	清算日付 MMDD の形式（例0927）	△
settleCurrency	清算通貨種類	半角数字3桁	清算通貨種類 392：日本円（固定）	△
settleRate	清算レート	半角数字8桁	清算レート ※清算レートの仕様は、「3-1銀聯ネット決済（UPOP）注意事項」の2)を参照。	△
upopOrderId	決済センターとの取引ID	半角英数字20桁以内	決済サーバーが、決済センター向けに発番するID ※拡張項目のため、ご利用の際には弊社までお問い合わせください。	※

売上

要求電文：UpopCaptureRequestDto

要求電文：UpopCaptureRequestDto
フィールド名	項目名	書式・制限	説明	設定
orderId	取引ID	半角英数字100桁以内	決済請求、与信完了時に採番した取引ID	○
amount	決済金額	数字12桁以内	決済金額（日本円）与信時に設定した金額以下、かつ1 以上 999,999,999,999 以下	○

応答電文：UpopCaptureResponseDto

応答電文：UpopCaptureResponseDto
フィールド名	項目名	書式・制限	説明	設定
serviceType	サービスタイプ	右記参照	要求電文を送信した決済サービスタイプ "upop"	○
mstatus	処理結果コード	半角英数字32文字以内	"success" ：正常終了 "failure" ：異常終了 "pending" ：保留状態	○
vResultCode	詳細結果コード	半角英数16桁	処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。詳細は『結果コード一覧』を参照下さい。	○
merrMsg	エラーメッセージ	文字列300桁以内	処理結果を日本語で表示します。	○
custTxn	トランザクションID(取引毎につけるID)	文字列100桁以内	決済サーバーがオーダー（取引ID）と紐付ける為に採番するID	○
marchTxn	電文ID	文字列100桁以内	決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。	○
orderId	取引ID	半角英数字100桁以内	決済要求時に店舗様にて任意に採番し送信された取引ID	○
txnVersion	MDKバージョン	文字列5 桁	電文のバージョン問題発生時などに用いますが、通常ご利用になることはありません。	○
txnDatetimeJp	決済時刻（日本時間）	半角数字14 桁固定	決済日時（日本時間） YYYYMMDDhhmmssの形式（例 20130728181905）	△
txnDatetimeCn	決済時刻（中国時間）	半角数字14 桁固定	決済日時（中国時間） YYYYMMDDhhmmssの形式（例 20090728171905）	△
capturedAmount	売上金額	半角数字12桁以内	売上金額	△
remainingAmount	返品後の金額	半角数字12桁以内	通常ご利用になることはありません。	△
settleAmount	清算金額	半角数字12桁以内	清算金額	△
settleDate	清算日付	右記参照	清算日付 MMDD の形式（例 0927）	△
settleCurrency	清算通貨種類	半角数字3桁	清算通貨種類 392：日本円（固定）	△
settleRate	清算レート	半角数字8桁	清算レート ※清算レートの仕様は、「3-1銀聯ネット決済（UPOP）注意事項」の2)を参照。	△
upopOrderId	決済センターとの取引ID	半角英数字20桁以内	決済サーバーが、決済センター向けに発番するID ※拡張項目のため、ご利用の際には弊社までお問い合わせください。	※

キャンセル

要求電文：UpopCancelRequestDto

要求電文：UpopCancelRequestDto
フィールド名	項目名	書式・制限	説明	設定
orderId	取引ID	半角英数字100桁以内	決済請求、与信・売上完了時に採番した取引ID	○

応答電文：UpopCancelResponseDto

応答電文：UpopCancelResponseDto
フィールド名	項目名	書式・制限	説明	設定
serviceType	サービスタイプ	右記参照	要求電文を送信した決済サービスタイプ "upop"	○
mstatus	処理結果コード	半角英数字32文字以内	"success" ：正常終了 "failure" ：異常終了 "pending" ：保留状態	○
vResultCode	詳細結果コード	半角英数16桁	処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。詳細は『結果コード一覧』を参照下さい。	○
merrMsg	エラーメッセージ	文字列300桁以内	処理結果を日本語で表示します。	○
custTxn	トランザクションID(取引毎につけるID)	文字列100桁以内	決済サーバーがオーダー（取引ID）と紐付ける為に採番するID	○
marchTxn	電文ID	文字列100桁以内	決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。	○
orderId	取引ID	半角英数字100桁以内	決済要求時に店舗様にて任意に採番し送信された取引ID	○
txnVersion	MDKバージョン	文字列5 桁	電文のバージョン問題発生時などに用いますが、通常ご利用になることはありません。	○
txnDatetimeJp	決済時刻（日本時間）	半角数字14 桁固定	決済日時（日本時間）　YYYYMMDDhhmmss の形式（例 20130728181905）	△
txnDatetimeCn	決済時刻（中国時間）	半角数字14 桁固定	決済日時（中国時間）　YYYYMMDDhhmmss の形式（例 20130728171905）	△
capturedAmount	元売上金額	半角数字12桁以内	与信（売上は未実行の場合）に対するキャンセルの場合：　"0" 与信（売上同時）、与信後の売上に対するキャンセルの場合：売上金額	△
remainingAmount	返品後の金額	半角数字12桁以内	返品後の金額	△
settleAmount	清算金額	半角数字12桁以内	清算金額	△
settleDate	清算日付	右記参照	清算日付 MMDD の形式（例 0927）	△
settleCurrency	清算通貨種類	半角数字3桁	清算通貨種類 392：日本円（固定）	△
settleRate	清算レート	半角数字8桁	清算レート ※清算レートの仕様は、「3-1銀聯ネット決済（UPOP）注意事項」の2)を参照。	△
upopOrderId	決済センターとの取引ID	半角英数字20桁以内	決済サーバーが、決済センター向けに発番するID ※拡張項目のため、ご利用の際には弊社までお問い合わせください。	※

返金

与信後にCapture（売上）を実施した取引については、Refund（返金）が可能です。
ただし、Capture（売上）を実施した当日は、Cancel（キャンセル）を利用してください。（売上当日に返金処理を行った場合、失敗する可能性があります。）
返金が可能な期間は、売上実施日から180日間となります。

※与信時の売上フラグが"true"（与信・売上）の場合には、申込みが成立した日から180日間となります。

要求電文：UpopRefundRequestDto

要求電文：UpopRefundRequestDto
フィールド名	項目名	書式・制限	説明	設定
orderId	取引ID	半角英数字100桁以内	決済請求、売上完了時に採番した取引ID	○
amount	決済金額	半角数字12桁以内	返金金額（日本円） ※一部キャンセルも可能	○

応答電文：UpopRefundResponseDto

応答電文：UpopRefundResponseDto
フィールド名	項目名	書式・制限	説明	設定
serviceType	サービスタイプ	右記参照	要求電文を送信した決済サービスタイプ "upop"	○
mstatus	処理結果コード	半角英数字32文字以内	"success" ：正常終了 "failure" ：異常終了 "pending" ：保留状態	○
vResultCode	詳細結果コード	半角英数16桁	処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。詳細は『結果コード一覧』を参照下さい。	○
merrMsg	エラーメッセージ	文字列300桁以内	処理結果を日本語で表示します。	○
custTxn	トランザクションID(取引毎につけるID)	文字列100桁以内	決済サーバーがオーダー（取引ID）と紐付ける為に採番するID	○
marchTxn	電文ID	文字列100桁以内	決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。	○
orderId	取引ID	半角英数字100桁以内	決済要求時に店舗様にて任意に採番し送信された取引ID	○
txnVersion	MDKバージョン	文字列5 桁	電文のバージョン問題発生時などに用いますが、通常ご利用になることはありません。	○
txnDatetimeJp	決済時刻（日本時間）	半角数字14 桁固定	決済日時（日本時間）　YYYYMMDDhhmmss の形式（例 20130728181905）	△
txnDatetimeCn	決済時刻（中国時間）	半角数字14 桁固定	決済日時（中国時間）　YYYYMMDDhhmmss の形式（例 20090728171905）	△
capturedAmount	元売上金額	半角数字12桁以内	与信（売上同時）、与信後の売上に対する返金の場合の元売上金額	△
remainingAmount	返品後の金額	半角数字12桁以内	返品後の金額	△
settleAmount	清算金額	半角数字12桁以内	清算金額	△
settleDate	清算日付	右記参照	清算日付 MMDD の形式（例 0927）	△
settleCurrency	清算通貨種類	半角数字3桁	清算通貨種類 392：日本円（固定）	△
settleRate	清算レート	半角数字8桁	清算レート ※清算レートの仕様は、「3-1銀聯ネット決済（UPOP）注意事項」の2)を参照。	△
upopOrderId	決済センターとの取引ID	半角英数字20桁以内	決済サーバーが、決済センター向けに発番するID ※拡張項目のため、ご利用の際には弊社までお問い合わせください。	※

結果通知

銀聯ネット決済（UPOP）では、与信、売上、キャンセル、返金それぞれの処理について、店舗様へ結果通知を送信します。

下表に、電文項目の詳細を示します。
結果通知に関するサービス共通の仕様については、『開発ガイド』を併せてご参照ください。

項番	フィールド名	項目名	書式・制限	説明
1	numberOfNotify	通知件数	半角数字4桁以内	1度に通知可能な件数は100件 101件以上は次回通知
2	pushTime	送信時刻	半角数字14桁	決済サーバーから通知した時刻 YYYYMMDDhhmmss形式
3	pushId	識別ID	半角数字8桁	プッシュ処理を行うたびに採番されるID 注）他の決済サービスで使用されたIDと重複する場合があります。
通知件数分下記の項番（4～12）を繰り返す。尚、フィールド名の後ろに4ケタの連番（0000～0999）を付与する。
4	orderId	取引ID	半角英数字100桁以内	取引ID
5	txnType	サービスコマンド	半角英数字20桁以内右記参照	"Authorize", "Capture" , "Refund", "Cancel" ※与信／与信同時売上の場合は"Authorize"が、与信後売上の場合は"Capture"が返戻されます。
6	mstatus	処理結果コード	半角英数字32文字以内	"success"：正常終了 "failure"：異常終了
7	traceNumber	システム追跡番号	半角数字6桁	UPOPより発行されるシステム追跡番号
8	traceTime	認証サービス日時	半角数字10桁固定	MMDDhhmmss形式（中国時間）（例 0928171905）
9	settleAmount	清算金額	半角数字12桁以内	清算金額
10	settleDate	清算日付	半角数字4桁	清算日付 MMDD の形式（例 0927）
11	settleRate	清算レート	半角数字8桁	（予約項目）
12	dummy	ダミー決済フラグ	半角数字1桁	ダミー取引の場合："1"、本番取引場合："0"
13	vResultCode	詳細結果コード	文字列16桁	処理結果を詳細に表すコード詳細は『結果コード一覧』を参照下さい。 ※拡張項目のため、ご利用の際には弊社までお問い合わせください。
14	upopOrderId	決済センターとの取引ID	半角英数字20桁以内	決済サーバーが、決済センター向けに発番するID ※拡張項目のため、ご利用の際には弊社までお問い合わせください。

(注意事項)

通常、各種決済の成功・失敗のステータス判明後の5分以内に店舗様へ結果通知を送信しますが、一部の特殊取引（ネットワーク通信問題などによって、銀聯側のステータスが判断できないもの等）については、翌日に行われる銀聯センターと決済サーバーとのマッチング処理にてステータスが判明しますので、翌日以降に結果通知が送信される場合があります。
通常ケースでは、結果通知の送信は1回だけ行われますが、取引の翌日に銀聯から受信した清算データと、決済サーバー側の取引データとの突合処理によって差異が判明した場合は、結果通知を再度送信する場合があります。
pushId（識別ID）は、他の決済サービスで使用されたIdと重複する場合がありますので、ユニークキーとして処理しないようにしてください。
項目の並び順は、必ずしも表の順序とは一致しません。

その他　補足事項

注意事項

清算通貨および清算レートについて

各I/Fで返却している「清算通貨」は、392（JPY）固定となります。そのため、消費者への中国元での請求については、消費者自身で銀聯（UPOP）側のサイトで確認する必要があります。
また、為替レートが事前に取得する仕組みが提供されていないため、中国元の金額は銀聯（UPOP）のサイトにリダイレクトした後に分かります。
各I/Fの「清算レート」の仕様は、以下のとおりです。
1桁目：小数の桁数
2～8桁目：実際の清算レート
例）「30001000」の場合、小数の桁数が"3"となっているため清算レートは「1.000」になります。

支払い期限について

消費者の支払い期限は、UPOPの決済画面に遷移してから30分です。30分を超えて支払いを行うと、UPOP側でエラーとなります。

与信・売上について

銀聯カードはクレジットカードよりデビットカードとしての発行枚数が多いため、与信のみの場合、失敗する可能性があります。与信同時売上の実装をご検討ください。
銀聯カードの与信有効期限は30日です。与信有効期限内であってもイシュアの運用によっては売上エラーになる場合があります。その場合には弊社にて売上処理を行いますが、処理を行うにあたっては利用契約に則り、取引に関する必要書類をご提出頂く必要があります。