VeriTrans4G インターフェース詳細 ～Alipay 決済～

VeriTrans4G インターフェース詳細～Alipay 決済～
Ver. 1.2.0 （2024 年 6 月～）

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

内容第1章

本ドキュメントについて ......................................................................................................................................................................................................... 3

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

インターフェース詳細 ............................................................................................................................................................................................................ 62-1 共通 ......................................................................................................................................................................................................................................................................62-2 与信同時売上........................................................................................................................................................................................................................................................72.2.1 要求電文：AlipayAuthorizeRequestDto ................................................................................................................................................................................................................................... 7
2.2.2 応答電文：AlipayAuthorizeResponseDto ................................................................................................................................................................................................................................. 82-3 結果 ......................................................................................................................................................................................................................................................................92.3.1 リダイレクト受信内容 ： 決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(POST)される内容 ....................................................................................................................................... 92-4 返金申込............................................................................................................................................................................................................................................................. 102.4.1 要求電文 ： AlipayRefundRequestDto ..................................................................................................................................................................................................................................10
2.4.2 応答電文 ： AlipayRefundResponseDto ................................................................................................................................................................................................................................ 11

2-5 結果通知............................................................................................................................................................................................................................................................. 12

第3章

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

3-1 注意事項............................................................................................................................................................................................................................................................. 142

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

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

tech-support@veritrans.jp

1-3 改訂履歴
2017/04 ：Ver1.0.0 リリース※

以下、「VeriTrans3G インターフェース詳細 ～ Alipay 決済 ～」 Ver 2.1.0 からの更新分を記載します。
2.2.1 要求電文：AlipayAuthorizeRequestDto の amount の上限金額の説明を変更。併せて関連箇所の記載内容を変更。
2.2.2 応答電文：AlipayAuthorizeResponseDto の entryForm の説明を追加
2.2.2 応答電文：AlipayAuthorizeResponseDto の buyerChargedAmountCny の桁数を変更
2-3 Alipay 決済 返金申込 に、返金可能期間に関する説明を追加

2017/08 ：Ver1.0.1 リリース
2-5 結果通知（Alipay 決済）のオンライン決済の結果通知の通知タイミングに関する説明を修正。
2018/02 ：Ver1.0.2 リリース
2.2.1 要求電文：AlipayAuthorizeRequestDto に responseType を追加
3

2-5 Alipay 決済 確認 を追加
2-6 結果通知（Alipay 決済）の「通知件数」の「説明」を修正（1 度に通知可能な件数を 1,000 件から 100 件に変更）
3-2 Alipay バーコード決済（店舗スキャン型）決済要求の応答時間について 説明文を修正。与信同時売上要求時のレスポンスタイプ別の説明図を追加。
2018/06 ：Ver1.0.3 リリース
2.2.1 要求電文：AlipayAuthorizeRequestDto に storeId と storeName を追加
2.4.1 要求電文：AlipayRefundRequestDto の amount の説明に、返金時のレートについての説明を追加
3-1 Alipay 決済 注意事項 に、返金結果の確定が遅れる場合の説明を追加
3-1 Alipay 決済 注意事項 に、返金時のレートについての説明を追加
2018/08 ：Ver1.0.4 リリース
章タイトルから「Alipay 決済」という表現を削除（冗長さの排除）
2.4 返金申込 返金が可能な期間を 90 日から 365 日に変更
2.4.1 要求電文：AlipayRefundRequestDto の reason の説明を補足
2018/09 ：Ver1.0.5 リリース
2.2.1 要求電文：AlipayAuthorizeRequestDto に deviceType を追加
2019/04 ：Ver1.0.6 リリース
2-6 結果通知 項目の並び順について追記
2019/08 ：Ver1.0.8 リリース
2.2.1 要求電文：AlipayAuthorizeRequestDto の storeId の書式制限を 32 桁以内から 64 桁以内に変更
2-1 共通 の決済種別の説明に静的型を追加
2-6 QR コード生成 を追加
3-3 Alipay バーコード決済（消費者スキャン型支払期限について） を修正
3-1 5) バーコード決済（店舗スキャン型）の決済申込がご利用いただけない時間帯に関する注意事項を削除
2020/01 ：Ver1.0.9 リリース
2-7 結果通知にバーコード決済（消費者スキャン型）で通知されるを txnTime を追加。
2022/12 ：Ver1.1.0 リリース
2.3.1 リダイレクト受信内容 に pending に関する補足を追加。
2.4.2 応答電文：AlipayRefundResponseDto の mstatus の説明に pending を追加。
2023/06 ：Ver1.1.1 リリース
2.2.1 要求電文：AlipayAuthorizeRequestDto の deviceType に関する以下の注意事項を削除
注）このパラメータを利用される場合には、弊社までご連絡ください。
2-7 結果通知に結果通知先 URL の設定箇所の説明を補足
2023/09 ：Ver1.1.2 リリース
2-7 結果通知 取引翌日の結果の訂正について詳細を追記。また記述の順番と構成を調整。
2023/12 ：Ver1.1.3 リリース
2-7 結果通知の URL は MAP の「各種設定変更」画面で設定する旨を追記

