Alipay+
本ガイドについて
本ガイドの内容
本ガイドは、株式会社DGフィナンシャルテクノロジーが提供するVeriTrans4GのAlipay+（オンライン決済）サービスをインターネット店舗に導入するための、アプリケーション開発者向けのガイドです。
Alipay+サービス概要
Alipay+サービスの概要
Alipay+サービスは、VeriTrans4G加盟店様のサイトで購入された商品の代金を、Alipayや様々な海外決済サービスで支払いすることが可能です。
- PC/スマートフォン/加盟店作成のアプリでの決済が可能です。
決済の画面遷移のイメージを以下に示します。
【PC+Alipayアプリでの決済】
【スマートフォン/加盟店作成のアプリでの決済】
MDKの処理概要
機能一覧（決済要求コマンド）
使用可能な決済要求コマンドを下記表に示します。
| 決済要求種類 /コマンド |
概要 |
|---|---|
| 申込 （与信＋売上） /Authorize |
決済の申し込み（オーソリ）と売上を同時に要求します。 |
| 返金 /Refund |
決済申し込み済みの取引に対し返金します。 消費者が利用する決済サービスによっては、売上金額を超えない範囲で返金金額を指定できます（部分返金）※1。 |
※1 部分返金は、決済金額の残り（残高）が0円になるまで繰り返し実行できます。
以下は実施可能タイミングの図示です。
決済処理シーケンス
【決済申込処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 決済申込要求 | ECサイト上の決済導入部に渡された決済申込情報を電文化し決済サーバーに送信します。 |
| 2 | 結果応答 | 決済サーバーから返戻された結果を受信します。結果が成功（決済可能）の場合、「3. リダイレクト指示」を実施します。消費者ブラウザに返すリダイレクト先のURLが決済サーバーより返戻された結果に含まれます。 |
| 3 | リダイレクト指示 | 決済サーバーにより返戻されたURLを表示します。URLをリダイレクトし、Alipayの注文画面へ遷移します。 |
| 4 | 決済承認シーケンス | 支払画面から決済承認を行います。 具体的な承認の動きについては以下をご参照ください。 2-1 Alipay+サービスの概要 【PC+Alipayアプリでの決済】 【スマートフォン/加盟店作成のアプリでの決済】 |
| 5 | 決済申込完了通知 |
この通知は、決済申込により与信が成功した場合のみ通知されます。 リクエスト時に指定したPUSH通知先URL（未指定の場合は、MAP（Merchant Administration Portal）により設定した値）に、決済サーバーよりPOSTで通知されますので、決済結果を受け取り、注文データ等に反映します。 完了画面要求は、消費者の端末（PCやスマートフォン）のネットワーク環境の問題や、誤操作（ブラウザやタブを閉じてしまう等）により、正しく行われない可能性がありますので、必ずこの通知を受信してください。 なお、この通知と完了画面要求のリダイレクト結果が加盟店に届く順番は保証されていません。どちらが先に届いても問題とならないようにご対応ください。 |
| 6 | 完了画面要求 |
消費者ブラウザから結果を受信し、完了画面を送信します。 消費者側の状況により通信断や誤ってブラウザを閉じる、といったケースではこのシーケンスは発生しませんが、第4章の結果通知(PUSH)を受信していれば、決済結果を取りこぼすことはありません。 |
【返金処理】
| No. | 基本機能 | 処理説明 |
|---|---|---|
| 1 | 返金要求 | 返金の対象となる取引情報を電文化し、決済サーバーに送信します。 |
| 2 | 結果応答 | 決済サーバーより返金の結果応答を受信し、結果情報を取得します。 |
結果通知(PUSH)受信処理
結果通知受信処理の対象
Alipay+の結果通知受信処理の対象は以下の機能です。
| 決済サービス名 | 決済申込 | 返金 |
|---|---|---|
| Alipay+ （オンライン決済） |
○ | － |
通信電文仕様（共通部）および店舗受信後応答仕様は、『VeriTrans4G 開発ガイド（MDKモジュール方式）』をご参照ください。
Alipay+固有の通知電文インターフェイスにつきましては、「5.3.2 結果通知電文の詳細」をご参照ください。
インターフェイス詳細
ここではAlipay+サービスで利用するMDKインターフェイス項目を説明します。
-
「設定」欄の内容は以下の通りです。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※、※n（条件は説明欄、または欄外に記入）
- 応答電文 ...
- 必ず返戻：○ 処理成功時のみ返戻：△ 処理失敗時でも返戻の可能性あり：◇ 返戻なし：× その他条件付：※
- その他 ...
- CPM：店舗スキャン型 MPM：消費者スキャン型
-
orderId（取引ID）について
店舗で任意に採番してください。申込処理毎に付ける必要があります。他の取引IDと重複しないよう採番してください。他決済サービスとも重複できません。
また、テスト取引で使用した取引IDを、本番取引で再度使用することはできません。
取引IDには、半角英数字以外に"-"（ハイフン）、"_"（アンダースコア）も使用可能です。 -
応答電文について
応答電文には、本書に記載されていないフィールド（パラメータ）も存在しますが、通常は、記載されているフィールド以外は加盟店様の方で意識する必要はございません。
Alipay+
申込
| 要求電文：AlipayxAuthorizeRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 100桁以内 |
店舗側で採番した取引IDを指定 | ○ |
| serviceOptionType | サービスオプションタイプ | 半角英数字 | 利用する決済方法のタイプを指定 "online" ：オンライン決済 |
○ |
| amount | 決済金額 | 半角数字 12桁以内 |
決済金額を指定 決済金額は、日本円（JPY）で指定してください。 1～999999999999の間で指定できます。 |
○ |
| withCapture | 売上フラグ | 右記参照 |
"true"： 与信同時売上（設定可能な値は"true"のみです）
※指定が無い場合のデフォルト値は"true"です。 |
△ |
| orderDetail | 商品詳細 | 文字列 256文字以内 |
商品詳細を指定 全角（日本語・中国語）の指定が可能ですが、英語での指定を推奨します。 |
○ |
| storeId | 店舗ID | 半角英数字 32桁以内 |
店舗IDを指定
※半角英数字、"-"（ハイフン）、"_"（アンダースコア）も使用可能です。 ※指定する値はAlipayに登録されている必要があります。未指定の場合はマーチャント登録時に設定した値を使用します。 |
△ |
| storeName | 店舗名 | 文字列 128byte以内 |
店舗名を指定 全角（日本語・中国語）の指定が可能ですが、英語での指定を推奨します。 ※未指定の場合はマーチャント登録時に設定した値を使用します。 |
△ |
| terminalId | 端末ID | 半角英数字 64桁以内 |
端末IDを指定
※半角英数字、"-"（ハイフン）、"_"（アンダースコア）も使用可能です。 |
△ |
| deviceType | デバイスタイプ | 半角数字 | デバイスのタイプを指定
"0"：PC ※指定が無い場合のデフォルト値は"0"です。 |
△ |
| userAgent | ユーザーエージェント | 文字列 1024byte以内 |
ユーザーエージェントを指定
OSの種類（Android・iOS）の判別可能な情報を設定いただくようにお願いします。OSの種類（Android・iOS）の判別可能な情報判別が不可能な場合はエラーとなります。 ※deviceType="1"、"2"の場合、指定必須。 |
△※ |
| successUrl | 決済完了時URL | 文字列 1024byte以内 |
決済完了後に、店舗側サイトに画面遷移を戻すためのURLを指定
※未指定の場合は管理画面(MAP)から設定した「決済完了時URL」を使用します。 ※未指定かつ、管理画面(MAP)の対象項目も未指定の場合はエラーとなります。 |
△※ |
| errorUrl | 決済失敗時URL | 文字列 1024byte以内 |
決済失敗後に、店舗側サイトに画面遷移を戻すためのURLを指定
※未指定の場合は管理画面(MAP)から設定した「決済失敗時URL」を使用します。 ※未指定かつ、管理画面(MAP)の対象項目も未指定の場合はエラーとなります。 |
△※ |
| pushUrl | プッシュURL | 文字列 1024byte以内 |
結果通知URLを指定
※未指定の場合は管理画面(MAP)から設定した「通知URL」を使用します。 |
△ |
| 応答電文 ： AlipayxAuthorizeResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ | 半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード | 半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ | 文字列 1024 byte以内 |
処理結果を日本語又は英語で表示 | ○ |
| marchTxn | 電文ID | 半角英数字 100桁以内 |
決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。 |
○ |
| orderId | 取引ID | 半角英数字 100 桁以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID | 半角英数字 100桁以内 |
決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| txnVersion | MDK バージョン | 半角英数字5桁 | 電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| centerId | 決済センターの管理ID | 文字列 64byte以内 |
決済センターが発番するID | △ |
| gatewayTransId | 決済ゲートウェイ管理ID | 半角英数字記号 64桁以内 |
決済ゲートウェイが発番するID
※記号について、"-"（ハイフン）、"_"（アンダースコア）は返戻される可能性があります。 |
◇ |
| authStartUrl | 認証開始URL | 文字列 1024byte以内 |
ブラウザを遷移させるためのHTMLコンテンツを取得するURL | △ |
消費者ブラウザから店舗側の完了画面へリダイレクトする時のクエリパラメータ
| リダイレクト受信内容：決済サーバーから消費者ブラウザ経由で店舗へリダイレクト(GET)される内容 | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| mstatus | 処理結果コード | 半角英数字 32 文字以内 |
"success"：正常終了 "failure"：異常終了 |
○ |
| vResultCode | 詳細結果コード | 半角英数4桁 | 処理の結果を詳細に表すコード詳細は『結果コード一覧』を参照下さい。 | ○ |
| orderId | 取引ID | 半角英数字 100文字以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| payTimeJp | 決済日時(日本時間) | 文字列 14桁 |
決済センターで決済が確定した日時(日本時間)
※YYYYMMDDhhmmssの形式 |
△ |
| centerId | 決済センターの管理ID | 文字列 64byte以内 |
決済センターが発番するID |
△ |
| gatewayTransId | 決済ゲートウェイ管理ID | 半角英数字 64桁以内 |
決済ゲートウェイが発番するID ※記号について、"-"（ハイフン）、"_"（アンダースコア）は返戻される可能性があります。 |
◇ |
| paymentSource | ペイメントソース | 文字列 64byte以内 |
支払いを行った決済手段を表す情報
※「paymentSource」の種類は6-3ペイメントソース（paymentSource）の一覧を参照 |
△ |
| foreignAmount | 決済金額(外貨) | 半角数字（小数点含む） 16桁以内 |
決済金額(外貨)
※ウォレットによっては連携されない場合があります。また、決済通貨と清算通貨が同一の場合は返却しません。 |
△※ |
| foreignAmountCurrency | 通貨コード(外貨) | 文字列 3桁以内 |
通貨コード(外貨)
※ウォレットによっては連携されない場合があります。また、決済通貨と清算通貨が同一の場合は返却しません。 |
△※ |
| txnType | トランザクションタイプ | 文字列 右記参照 |
決済申込結果であることを示す、以下の文字列が設定されます。
"Authorize" |
○ |
| vAuthInfo | 改ざんチェック用 ハッシュ値 |
文字列 右記参照 |
下記文字列を連結し、SHA-256によって算出したハッシュ値
|
○ |
| authParams | ハッシュ値算出 パラメータ順序 |
文字列 右記参照 |
vAuthInfo のハッシュ値を算出する元とした文字列の、パラメータの連結順序を示す値 パラメータ名のカンマ区切り文字列をBase64エンコードしています。デコードを行うと文字列が復元されます。 例) "orderId,vResultCode,mstatus" "mstatus,orderId,vResultCode" （順不同のため、リクエスト受信の度に動的に処理してください。） |
○ |
- vAuthInfoおよびauthParamsを利用した改ざんチェックについて
決済サーバーから消費者ブラウザを経由して店舗側の結果画面に遷移（リダイレクト）しますが、ここで店舗側システムが受け取ったクエリパラメータが改ざんされていないことを検証するためのパラメータが、vAuthInfoとauthParamsです。
店舗側システムで算出したハッシュ値が、クエリパラメータより取得したvAuthInfoと一致している場合は、パラメータは改ざんされていない、とみなすことができます。
この改ざんチェックは必須ではありませんが、悪意を持った第三者によって、不正なリダイレクト電文を受信する可能性がありますので、実装を強く推奨しています。
実装方法の詳細につきましては、弊社より提供しているサンプルプログラムをご参照ください。
返金
| 要求電文 ： AlipayxRefundRequestDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| orderId | 取引ID | 半角英数字 100桁以内 |
上記「orderId（取引ID）について」参照 |
○ |
| serviceOptionType | サービスオプションタイプ | 半角英数字 | 利用する決済方法のタイプを指定 "online" ：オンライン決済 |
○ |
| amount | 返金金額 | 半角数字 12桁以内 |
返金金額を指定。 返金金額は、日本円（JPY）で指定してください。 ※未指定時は、残高（現在の決済金額） |
△ |
| reason | 返金理由 | 文字列 256文字以内 |
返金の理由を指定 英語での指定を推奨します。 |
△ |
| 応答電文 ： AlipayxRefundResponseDto | ||||
|---|---|---|---|---|
| フィールド名 | 項目名 | 書式・制限 | 説明 | 設定 |
| serviceType | 決済サービスタイプ | 半角英数字 10桁以内 |
要求電文を送信した決済サービスタイプ | ○ |
| mstatus | 処理結果コード | 半角英数字 32文字以内 |
"success"：正常終了 "failure"：異常終了 "pending"：保留 |
○ |
| vResultCode | 詳細結果コード | 半角英数字 16文字 |
処理の結果を詳細に表すコード 4桁ずつ4つのブロックで構成され、各ブロックでサービス毎の処理結果を表します。 詳細は『結果コード一覧』を参照下さい。 |
○ |
| merrMsg | エラーメッセージ | 文字列 1024byte以内 |
処理結果を日本語又は英語で表示 | ○ |
| marchTxn | 電文ID | 半角英数字 100桁以内 |
決済サーバーにて決済処理電文（内部処理も含む）毎に付与するID １つの取引IDに対して、複数のIDが付与されます。 |
○ |
| orderId | 取引ID | 半角英数字 100桁以内 |
決済要求時に店舗様にて任意に採番し送信された取引ID | ○ |
| custTxn | 取引毎に付くID | 半角英数字 100桁以内 |
決済サーバーがオーダー（取引ID）と紐付ける為に採番するID | ○ |
| txnVersion | MDK バージョン | 半角英数字5桁 | 電文のバージョン 問題発生時などに用いますが、通常ご利用になることはありません。 |
○ |
| payTimeJp | 決済日時(日本時間) | 文字列 14桁 |
決済センター側で決済された日時 ※YYYYMMDDhhmmssの形式 |
△ |
| gatewayTransId | 決済ゲートウェイ管理ID | 半角英数字記号 64桁以内 |
決済ゲートウェイが発番するID ※記号について、"-"（ハイフン）、"_"（アンダースコア）は返戻される可能性があります。 |
◇※ |
| balance | 残高 | 半角数字 12桁以内 |
現在の決済金額を返します |
◇ |
共通
検索
-
「設定」欄の内容は以下の通りとなります。
- 要求電文 ...
- 必須項目：○ 任意項目：△ 設定不可：× その他条件付：※（条件は説明欄に記入）
- 応答電文 ...
- 必ず返戻：○ 該当取引存在時に返戻：△ 処理失敗時でも返戻の可能性あり：◇ 返戻なし：× その他条件付：※
-
複数指定は0～の添字を指定します。
例）exparam.serviceTypeCd[0]=card&exparam.serviceTypeCd[1]=alipayx -
ワイルドカードは値の一部と"*"を組み合わせて検索します。"*"のみの指定はできません。
例）exparam.searchParameters.common.orderId=123*
| 要求電文 ： SearchRequestDto | |||||||
|---|---|---|---|---|---|---|---|
| ※ 以下は、共通の検索要求フィールドです。 | |||||||
| 検索フィールド名 | 検索項目名 | 書式・制限 | 複数指定 | ﾜｲﾙﾄﾞｶｰﾄﾞ | 説明 | 設定 | |
| requestId | リクエストID | 半角英数字記号128文字以内 | リクエストIDを指定します。指定した場合は、それ以外のパラメータは指定できなくなります。 | △ | |||
| serviceTypeCd | 決済サービスタイプ | 右記参照 | ○ | 検索対象の決済を指定します。未指定の場合は、全決済が検索対象となります。 "alipayx"： Alipay+ |
△ | ||
| 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 "：申込（与信＋売上） " Refund "：返金 |
△ | ||
| 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）を指定します。 | △ | |||
| ※ 以下は、Alipay+固有の検索要求フィールドです。 | |||||||
| alipayx Alipay+ | |||||||
| detailOrderType | 詳細オーダー決済状態 | 右記参照 | ○ |
※「detailOrderType」の詳細は6-2検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）を参照 |
△ | ||
| detailCommandType | 詳細コマンドタイプ | 右記参照 | ○ |
※「detailCommandType」の詳細は6-2検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）を参照 |
△ | ||
| alipayxServiceType | Alipay+サービスタイプ | 右記参照 | ○ | 決済申込時に指定したAlipay+の決済タイプ（serviceOptionType） | △ | ||
| 応答電文 ： SearchResponseDto | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ※ 以下は、共通の検索結果フィールドです。 | |||||||||||||
| 検索フィールド名 | 検索項目名 | 書式・制限 | 説明 | 設定 | |||||||||
| result | 処理結果 | － | ○ | ||||||||||
| mstatus | 処理結果コード | 半角英数字32文字以内 |
処理の結果ステータスが格納されます。 "success"：正常終了 "failure"：異常終了 |
○ | |||||||||
| vResultCode | 詳細結果コード | 半角英数字16文字 |
処理の結果を詳細に表すコードとなります。 詳細は『結果コード一覧』を参照下さい。 |
○ | |||||||||
| merrMsg | エラーメッセージ | 文字列1024バイト以内 | 処理結果を日本語又は英語で表示します。 | ○ | |||||||||
| overMaxCountFlag | 最大件数超えフラグ | 右記参照 |
検索対象データが要求電文で指定した検索最大件数より多いかどうかを表します。 "true"： 最大件数以上 "false"： 最大件数未満 |
△ | |||||||||
| searchCount | 検索結果件数 | 0～1000 | 検索結果件数（オーダー件数）が格納されます。 | △ | |||||||||
| orderInfos | オーダー情報リスト | 複数のオーダー情報（orderInfo）が格納されます。 | △ | ||||||||||
| orderInfo | オーダー情報 | － | 検索条件に該当した取引の情報が該当件数分繰り返されます。0～1000件（要求電文で指定した検索最大件数まで）となります。 | △ | |||||||||
| index | インデックス | 0～999 | 検索された情報のインデックスが格納されます。 | △ | |||||||||
| serviceTypeCd | 決済サービスタイプ | 右記参照 |
決済の種類が格納されます。 "alipayx"： Alipay+ |
△ | |||||||||
| 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 | 固有トランザクション情報 | － | 各決済サービスの固有トランザクション情報が格納されます。後述の一覧参照。 | △ | |||||||||
|
☆ 以下の情報は、上記 「固有オーダー情報」 「固有トランザクション情報」 内の階層にセットされます。 |
|||||||||||||
|
※ 以下は、Alipay+固有の検索結果フィールドです。 |
|||||||||||||
| properOrderInfo | Alipay+ 固有オーダー情報 | ||||||||||||
| alipayxServiceType | Alipay+サービスタイプ | 文字列 | 決済申込時に指定したAlipay+の決済タイプ（serviceOptionType） | △ | |||||||||
| authorizeAmount | 申込金額 | 半角数字12桁以内 | 決済申込時に指定した金額 | △ | |||||||||
| balance | 残高 | 半角数字12桁以内 | 現在の残高 | △ | |||||||||
| authorizeDatetime | 決済申込日時 | 文字列14桁 | 決済申込日時
YYYYMMDDhhmmss形式 |
△ | |||||||||
| centerId | 決済センターの管理ID | 文字列64byte以内 | 決済センターが発番したID | △ | |||||||||
| paymentSource | ペイメントソース | 文字列64byte以内 | 支払いを行った決済手段を表す情報
※「paymentSource」の種類は6-3ペイメントソース（paymentSource）の一覧を参照 |
△ | |||||||||
| foreignAmount | 決済金額(外貨) |
半角数字（小数点含む） 16桁以内 |
決済金額(外貨) ※ウォレットによっては連携されない場合があります。また、決済通貨と清算通貨が同一の場合は返却しません。 |
△※ | |||||||||
| foreignAmountCurrency | 通貨コード(外貨) | 文字列3桁以内 |
通貨コード(外貨)
※ウォレットによっては連携されない場合があります。また、決済通貨と清算通貨が同一の場合は返却しません。 |
△※ | |||||||||
| properTransactionInfo | Alipay+ 固有トランザクション情報 | ||||||||||||
| gatewayTransId | 決済ゲートウェイ管理ID | 半角英数字64桁以内 | 決済ゲートウェイが発番するID
※記号について、"-"（ハイフン）、"_"（アンダースコア）は返戻される可能性があります。 ※当日全額返金の場合は返戻されません。 |
◇※ | |||||||||
| alipayxResultCode | 決済センター結果コード | 文字列 | 決済センターが返却する結果コード | △ | |||||||||
| detailCommandType | 詳細コマンドタイプ | 文字列 |
※「detailCommandType」の詳細は 6-2検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態） を参照 |
△ | |||||||||
| alipayxRequestDatetime | 決済センターへの要求日時 | 文字列14桁 |
決済センターへの要求日時が格納されます。 YYYYMMDDhhmmss形式 |
△ | |||||||||
| alipayxResponseDatetime | 決済センターからの返戻日時 | 文字列14桁 |
決済センターからの返戻日時が格納されます。 YYYYMMDDhhmmss形式 |
△ | |||||||||
結果通知電文
結果通知電文の概要
機能概要
決済サーバーから店舗システムへ決済の結果通知を行います。
通知は、HTTPのPOSTを利用します。
※プロトコルはHTTP（Port：80）、HTTPS（Port：443）に対応しています。
処理の概要については「第4章 結果通知(PUSH)受信処理」をご参照ください。
HMACについて
POSTにてデータを通知する時、リクエストヘッダーにHMACを設定します。
また、HMAC値は、リクエストボディから算出します。
アルゴリズムは「HmacSHA256」が設定されます。
| フィールド名 | 設定値 |
|---|---|
| content-hmac | h={アルゴリズム名};s={CCID};v={HMAC値} |
結果通知受信処理結果について
決済サーバーからの通知に対して店舗側システムがHTTPステータスコード"200"を返戻した場合、受信処理が正常に終了したものと判断します。"200"以外のコードを返した場合は、受信失敗と判断し、一定期間、通知を繰り返します。
※ 規定の回数失敗した場合は、通知処理が停止しますのでご注意ください。
結果通知電文の詳細
結果通知電文の種類と通知タイミングを下表に示します。
| No. | 通知種類 | 通知タイミング | 注意事項 |
|---|---|---|---|
| 1 | 決済申込完了通知 （Authorize） |
決済申込が成立したタイミングで送信されます。 | 成功時に、結果が送信されます。 |
-
決済に消費者ブラウザが介在する場合、申込完了を通知するケース
決済が成立しているのにもかかわらず、消費者が画面遷移の途中で離脱した場合や、通信環境の問題で画面遷移時にタイムアウトが発生した場合など、最終遷移先まで到達しない場合があります。
このような場合にも、決済サーバーからの通知を店舗側システムで受信していただくことで、決済が成立したことを検知することができます。
対象の通知は、"Authorize"：決済申込完了通知です。
通知項目およびフォーマットを下表に示します。
| 項番 | フィールド名 | 項目名 | 書式・制限 | 説明 |
|---|---|---|---|---|
| 1 | numberOfNotify | 通知件数 | 半角数字4桁以内 | 1回の通知可能件数は1,000件、 1,001件以上は次回通知 |
| 2 | pushTime | 送信時刻 | 半角数字14桁 | VeriTrans4Gから通知した時刻 yyyyMMddHHmmss形式 |
| 3 | pushId | 識別ID | 半角数字8桁 | プッシュ処理を行うたびに採番されるID。 |
| 通知件数分下記の項番（4～11）を繰り返す。尚、フィールド名の後ろに4ケタの連番（0000～0999）を付与する。 | ||||
| 4 | orderId | 取引ID | 半角英数字100桁以内 | 取引ID |
| 5 | txnType | トランザクションタイプ | ※右記の説明を参照 | "Authorize"：決済申込完了通知 |
| 6 | txnTime | 処理日時 | 半角数字14桁 | yyyyMMddHHmmss形式 |
| 7 | vResultCode | 詳細結果コード | ※右記の説明を参照 | 半角英数字4桁の処理結果コード。 処理結果コードの詳細は、 『結果コード一覧』をご参照ください。 |
| 8 | mstatus | 処理ステータス | 半角英数字8桁以内 | "success"：正常終了 "failure"：異常終了 "pending"：保留 |
| 9 | dummy | ダミー決済フラグ | 半角数字1桁 | ダミー取引を示す場合は"1"を設定する |
| 10 | gatewayTransId | 決済ゲートウェイ管理ID | 半角英数字記号64桁以内 | VeriTrans4Gが発番したAlipay+の取引番号 |
| 11 | paymentSource | ペイメントソース | 文字列64byte以内 | 支払いを行った決済手段を表す情報 ※「paymentSource」の種類は6-3ペイメントソース（paymentSource） の一覧を参照 |
| 12 | foreignAmount | 決済金額(外貨) | 半角数字（小数点含む） 16桁以内 |
決済金額(外貨)
※ウォレットによっては連携されない場合があります。また、決済通貨と清算通貨が同一の場合は返却しません。 |
| 13 | foreignAmountCurrency | 通貨コード(外貨) |
文字列 3桁以内 |
通貨コード(外貨)
※ウォレットによっては連携されない場合があります。また、決済通貨と清算通貨が同一の場合は返却しません。 |
| 14 | payTimeJp | 決済日時(日本時間) |
文字列 14桁 |
決済センターで決済が確定した日時(日本時間)
※YYYYMMDDhhmmssの形式 |
| 15 | centerId | 決済センターの管理ID |
文字列 64byte以内 |
決済センターが発番するID |
- pushId（識別ID）は、他の決済サービスで使用されたIdと重複する場合がありますので、ユニークキーとして処理しないようにしてください。
- 項目の並び順は、必ずしも表の順序とは一致しません。
※ 結果通知電文の受信処理を実装される際は、サポートページに公開中のサンプルプログラムを参考にしてください。
その他 補足事項
Alipay+の注意事項
決済金額について
一回の支払限度額は、決済事業者側で登録したMCC（加盟店業種コード）により異なります。
また、支払限度額を超えた場合は「2G11：金額が上限を超えています。」を返します。
ロゴについて
Alipay+のロゴはAlipayが提供している以下のロゴジェネレーター「Alipay+ Acceptance Mark Generator」を使用して作成してください。
また作成にあたって、決済可能なウォレットを可能な限り多くにご記載いただくことを推奨します。
【ロゴジェネレーター】
https://docs.alipayplus.com/alipayplus/alipayplus/brand_guidelines_acq/brand_cashier_acq#gO5xy
返金の要求可能期間
Alipay+サービスにおける、返金の要求可能期間を下表に示します。
| 要求種類 | 要求可能期間 |
|---|---|
| 返金 | 決済申込から1年 |
例えば、「2022/11/20 1:00:00」に決済が成功した場合、返金可能な期限は「2023/11/20 1:00:00」となります。
返金結果が消費者に反映されるタイミングについて
返金結果は、消費者の決済アプリの残高へ即時に反映されます。
ただしクレジットカードなどの残高以外で決済をされていた場合、返金結果の反映タイミングは各決済方法の仕様に準拠します。
検索（Search）に関する補足（詳細コマンドタイプ/詳細オーダー決済状態）
決済サーバーでは、システム内部データとして詳細コマンド（処理要求の種類）と詳細な決済状態（その取引がどのような状態にあるか）を管理しています。
通常の運用では、店舗様システムではこれらの内部情報を利用する必要はありませんが、店舗様システムにおいて取引の状態検索が必要なケースや、障害等のお問い合わせ時の参照情報として、これらの内部データをSearchコマンドで公開しています。
下表にSearchコマンドにて利用可能な内部データの一覧を示します。
| 詳細コマンドタイプ (detailCommandType) |
コマンド成功時の詳細オーダー決済状態 (detailOrderType) |
||
|---|---|---|---|
| 論理名 | 値 | 論理名 | 値 |
| 決済認証 | PreAuth | 初期状態 | Init |
| 与信売上 | AuthCapture | 与信売上 | AuthCapture |
| 返金 | RefundAuthCapture | 与信売上 | AuthCapture |
| 取消 | VoidAuthCapture | 取消 | VoidAuthCapture |
注） 一覧に記載していないコマンドタイプと状態も存在します。
ペイメントソース（paymentSource）の一覧
ペイメントソース（paymentSource）の値は以下の支払手段と対応します。
今後、ペイメントソースの値は変更されませんが、Pay事業者の事情により支払手段の名前が変更される可能性があります。
そのため、Alipay社ではレシート等で消費者に対してペイメントソースを提示せずに「Alipay+」のみを提示することを推奨しています。
| paymentSource | 支払手段 |
|---|---|
| 1022088000000000001 | Alipay |
| 1022160000000000000 | AlipayHK |
| 1022166000000000001 | DANA |
| 1022167000000000001 | TrueMoney Wallet |
| 1022170000000000000 | Gcash |
| 1022171000000000001 | TNG eWallet |
| 1022172000000000001 | Kakao Pay |
| 2010BOPI00000000 | BPI |
| 2021224000000000 | Tinaba |
| 2021226300000000 | Rabbit LINE Pay |
| 2021227800000000 | Boost |
| 2021234400000000 | NAVER Pay |
| 2021241800000000 | Akulaku PayLater |
| A111253000000000 | BillEase |
| A111253100000000 | Mpay |
| A111254300000000 | Toss |
| A111256400000000 | KREDIVO ID |
| A111265400000000 | HiPay |
| A111266800000000 | K PLUS |
注1） 一部paymentSourceはAlipay社による対応時期が未定のため、返戻されない場合があります。 注2) 今後予告なくpaymentSourceの値が追加される可能性があります。
取引未確定時の処理について
以下のような状態で取引未確定となった際、一定時間経過後に決済サーバー側から決済センターへ確認処理を行います。その結果については、検索等でご確認ください。
また、確認処理後、コマンド実行時と同じ条件で結果通知も行います。詳細は「5.3.2 結果通知電文の詳細」
を参照ください。
| 対象の状態 | 確認時の(Searchで表示される)コマンド |
|---|---|
| Authorize後、PreAuth(決済認証)のまま決済センターからの通知(AuthorizeNotify)もリダイレクト(ResultRedirect)もない取引 | Confirm |
| Refund時に中断(mstatus=pending)となった取引 | Refund |
導入・テストに関する補足
決済サーバーに接続し、テストを実施するための各種手続き・手順の詳細につきましては、『導入テストガイド』を参照してください。
決済申込のエラーをシミュレートする
弊社では、テストのための疑似環境を提供しています。
Authorizeコマンドの結果として返戻されたURLをブラウザで読み込むと、疑似環境に遷移します。
| 取引結果選択 | 結果 |
|---|---|
| 成功 | 2001(成功) |
| 失敗 | 2GD2(失敗) |
この画面で「取引結果」の選択を行い、「確定」ボタンをクリックすると、「決済完了時URL（successUrl）」または「決済失敗時URL（errorUrl）」へ遷移します。
決済申込・返金コマンドのエラーをシミュレートする
Authorize、Refundコマンドの要求金額（"amount"）の下一桁の値を調整することで、
意図的にエラーを発生させることができます。
（Refundコマンドは金額を指定しない場合のみ、対象取引の残高で判定されます。）
テスト時の結果コード
要求金額の下一桁と、返戻されるvResultCodeの対応表を以下に記載します。
Authorize
| 要求金額の 下1桁 |
Authorize （決済申込） |
|---|---|
| 0 | 2001(成功) |
| 1 | |
| 2 | |
| 3 | |
| 4 | 2GD2(失敗) |
| 5 | 2001(成功) |
| 6 | 2ED2(失敗) |
| 7 | 2001(成功) |
| 8 | |
| 9 |
Authorizeのレスポンス返戻後の決済センター遷移後のシミュレートは「7.1決済申込のエラーをシミュレートする」を参照ください。
またAuthorize後、疑似環境（ダミーAlipay+）の「取引結果」の「確定」ボタンを押下しなかった取引について、一定時間経過後以下の結果に遷移します。
| 要求金額の 下1桁 | 結果コード |
|---|---|
| 0 | 2001(成功) |
| 1 | |
| 2 | 2G02(失敗) |
| 3 | 2001(成功) |
| 4 | - |
| 5 | 2001(成功) |
| 6 | - |
| 7 | 2G08(失敗) |
| 8 | 2001(成功) |
| 9 |
Refund
| 要求金額の 下1桁 | Refund （返金） |
|---|---|
| 0 | 2001(成功) |
| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | 2ED1 (ペンディング) |
| 8 | 2001(成功) |
| 9 |
- reasonに「fail」を指定した場合に、2GD3のエラーコードを返却します。
- 返戻されるエラーコード（vResultCode）につきましては、今後、予告なしに変更させて頂く場合がございます。
ペンディングとなった取引について、一定時間経過後以下の結果に遷移します。
| 要求金額の下1桁 | 結果コード |
|---|---|
| 7 | 2001(成功) |
ペイメントソース（paymentSource）について
Authorizeコマンド実行後、決済成功となった場合、以下のペイメントソース（paymentSource）を返戻します。
| paymentSource |
|---|
| 1022088000000000001 |