Alipay
本ガイドについて
本ガイドの内容
本ガイドは、(株)DGフィナンシャルテクノロジーが提供するVeriTrans4Gを利用するための専用ソフトウェアMDK（Merchant Development Kit）をインターネット店舗などに導入する開発者向けのガイドです。VeriTrans4G Alipay決済にて使用する電文のインターフェース詳細について記載しています。
VeriTrans4Gの詳細については、『開発ガイド』を参照して下さい。
尚、インターフェース詳細は、決済サービス毎に提供していますので、当該決済サービスの『インターフェース詳細』を参照して下さい。
インターフェース詳細
本章では、各決済にて使用する電文（Dto）について説明します。以下の表に記載されているフィールドは、店舗様にて利用可能なフィールドです。
各電文（Dto）には、以下の表に記載されていないフィールドが定義されている場合がありますが、以下の表に記載されていないフィールドは店舗様では使用することはできません。
共通
-
「設定」欄の内容は以下の通りです。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※、※n（条件は説明欄、または欄外に記入）
- 応答電文 ...
- 必ず返戻：○ 処理成功時のみ返戻：△ 返戻なし：× その他条件付：※
-
orderId（取引ID）について
店舗で任意に採番してください。申込処理毎に付ける必要があります。他の取引IDと重複しないよう採番してください。他決済サービスとも重複できません。
また、テスト取引で使用した取引IDを、本番取引で再度使用することはできません。
取引IDには、半角英数字以外に"-"（ハイフン）、"_"（アンダースコア）も使用可能です。
与信同時売上
要求電文：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"： 日本円 "CNY"： 中国元（オンライン決済のみ） |
○ | ||
| successUrl | 決済完了後戻りURL | URLに使える文字256桁以内 | 決済が成功した場合に、店舗側へ遷移を戻す為のURLを指定 | ○ | ||
| errorUrl | 決済エラー時戻りURL | URLに使える文字256桁以内 | 決済が失敗した場合に、店舗側へ遷移を戻す為のURLを指定 | ○ | ||
| commodityName | 商品名 | 文字列100桁以内 | 商品名を指定 この情報はオンライン決済ではAlipayの決済ページに表示されます。 |
○ | ||
| commodityDescription | 商品詳細 | 文字列200桁以内 | 商品の詳細を指定 この情報はAlipayの決済ページに表示されます。 |
△ | ||
| withCapture | 売上フラグ | 右記参照 | "true"： 与信・売上（設定可能な値は"true"のみです）
※設定しない場合のデフォルト値は"true"です。 |
△ | ||
| payType | 決済種別 | 半角数字 | 決済種別を指定 "0"：オンライン決済 ※未指定の場合は、"0"：オンライン決済 |
△ | ||
| deviceType | デバイスタイプ | 半角数字 |
デバイスタイプを指定 "0"：PC "1"：スマートフォン ※payTypeが"0":オンライン決済の場合に有効 |
△ | ||
応答電文：AlipayAuthorizeResponseDto
| 応答電文：AlipayAuthorizeResponseDto | ||||||
|---|---|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 | ||
| serviceType | サービスタイプ | 右記参照 | 要求電文を送信した決済サービスタイプ "alipay"：Alipay決済 |
○ | ||
| 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 | Alipayリダイレクト用HTMLフォーム文字列 | 文字列4096桁以内 | AlipayへリダイレクトするためのHTML この文字列はURLエンコードされています。 Alipayの画面に自動遷移するためのJavaScript を含みますので、URLデコード後の文字列をそのまま消費者のブラウザに返戻してください。 返戻するコンテンツの文字コードはUTF-8として返戻する必要があります。 |
△ | ||
結果
リダイレクト受信内容 ： 決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(POST)される内容
※オンライン決済の場合のみ、リダイレクトされます
| リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(POST)される内容 | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | サービスタイプ | 右記参照 | 要求電文を送信した決済サービスタイプ "alipay"：Alipay決済 |
○ |
| authInfo | 認証情報 | 右記参照 | 受信データが自店舗のデータかどうかを検証するための文字列 (弊社から提供するサンプルに当文字列による店舗認証の実装方法が含まれていますので参照してください) |
○ |
| mstatus | 処理結果コード | 半角英数字32文字以内 | "success" ： 正常終了 "failure" ： 異常終了 "pending" ： 保留状態(※) |
○ |
| vResultCode | 詳細結果コード | 半角英数16桁 | 処理結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。詳細は別途 『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ | 文字列300桁以内 | 処理結果を日本語で表示します。 | ○ |
| custTxn | トランザクションID(取引毎に付けるID) | 文字列100桁以内 | 決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| orderId | 取引ID | 半角英数字100桁以内 | 決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| centerTradeId | 決済センターとの取引ID | 文字列64文字以内 | 決済サーバーが発番するID | ○ |
| settleAmount | 清算金額 | 半角数字7桁以内 | 清算金額 | △ |
| settleCurrency | 清算通貨種類 | 半角文字3桁 | 清算通貨種類 "JPY"：日本円（固定） |
△ |
pendingについて
- ブラウザがAlipayのサイトから弊社URLに戻ってきた時点で、決済サーバーがAlipayからの結果通知を受信してない場合は、Alipayに決済結果の問合せを行っています。
その問合せ結果が何らかの問題（一時的な通信の問題等）で正常に取得できなかった場合にpendingとなります。 - pendingとなった時点では加盟店様への結果通知（PUSH通知）は送信しませんが、弊社側で結果が確認できたタイミングで結果通知（successまたはfailure）を送信します。
ただし、状況により翌日の運用対処となる可能性があり、その場合には結果通知を送信できないことがあります。
結果通知が送信できない場合には、テクニカルサポートまたはカスタマーサポートからご連絡させていただきます。 - pendingが発生した場合は、その時点で失敗扱いとしていただき、後から成功していたことが確認できた場合には、返金を行っていただくことをお勧めします。
- お客様には一時的な障害のため決済が失敗したことと、万が一成立している場合には後ほど返金されることをご案内ください。
返金申込
返金が可能な期間は、支払い日から365日間となります。また、決済金額の残高が0円になるまで繰り返し実行できます。
- オンライン決済では、返金申込みという扱いになります。翌日以降、返金自体が成功か失敗かの結果が得られます。通貨は、Authorize（与信同時売上方式）時に指定した通貨と同じものになります。
要求電文 ： AlipayRefundRequestDto
| 要求電文 ： AlipayRefundRequestDto | ||||||
|---|---|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 | ||
| orderId | 取引ID | 半角英数字100桁以内 | 決済請求、与信完了時に採番した取引IDを指定 | ○ | ||
| amount | 取引金額 | 半角数字7桁以内 | 返金する金額を指定
※一部キャンセルも可能 |
○ | ||
| reason | 理由 | 文字列80桁以内 | 返金の理由を指定 返金理由は、Alipayが提供している消費者向けの管理画面に表示されます。 返金理由は、中国語または英語での指定を推奨します。 |
○ | ||
応答電文 ： AlipayRefundResponseDto
| 応答電文 ： AlipayRefundResponseDto | ||||||
|---|---|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 | ||
| serviceType | 決済サービスタイプ | 右記参照 | 要求電文を送信した決済サービスタイプ "alipay"：Alipay決済 |
○ | ||
| mstatus | 処理結果コード | 半角英数字32文字以内 | "success"：正常終了 "failure"：異常終了 "pending"：保留状態（オンライン決済ではpendingは発生しません） |
○ | ||
| vResultCode | 詳細結果コード | 半角英数字16文字 | 処理結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は別途『結果コード一覧』を参照下さい。 |
○ | ||
| merrMsg | エラーメッセージ | 文字列300桁以内 | 処理結果を日本語で表示します。 | ○ | ||
| marchTxn | 電文ID | 文字列100桁以内 | 決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。 |
○ | ||
| orderId | 取引ID | 半角英数字 100文字以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ | ||
| custTxn | トランザクションID(取引毎に付けるID) | 文字列100桁以内 | 決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ | ||
| txnVersion | MDKバージョン | 文字列5桁 | 電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ | ||
| centerTradeId | 決済センターとの取引ID | 文字列64文字以内 | 決済サーバーが発番するID | △ | ||
結果通知
- 与信、返金が結果通知対象となります。
- 与信時の結果通知は、決済サーバーがAlipay決済センターから決済請求に対する完了通知を受け取り、該当の取引が完了したと判断した後通常5分以内に店舗様へ通知されます。
- 決済申込み要求後、Alipay決済画面で決済の確定が可能な時間は最大30分となります。そのため、申込から最大30分遅れて結果通知が送信される可能性があります。
- Alipay決済画面に遷移すると、画面上でタイマーが動作しているのが確認できます。30分以内であれば、一度ブラウザを閉じたとしても、再度Alipayにアクセスして決済を確定できます。
-
取引の翌日にAlipayから届く清算データと決済サーバーの取引データを比較し、差異が発生した場合は、訂正後の内容で再度通知が送られます。
決済センターと弊社の取引ステータス整合性チェックを翌日に行っています。その際、何らかの原因により、稀に弊社側で成功として扱っていた取引が失敗しているといった不整合が発生する可能性があります。この場合には再度新しいステータスでの結果通知を店舗様へ送信します。
この事象の発生は全加盟店様で年1件程度の頻度となっており、発生時には弊社のオペレーターより別途ご連絡をさせていただきます。
もしもこの事象が発生した場合には、たとえば加盟店様では既に消費者様に商品の発送をしているなど、運用に支障が出る事も想定されますので、念のため考慮された運用をご検討ください。 - 返金申込時の結果通知は、返金申込が失敗した場合のみ通知されます。 決済サーバーは、返金申込に対するAlipay決済センターからの失敗通知を受け取り、該当の取引が失敗したと判断した後通常5分以内に店舗様へ通知します。 Alipay決済センターでの返金処理は、返金申込を行った翌日以降となります。
※結果通知を受信するURLは、MAPの「各種設定変更」画面の「Alipay決済」－「通知URL」に設定してください。
下表に、電文項目の詳細を示します。
結果通知に関するサービス共通の仕様については、『開発ガイド』を併せてご参照ください。
| 項番 | フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 | |
|---|---|---|---|---|---|---|
| 1 | numberOfNotify | 通知件数 | 半角数字4桁以内 | 1度に通知可能な件数は100件 101件以上は次回通知 |
○ | |
| 2 | pushTime | 送信時刻 | 半角数字14桁 | 決済サーバーから通知した時刻 YYYYMMDDhhmmss形式 |
○ | |
| 3 | pushId | 識別ID | 半角数字8桁 | プッシュ処理を行うたびに採番されるID 注） 他の決済サービスで使用されたIDと重複する場合があります。 |
○ | |
| 通知件数分下記の項番（4～9）を繰り返す。尚、フィールド名の後ろに4ケタの連番（0000～0099）を付与する。 | ||||||
| 4 | orderId | 取引ID | 半角英数字100桁以内 | 取引ID | ○ | |
| 5 | txnType | サービスコマンド | 半角英数字20桁以内 右記参照 | "Authorize"：与信 "Refund"：返金申込（オンライン決済のみ） |
○ | |
| 6 | mstatus | 処理結果コード | 半角英数字32文字以内 | 処理結果のステータス。 "success"：正常終了 "failure"：異常終了 |
○ | |
| 7 | vResultCode | 詳細結果コード | 文字列16桁 | 処理結果を詳細に表すコード 詳細は別途『結果コード一覧』を参照下さい。 |
○ | |
| 8 | centerTradeId | 決済センターとの取引ID | 文字列64文字以内 | 決済センターとの取引ID | ○ | |
| 9 | dummy | ダミー決済フラグ | 半角数字1桁 | ダミー取引の場合："1"、本番取引場合："0" | ○ | |
| 10 | txnTime | 処理日時 | 半角数字14桁 | yyyyMMddHHmmss形式 | - | |
（注意事項）
- pushId（識別ID）は、他の決済サービスで使用されたIdと重複する場合がありますので、ユニークキーとして処理しないようにしてください。
- 項目の並び順は、必ずしも表の順序とは一致しません。
- 結果通知を受信するためのURLは、MAP管理画面（Merchant Administration Portal）の「各種設定変更」の画面で設定してください。
その他 補足事項
注意事項
- 一回の支払限度額は、中国元(CNY)換算で300,000元までとなります。
- オンライン決済の場合、返金自体が成功か失敗かの結果が得られるのは、翌日以降となります。
- Alipayの仕様上、返金結果の確定が遅れる場合があります。また、最長何日程度の遅れが発生するかの仕様は非公開となっております。
これまでの発生件数は年に1～2回、3～4日程度の遅延を確認しております。 ※2018年5月現在
- Alipayの仕様上、返金結果の確定が遅れる場合があります。また、最長何日程度の遅れが発生するかの仕様は非公開となっております。
- 与信同時売上金額を超えないかぎり、金額の一部のみ返金することも可能です。
- Alipayオンライン決済のみマルチ通貨に対応しています。Authorize（与信同時売上方式）時に、決済金額を日本円、または中国元で設定できます。また、Refund（返金）における通貨は、Authorize（与信同時売上方式）時に指定した通貨と同じものになります。返金時の為替レートは、購入時のレートが適用されます。
ただし、「清算金額」と「清算通貨」については、JPY（日本円）で返却いたします。CNY（中国元）では返却しないため、消費者への中国元での請求については、消費者自身でAlipay側のサイトで確認する必要があります。
また、為替レートを事前に取得する仕組みが提供されていないため、決済金額を日本円で指定した場合、中国元の金額はAlipayのサイトにリダイレクトした後に分かります。