4

2024/06 ：Ver1.2.0 リリース
バーコード決済についての記載を削除（本書は、非対面オンライン決済専用の仕様書とする）

5

第2章 インターフェース詳細
本章では、各決済にて使用する電文（Dto）について説明します。以下の表に記載されているフィールドは、店舗様にて利用可能なフィールドです。
各電文（Dto）には、以下の表に記載されていないフィールドが定義されている場合がありますが、以下の表に記載されていないフィールドは店舗様では使用することはできません。

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

任意項目：△

設定不可：×

応答電文 … 必ず返戻：○

処理成功時のみ返戻：△

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

返戻なし：×

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

6

2-2 与信同時売上
2.2.1 要求電文：AlipayAuthorizeRequestDto
要求電文：AlipayAuthorizeRequestDto
フィールド名

項目名

書式・制限

説明

orderId

取引 ID

半角英数字100桁以内「2-1 共通」の「orderId（取引 ID）について」を参照

amount

決済金額

半角数字 7 桁以内

決済金額を日本円または中国元で指定。

設定○○

ただし、中国元(CNY)換算で上限金額はオンライン決済の場合：300,000 元
また、通貨に中国元を指定する場合、amount には取引金額を 100 倍した値を指定します。（amount=決済金額×100）（例 日本円：1 円の場合は 1 を指定します。
中国元：1.99 元の場合は 199 を指定します。）
currency

通貨

右記参照"JPY"： 日本円

successUrl

決済完了後戻り URL

URL に使える文字 256 桁以内

決済が成功した場合に、店舗側へ遷移を戻す為の URL を指定

errorUrl

決済エラー時戻り URL

URL に使える文字 256 桁以内

決済が失敗した場合に、店舗側へ遷移を戻す為の URL を指定

commodityName

商品名

文字列 100 桁以内

商品名を指定○"CNY"： 中国元（オンライン決済のみ）○○○

この情報はオンライン決済では Alipay の決済ページに表示されます。
commodityDescription

商品詳細

文字列 200 桁以内

商品の詳細を指定△

この情報は Alipay の決済ページに表示されます。
withCapture

売上フラグ

右記参照

"true"： 与信・売上（設定可能な値は"true"のみです）△※設定しない場合のデフォルト値は"true"です。
payType

決済種別

半角数字

決済種別を指定△"0"：オンライン決済※未指定の場合は、"0"：オンライン決済
deviceType

デバイスタイプ

半角数字

デバイスタイプを指定△"0"：PC"1"：スマートフォン※payType が"0":オンライン決済の場合に有効※未指定の場合は、"0"：PC※このパラメータを指定することで消費者の利用環境に応じて画面表示を変更することが可能となります。
7

2.2.2 応答電文：AlipayAuthorizeResponseDto
応答電文：AlipayAuthorizeResponseDto
フィールド名

項目名

書式・制限

serviceType

サービスタイプ

右記参照

mstatus

処理結果コード

半角英数字 32 文字以内

vResultCode

詳細結果コード

半角英数 16 桁

説明
要求電文を送信した決済サービスタイプ

設定○"alipay"：Alipay 決済"success" ： 正常終了
"failure"○： 異常終了

処理結果を詳細に表すコード○

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

エラーメッセージ

文字列 300 桁以内

処理結果を日本語で表示します。

custTxn

トランザクション ID(取引文字列100桁以内

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

文字列 100 桁以内

決済サーバーにて決済処理電文（内部処理も含む）毎に付与する ID○毎に付ける ID)
marchTxn

電文 ID

１つの取引 ID に対して、複数の ID が付与されます。
orderId

取引 ID

半角英数字 100 桁以内

決済要求時に店舗様にて任意に採番し送信された取引 ID

txnVersion

MDK バージョン

文字列 5 桁

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

Alipay リダイレクト用
HTML フォーム文字列

文字列 4096 桁以内

Alipay へリダイレクトするための HTML△

この文字列は URL エンコードされています。
Alipay の画面に自動遷移するための JavaScript を含みますので、URL デコード後の文字列をそのまま消費者のブラウザに返戻してください。
返戻するコンテンツの文字コードは UTF-8 として返戻する必要があります。

8

2-3 結果
2.3.1 リダイレクト受信内容 ： 決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(POST)される内容※オンライン決済の場合のみ、リダイレクトされます
リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(POST)される内容
フィールド名
serviceType

項目名
サービスタイプ

書式・制限
右記参照

説明
要求電文を送信した決済サービスタイプ

設定○"alipay"：Alipay 決済
authInfo

認証情報

右記参照

受信データが自店舗のデータかどうかを検証するための文字列○(弊社から提供するサンプルに当文字列による店舗認証の実装方法が含まれていますので参照してください)
mstatus

処理結果コード

半角英数字 32 文字以内

"success" ： 正常終了
"failure"○： 異常終了"pending" ： 保留状態(※)
vResultCode詳細結果コード

半角英数 16 桁

処理結果を詳細に表すコード○

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

エラーメッセージ

文字列 300 桁以内

処理結果を日本語で表示します。

custTxn

トランザクション ID(取文字列100桁以内

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

引毎に付ける ID)
orderId

取引 ID

半角英数字 100 桁以内

決済要求時に店舗様にて任意に採番し送信された取引 ID

centerTradeId

決済センターとの取引

文字列 64 文字以内

決済サーバーが発番する ID○○IDsettleAmount

清算金額

半角数字 7 桁以内

清算金額

settleCurrency

清算通貨種類

半角文字 3 桁

清算通貨種類△△"JPY"：日本円（固定）(※) pending について

ブラウザが Alipay のサイトから弊社 URL に戻ってきた時点で、決済サーバーが Alipay からの結果通知を受信してない場合は、Alipay に決済結果の問合せを行っています。
その問合せ結果が何らかの問題（一時的な通信の問題等）で正常に取得できなかった場合に pending となります。



pending となった時点では加盟店様への結果通知（PUSH 通知）は送信しませんが、弊社側で結果が確認できたタイミングで結果通知（success または failure）を送信します。
ただし、状況により翌日の運用対処となる可能性があり、その場合には結果通知を送信できないことがあります。
9結果通知が送信できない場合には、テクニカルサポートまたはカスタマーサポートからご連絡させていただきます。
pending が発生した場合は、その時点で失敗扱いとしていただき、後から成功していたことが確認できた場合には、返金を行っていただくことをお勧めします。
お客様には一時的な障害のため決済が失敗したことと、万が一成立している場合には後ほど返金されることをご案内ください。

2-4 返金申込
返金が可能な期間は、支払い日から 365 日間となります。また、決済金額の残高が 0 円になるまで繰り返し実行できます。


オンライン決済では、返金申込みという扱いになります。翌日以降、返金自体が成功か失敗かの結果が得られます。通貨は、Authorize（与信同時売上方式）時に指定した通貨と同じものになります。

2.4.1 要求電文 ： AlipayRefundRequestDto
要求電文 ： AlipayRefundRequestDto
フィールド名

項目名

書式・制限

説明

orderId

取引 ID

半角英数字 100 桁以内

決済請求、与信完了時に採番した取引 ID を指定

amount

取引金額

半角数字 7 桁以内返金する金額を指定

設定○○※一部キャンセルも可能
返金における通貨は、与信同時売上の時に指定した通貨と同じものを指定します。
※中国元の場合に指定する値は、与信同時売上時と同様、取引金額を 100 倍した値を指定してください。
※返金時の為替レートは、購入時のレートが適用されます。
reason理由

文字列 80 桁以内

返金の理由を指定○

返金理由は、Alipay が提供している消費者向けの管理画面に表示されます。
返金理由は、中国語または英語での指定を推奨します。

10

2.4.2 応答電文 ： AlipayRefundResponseDto
応答電文 ： AlipayRefundResponseDto
フィールド名
serviceType

項目名
決済サービスタイプ

書式・制限
右記参照

説明
要求電文を送信した決済サービスタイプ

設定○"alipay"：Alipay 決済
mstatus

処理結果コード

半角英数字 32 文字以内

"success"：正常終了○"failure"：異常終了"pending"：保留状態（オンライン決済では pending は発生しません）
vResultCode

詳細結果コード

半角英数字 16 文字

処理結果を詳細に表すコード○

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

エラーメッセージ

文字列 300 桁以内

処理結果を日本語で表示します。

marchTxn

電文 ID

文字列 100 桁以内

決済サーバーにて決済処理電文（内部処理も含む）毎に付与する ID

orderId

取引 ID

半角英数字

custTxn

トランザクション ID(取○○１つの取引 ID に対して、複数の ID が付与されます。
決済要求時に店舗様にて任意に採番し送信された取引 ID○

文字列 100 桁以内

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

文字列 5 桁

電文のバージョン○

100 文字以内
引毎に付ける ID)
txnVersion

MDK バージョン

問題発生時などに用いますが、通常ご利用になることはありません。
centerTradeId

決済センターとの取引

文字列 64 文字以内

決済サーバーが発番する ID

△ID

11

2-5 結果通知

与信、返金が結果通知対象となります。

与信時の結果通知は、決済サーバーが Alipay 決済センターから決済請求に対する完了通知を受け取り、該当の取引が完了したと判断した後通常 5 分以内に店舗様へ通知されます。



決済申込み要求後、Alipay 決済画面で決済の確定が可能な時間は最大 30 分となります。そのため、申込から最大 30 分遅れて結果通知が送信される可能性があります。


Alipay 決済画面に遷移すると、画面上でタイマーが動作しているのが確認できます。30 分以内であれば、一度ブラウザを閉じたとしても、再度 Alipay にアクセスして決済を確定できます。

取引の翌日に Alipay から届く清算データと決済サーバーの取引データを比較し、差異が発生した場合は、訂正後の内容で再度通知が送られます。
決済センターと弊社の取引ステータス整合性チェックを翌日に行っています。その際、何らかの原因により、稀に弊社側で成功として扱っていた取引が失敗しているといった不整合が発生する可能性があります。この場合には再度新しいステータスでの結果通知を店舗様へ送信します。
この事象の発生は全加盟店様で年 1 件程度の頻度となっており、発生時には弊社のオペレーターより別途ご連絡をさせていただきます。
もしもこの事象が発生した場合には、たとえば加盟店様では既に消費者様に商品の発送をしているなど、運用に支障が出る事も想定されますので、念のため考慮された運用をご検討ください。

返金申込時の結果通知は、返金申込が失敗した場合のみ通知されます。
決済サーバーは、返金申込に対する Alipay 決済センターからの失敗通知を受け取り、該当の取引が失敗したと判断した後通常 5 分以内に店舗様へ通知します。
Alipay 決済センターでの返金処理は、返金申込を行った翌日以降となります。

※結果通知を受信する URL は、MAP の「各種設定変更」画面の「Alipay 決済」－「通知 URL」に設定してください。

12

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

フィールド名番
1

numberOfNotify

項目名
通知件数

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

説明
1 度に通知可能な件数は 100 件

設定○

101 件以上は次回通知
2pushTime

送信時刻

半角数字 14 桁

決済サーバーから通知した時刻○YYYYMMDDhhmmss 形式
3pushId

識別 ID

半角数字 8 桁

プッシュ処理を行うたびに採番される ID○注） 他の決済サービスで使用された ID と重複する場合があります。
通知件数分下記の項番（4～9）を繰り返す。尚、フィールド名の後ろに 4 ケタの連番（0000～0099）を付与する。
4orderId

取引 ID

半角英数字 100 桁以内

取引 ID

○

5txnType

サービスコマンド

半角英数字 20 桁以内"Authorize"：与信

○

右記参照

"Refund"：返金申込（オンライン決済のみ）

6mstatus

処理結果コード

半角英数字 32 文字以内

処理結果のステータス。

○"success"：正常終了"failure"：異常終了
7vResultCode

詳細結果コード

文字列 16 桁

処理結果を詳細に表すコード○

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

決済センターとの取引 ID

文字列 64 文字以内

決済センターとの取引 ID○9dummy

ダミー決済フラグ

半角数字1桁ダミー取引の場合："1"、本番取引場合："0"○10txnTime

処理日時

半角数字14桁

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



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



結果通知を受信するための URL は、MAP 管理画面（Merchant Administration Portal）の「各種設定変更」の画面で設定してください。

13

第3章 その他 補足事項
3-1 注意事項
1)

一回の支払限度額は、中国元(CNY)換算で 300,000 元までとなります。

2)

オンライン決済の場合、返金自体が成功か失敗かの結果が得られるのは、翌日以降となります。
Alipay の仕様上、返金結果の確定が遅れる場合があります。また、最長何日程度の遅れが発生するかの仕様は非公開となっております。
これまでの発生件数は年に 1～2 回、3～4 日程度の遅延を確認しております。 ※2018 年 5 月現在

3)

与信同時売上金額を超えないかぎり、金額の一部のみ返金することも可能です。

4)

Alipay オンライン決済のみマルチ通貨に対応しています。Authorize（与信同時売上方式）時に、決済金額を日本円、または中国元で設定できます。また、Refund（返金）における通貨は、Authorize（与信同時売上方式）時に指定した通貨と同じものになります。返金時の為替レートは、購入時のレートが適用されます。
ただし、「清算金額」と「清算通貨」については、JPY（日本円）で返却いたします。CNY（中国元）では返却しないため、消費者への中国元での請求については、消費者自身で Alipay 側のサイトで確認する必要があります。
また、為替レートを事前に取得する仕組みが提供されていないため、決済金額を日本円で指定した場合、中国元の金額は Alipay のサイトにリダイレクトした後に分かります。

14