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

VeriTrans4G インターフェース詳細～PayPal 決済～
Ver. 1.0.2 （2019 年 10 月～）

Copyright (c) 2019 VeriTrans Inc., a Digital Garage company. All rights reserved.

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

目次
第1章

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

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

第2章

インターフェース詳細 ............................................................................................................................................................................................................ 5

2-1 共通 ......................................................................................................................................................................................................................................................................5
2-2 与信 ......................................................................................................................................................................................................................................................................6
2.2.1 要求電文 ： PaypalAuthorizeRequestDto .............................................................................................................................................................................................................................. 6
2.2.2 応答電文 ： PaypalAuthorizeResponseDto ............................................................................................................................................................................................................................ 8

2-3 売上 .................................................................................................................................................................................................................................................................... 11
2.3.1 要求電文 ： PaypalCaptureRequestDto................................................................................................................................................................................................................................ 11
2.3.2 応答電文 ： PaypalCaptureResponseDto..............................................................................................................................................................................................................................14

2-4 結果 .................................................................................................................................................................................................................................................................... 16
2.4.1 リダイレクト受信内容：PayPal から消費者ブラウザ経由で店舗へリダイレクト(GET)される内容 .....................................................................................................................................................16

2-5 キャンセル ........................................................................................................................................................................................................................................................... 17
2.5.1 要求電文 ： PaypalCancelRequestDto ..................................................................................................................................................................................................................................172.5.2 応答電文 ： PaypalCancelResponseDto ................................................................................................................................................................................................................................17

2-6 返金 .................................................................................................................................................................................................................................................................... 18
2.6.1 要求電文 ： PaypalRefundRequestDto .................................................................................................................................................................................................................................18
2.6.2 応答電文 ： PaypalRefundResponseDto ...............................................................................................................................................................................................................................18

2-7 結果通知............................................................................................................................................................................................................................................................. 19

第3章

その他 ............................................................................................................................................................................................................................... 20

3-1 売り手保護制度について ..................................................................................................................................................................................................................................... 20
3-2 処理結果コードが「pending(保留)」の取引について .............................................................................................................................................................................................. 21
2

VeriTrans4G インターフェース詳細 ～PayPal 決済～
3-3 token の有効期限について .................................................................................................................................................................................................................................. 21

3

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

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

1-2 著作権、および問い合わせ先[著作権]

本ドキュメントの著作権はベリトランス株式会社が保有しています。
Copyright (c) 2019 VeriTrans Inc., a Digital Garage company. All rights reserved.

[お問い合わせ先]

ベリトランス株式会社 テクニカルサポート

電子メール： tech-support@veritrans.jp

1-3 改訂履歴
2017/04 ：Ver1.0.0 リリース
2017/07 ：Ver1.0.1 リリース
「2-7 結果通知（PayPal 決済）」の記載内容見直し（速報と確報の違いを明確化）「3-2 処理結果コードが「pending(保留)」の取引について」を追加「3-3 token の有効期限について」を追加
2019/10 ：Ver1.0.2 リリース
「2-3 売上」 売上可能期間についての説明を修正「2-5 キャンセル」 にキャンセル可能期間を追記「2-6 返金」 に返金可能期間を追記「2-7 結果通知」 項目の並び順について追記

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

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

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

任意項目：△

設定不可：×

応答電文 … 必ず返戻：○

処理成功時のみ返戻：△

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

返戻なし：×

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

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

2-2 与信2.2.1 要求電文 ： PaypalAuthorizeRequestDto
要求電文 ： PaypalAuthorizeRequestDto
設定
フィールド名

項目名

書式・制限

説明

set

get

do

orderId

取引 ID

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

○

×

×

amount

決済金額

半角数字 7 桁以内

日本円

○

×

×

○

○

○

○

×

×

○

×

×

△

×

×

△

×

×

※日本円で 1,000,000 円を上限とした金額を指定します。
action

アクションタイプ

右記参照"set"： 与信請求処理"get"： 与信請求確認処理"do "： 与信請求完了処理

returnUrl

戻り先 URL

半角英数字 1024 桁以内

消費者が PayPal 上での操作が完了したときの遷移する店舗サイトの URL を指定
URL として使用できる文字も使用可能です。

cancelUrl

取消 URL

半角英数字 1024 桁以内

消費者が PayPal 上で支払いをキャンセルした場合に遷移する店舗サイトの URL を指定
URL として使用できる文字も使用可能です。

headerImageUrl

ヘッダーイメージ URL

半角英数字 127 桁以内

PayPal 画面のヘッダーに表示する画像の URL を指定画像サイズは最大 750pixel×90pixel です。
URL として使用できる文字も使用可能です。

orderDescription

オーダー説明文字列 127 バイト以内

商品の説明を指定※文字コードは"UTF-8"です。

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

要求電文 ： PaypalAuthorizeRequestDto
設定
フィールド名shippingFlag

項目名
配送先フラグ

書式・制限

説明

半角数字 1 桁

要求電文（PaypalAuthorizeRequestDto）の配送先情報（※1）を PayPal へ連携するか否かを指定

右記参照

また、配送先情報を連携しない場合は、消費者の PayPal アカウントに登録されている自宅住所等の情

set

get

do

○

×

×

※

×

×

報を利用するか否かを指定します。
shippingFlag"0"

配送先情報の連携について「配送先の設定を連携しない」
要求電文（PaypalAuthorizeRequestDto）の配送先情報（※1）は PayPal へ連携されません。
消費者が PayPal アカウントを保持している場合、消費者の PayPal アカウントに設定されている自宅住所等の情報が PayPal チェックアウト画面に表示されます。

"1"「配送先の設定を連携する」
要求電文（PaypalAuthorizeRequestDto）の配送先情報（※1）が PayPal へ連携されます。
本フラグに"1"を指定した場合、配送先情報（※1）の設定が必須となります。（任意項目を除く）PayPal へ連携された配送先情報が PayPal チェックアウト画面に表示されます。

"2"「配送先の設定を連携・表示しない」
要求電文（PaypalAuthorizeRequestDto）の配送先情報(※1)は PayPal へ連携されません。
消費者が PayPal アカウントを保持している場合でも、消費者の PayPal アカウントに設定されている自宅住所等の情報は PayPal チェックアウト画面に表示されません。

※1：要求電文（PaypalAuthorizeRequestDto）の配送先情報
配送先氏名（shipName）、配送先住所１（shipStreet1）、配送先住所２（shipStreet2）、
配送先市区町村名（shipCity）、配送先州名（shipState）、配送先国コード（shipCountry）、
配送先郵便番号（shipPostalCode）、配送先電話番号（shipPhone）
shipName

配送先氏名

文字列 32 バイト以内※文字コードは"UTF-8"※shippingFlag="1"の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

7

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

要求電文 ： PaypalAuthorizeRequestDto
設定
フィールド名shipStreet1

項目名
配送先住所１

書式・制限
文字列 100 バイト以内

説明※文字コードは"UTF-8"

set

get

do

※

×

×

△

×

×

※

×

×

※

×

×

※

×

×

※

×

×

△

×

×

×
×

×
○

○
○

※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目
shipStreet2

配送先住所２

文字列 100 バイト以内※文字コードは"UTF-8"※shippingFlag="1 "の場合は任意項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipCity

配送先市区町村名

文字列 40 バイト以内※文字コードは"UTF-8"※shippingFlag="1"の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipState

配送先州名

文字列 40 バイト以内※文字コードは"UTF-8"※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipCountry

配送先国コード

半角英数字 2 桁以内※shippingFlag="1"の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipPostalCode

配送先郵便番号

半角英数字 20 桁以内

半角英数字のほかに、"-"（ハイフン）も使用可能※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipPhone

配送先電話番号

半角英数字 20 桁以内

半角英数字のほかに、"-"（ハイフン）も使用可能※shippingFlag="1 "の場合は任意項目※ShippingFlag="0"または"2"の場合は設定不可項目

payerId

顧客番号

半角英数字 13 桁以内

顧客番号を指定します。PayPal から処理が戻ってきたとき、URL（戻り先 URL）に付加されています。

token

トークン

半角英数字 20 桁以内

決済サーバーから返される値を指定します。

2.2.2 応答電文 ： PaypalAuthorizeResponseDto
応答電文 ： PaypalAuthorizeResponseDto
設定
フィールド名
serviceType

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

書式・制限
半角英数字 10 文字以内

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

set

get

do

○

○

○

8

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

応答電文 ： PaypalAuthorizeResponseDto
設定
フィールド名mstatus

項目名
処理結果コード

書式・制限
半角英数字 32 文字以内

説明
"success" ： 正常終了
"failure"

set

get

do

○

○

○

○

○

○

○
○

○
○

○
○

○
○
○

△
○
○

△
○
○

△
△
△
×
×
×
×
×
×
×
×
×

×
△
△
△
△
×
×
×
×
×
×
※

×
△
△
△
△
△
△
△
△
△
△
×

： 異常終了"pending" ： 保留※"pending"はアクションタイプ（action）=”do”の場合のみ返戻されます。
vResultCode

詳細結果コード

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

merrMsg

エラーメッセージ

文字列 1024 バイト以内

処理結果を日本語又は英語で表示

marchTxn

電文 ID

文字列 100 桁以内

決済サーバーにて決済処理電文（内部処理も含む）毎に付与する ID
１つの取引 ID に対して、複数の ID が付与されます。

orderId

取引 ID

半角英数字 100 文字以内

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

custTxn

取引毎に付く ID

文字列 100 桁以内

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

txnVersion

MDK バージョン

半角英数字 5 桁

電文のバージョンloginUrl

ログイン URL

文字列

PayPal のログイン画面 URL

token

トークン

半角英数字 20 文字以内

クエリストリングとしてログイン URL に付加するトークン

invoiceId

請求番号

半角英数字 127 文字以内

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

payerId

顧客番号

半角英数字 13 文字以内

PayPal 側の消費者識別 ID

amount

取引金額

半角数字

決済要求時に設定した金額

feeAmount

手数料

半角数字

決済手数料

settleAmount

決済金額

半角数字

決済金額

exchangeRate

外貨換算レート

半角英数字 17 文字以内

決済時に適用された外貨換算レート。消費者のメイン通貨は日本円以外のみ。

paymentDate

支払時刻

半角英数字 14 文字

支払時刻

paymentStatus

支払ステータス

半角英数字

支払ステータス

centerAuthId

決済センタ承認 ID

半角英数字 17 文字以内

PayPal が発番するユニークな ID

shipName

配送先氏名

文字列

shippingFlag によって返戻内容が変わります。

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

"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

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

応答電文 ： PaypalAuthorizeResponseDto
設定
フィールド名shipStreet1

項目名
配送先住所１

書式・制限
文字列

説明
shippingFlag によって返戻内容が変わります。

set

get

do

×

※

×

×

※

×

×

※

×

×

※

×

×

※

×

×

※

×

×

※

×

"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし
shipStreet2

配送先住所２

文字列

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻（要求電文で設定した場合のみ返戻）"2"：返戻なし

shipCity

配送先市区町村名

文字列shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

shipState

配送先州名

文字列

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

shipCountry

配送先国コード

半角英数字 2 文字以内

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

shipPostalCode

配送先郵便番号

半角英数字 20 文字以内

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

shipPhone

配送先電話番号

半角英数字 20 文字以内

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻（要求電文で設定した場合のみ返戻）"2"：返戻なし

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

2-3 売上2.3.1 要求電文 ： PaypalCaptureRequestDto
要求電文 ： PaypalCaptureRequestDto
設定
フィールド名

項目名

書式・制限

説明
set

get

do

capt
ure

orderId

取引 ID

半角英数字 100 文字以内

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

○

×

×

○

amount

取引金額

半角数字 7 桁以内

日本円

○

×

×

○

action

アクションタイプ

半角英数字 10 文字以内

○

○

○

○

○

×

×

×

○

×

×

×

△

×

×

×

△

×

×

×

※日本円で 1,000,000 円を上限とした金額を指定します。
"set"： 売上請求処理"get"： 売上請求確認処理"do" ： 売上請求完了処理"capture" ： 売上請求完了処理※"capture"は 与信を行った場合にのみ、実行可能
returnUrl

戻り先 URL

半角英数字 1024 文字以内

消費者が PayPal 上での操作が完了したときの遷移する店舗サイトの URL を指定
URL として使用できる文字も使用可能です。

cancelUrl

取消 URL

半角英数字 1024 文字以内

消費者が PayPal 上で支払いをキャンセルした場合に遷移する店舗サイトの URL を指定
URL として使用できる文字も使用可能です。

headerImageUrl

ヘッダーイメージ URL

半角英数字 127 文字以内

PayPal 画面のヘッダーに表示する画像の URL を指定
画像サイズは最大 750pixel×90pixel です。
URL として使用できる文字も使用可能です。

orderDescription

オーダー説明文字列 127Byte 以内

商品の説明を指定※文字コードは"UTF-8"です。

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

要求電文 ： PaypalCaptureRequestDto
設定
フィールド名shippingFlag

項目名
配送先フラグ

書式・制限
半角英数字 1 文字以内

説明
要求電文（PaypalCaptureRequestDto）の配送先情報（※1）を PayPal へ連携するか否かを指定

set

get

do

capt
ure

○

×

×

×

また、配送先情報を連携しない場合は、消費者の PayPal アカウントに登録されている自宅住所等の情報を利用するか否かを指定します。
shippingFlag"0"

配送先情報の連携について「配送先の設定を連携しない」
要求電文（PaypalCaptureRequestDto）の配送先情報（※1）は PayPal へ連携されません。
消費者が PayPal アカウントを保持している場合、消費者の PayPal アカウン
トに設定されている自宅住所等の情報が PayPal チェックアウト画面に表示
されます。

"1"

「配送先の設定を連携する」
要求電文（PaypalCaptureRequestDto）の配送先情報（※1）が PayPal へ連携されます。
本フラグに"1"を指定した場合、配送先情報（※1）の設定が必須となりま
す。
PayPal へ連携された配送先情報が PayPal チェックアウト画面に表示されます。

"2"「配送先の設定を連携・表示しない」
要求電文（PaypalCaptureRequestDto）の配送先情報(※1)は PayPal へ連携されません。
消費者が PayPal アカウントを保持している場合でも、消費者の PayPal アカ
ウントに設定されている自宅住所等の情報は PayPal チェックアウト画面に表示されません。

※1：要求電文（PaypalCaptureRequestDto）の配送先情報
配送先氏名（shipName）、配送先住所１（shipStreet1）、配送先住所２（shipStreet2）、
配送先市区町村名（shipCity）、配送先州名（shipState）、配送先国コード（shipCountry）、
配送先郵便番号（shipPostalCode）、配送先電話番号（shipPhone）

12

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

要求電文 ： PaypalCaptureRequestDto
設定
フィールド名shipName

項目名
配送先氏名

書式・制限
文字列 32Byte 以内

説明※文字コードは"UTF-8"

set

get

do

capt
ure

※

×

×

×

※

×

×

×

△

×

×

×

※

×

×

×

※

×

×

×

※

×

×

×

※

×

×

×

△

×

×

×

※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目
shipStreet1

配送先住所１

文字列 100Byte 以内※文字コードは"UTF-8"※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipStreet2

配送先住所２

文字列 100Byte 以内※文字コードは"UTF-8"※shippingFlag="1 "の場合は任意項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipCity

配送先市区町村名

文字列 40Byte 以内※文字コードは"UTF-8"※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipState

配送先州名

文字列 40Byte 以内※文字コードは"UTF-8"※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipCountry

配送先国コード

半角英数字 2 文字以内

shipPostalCode

配送先郵便番号

半角英数字 20 文字以内

※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目
全角文字を除く文字列を設定※shippingFlag="1 "の場合は必須項目※ShippingFlag="0"または"2"の場合は設定不可項目

shipPhone

配送先電話番号

半角英数字 20 文字以内

全角文字を除く文字列を設定※shippingFlag="1 "の場合は任意項目※ShippingFlag="0"または"2"の場合は設定不可項目

payerId

顧客番号

半角英数字 13 文字以内

PayPal から処理が戻ってきたとき、URL（戻り先 URL）に付加されています。

×

×

○

×

token

トークン

半角英数字 20 文字以内

トークンを設定

×

○

○

×

13

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

2.3.2 応答電文 ： PaypalCaptureResponseDto
応答電文 ： PaypalCaptureResponseDto
設定
フィールド名

項目名

書式・制限

説明

set

get

do

capt
ure

serviceType

決済サービスタイプ

半角英数字 10 文字以内

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

○

○

○

○

mstatus

処理結果コード

半角英数字 32 文字以内

"success" ： 正常終了

○

○

○

○

○

○

○

○

"failure"： 異常終了"pending" ： 保留※"pending"はアクションタイプ（action）="do "又は"capture"の場合のみ返戻されます。
vResultCode

詳細結果コード

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

merrMsg

エラーメッセージ

文字列 1024 バイト以内

処理結果を日本語又は英語で表示

○

○

○

○

marchTxn

電文 ID

文字列 100 桁以内

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

○

○

○

○

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

取引 ID

半角英数字 100 文字以内

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

○

△

△

○

custTxn

取引毎に付く ID

文字列 100 桁以内

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

○

○

○

○

txnVersion

MDK バージョン

半角英数字 5 桁

電文のバージョン

○

○

○

○

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

ログイン URL

文字列

PayPal のログイン画面 URL

△

×

×

×

token

トークン

半角英数字 20 文字以内

クエリストリングとしてログイン URL に付加するトークン

△

△

△

×

invoiceId

請求番号

半角英数字 127 文字以内

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

△

△

△

△

payerId

顧客番号

半角英数字 13 文字以内

PayPal 側の消費者識別 ID

×

△

△

×

amount

取引金額

半角数字

決済要求時に設定した金額

×

△

△

△

feeAmount

手数料

半角数字

決済手数料

×

×

△

△

settleAmount

決済金額

半角数字

決済金額

×

×

△

△

exchangeRate

外貨換算レート

半角英数字 17 文字以内

決済時に適用された外貨換算レート。消費者のメイン通貨は日本円以外のみ。

×

×

△

△

paymentDate

支払時刻

半角英数字 14 文字

支払時刻

×

×

△

△

paymentStatus

支払ステータス

半角英数字

支払ステータス

×

×

△

△

centerTxnId

決済センタ取引 ID

半角英数字 19 文字以内

PayPal が発番するユニークな ID

×

×

△

△
14

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

応答電文 ： PaypalCaptureResponseDto
設定
フィールド名shipName

項目名
配送先氏名

書式・制限
文字列

説明
shippingFlag によって返戻内容が変わります。

set

get

do

capt
ure

×

※

×

×

×

※

×

×

×

※

×

×

×

※

×

×

×

※

×

×

×

※

×

×

×

※

×

×

"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし
shipStreet1

配送先住所１

文字列

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

shipStreet2

配送先住所２

文字列

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻（要求電文で設定した場合のみ返戻）"2"：返戻なし

shipCity

配送先市区町村名

文字列shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

shipState

配送先州名

文字列

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

shipCountry

配送先国コード

半角英数字 2 文字以内

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

shipPostalCode

配送先郵便番号

半角英数字 20 文字以内

shippingFlag によって返戻内容が変わります。
"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻"2"：返戻なし

15

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

応答電文 ： PaypalCaptureResponseDto
設定
フィールド名shipPhone

項目名
配送先電話番号

書式・制限
半角英数字 20 文字以内

説明shippingFlag によって返戻内容が変わります。

set

get

do

capt
ure

×

※

×

×

"0"：成功時のみ PayPal アカウントの配送先が返戻"1"：成功時のみ要求電文に設定した配送先が返戻（要求電文で設定した場合のみ返戻）"2"：返戻なし※売上可能期間について
PayPal は、与信が成功してから 3 日以内であれば、原則として売上処理の成功を保証します。
ただし、以下の２つのケースでは売上処理はエラーとなります。
１） 消費者の PayPal アカウントが制限またはロックされている場合
２） 店舗様のアカウントの制限レベルが高い場合（リスクが高いアカウントの場合）
なお、与信が成功してから 3 日以内でなくとも、 最大 29 日間は売上処理を要求することが可能ですが、成功は保証されないため、この点には十分ご注意ください。

2-4 結果2.4.1 リダイレクト受信内容：PayPal から消費者ブラウザ経由で店舗へリダイレクト(GET)される内容
PayPal から消費者ブラウザを経由して店舗様サイトへ送信される項目となります。このリダイレクトを受信し、get または do を行います。

リダイレクト受信内容：PayPal から消費者ブラウザ経由で店舗へリダイレクト(GET)される内容
フィールド名

項目名

書式・制限

説明

設定

token

トークン

半角英数字 20 文字以内

クエリストリングとしてログイン URL に付加するトークン○

PayerId

顧客番号

半角英数字 13 桁以内

顧客番号を指定。PayPal から処理が戻ってきたとき、URL（戻り先 URL）に付加されています。

○

16

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

2-5 キャンセル
※キャンセル処理は与信を実施した取引（PaypalAuthorizeRequestDto にて action="do "（与信請求完了処理））のみに実行可能です。
また、与信後に売上まで実施した取引（PaypalCaptureRequestDto にて action="capture"（売上請求完了処理））には実行できません。
キャンセルが可能な期間は、与信を実施した日から 30 日間となります。30 日以内に売上処理されなかった与信は自動的にキャンセルになります。

2.5.1 要求電文 ： PaypalCancelRequestDto
要求電文 ： PaypalCancelRequestDto
フィールド名orderId

項目名
取引 ID

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

説明

設定

○

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

2.5.2 応答電文 ： PaypalCancelResponseDto
応答電文 ： PaypalCancelResponseDto
フィールド名

項目名

書式・制限

説明

serviceType

決済サービスタイプ

半角英数字 10 文字以内

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

mstatus

処理結果コード

半角英数字 32 文字以内

"success" ： 正常終了
"failure"

設定○○： 異常終了"pending" ： 保留vResultCode

詳細結果コード

半角英数字 16 文字処理の結果を詳細に表すコード○

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

エラーメッセージ

文字列 1024 バイト以内

処理結果を日本語又は英語で表示

marchTxn

電文 ID

文字列 100 桁以内

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

orderId

取引 ID

半角英数字 100 文字以内

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

custTxn

取引毎に付く ID

文字列 100 桁以内

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

txnVersion

MDK バージョン

半角英数字 5 桁

電文のバージョン○○

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

○○○

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

17

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

2-6 返金※返金処理は与信後に売上まで実施した取引（PaypalCaptureRequestDto にて action="capture"（売上請求完了処理））にのみ実行可能です。
返金が可能な期間は、売上実施日から 180 日間となります。

2.6.1 要求電文 ： PaypalRefundRequestDto
要求電文 ： PaypalRefundRequestDto
フィールド名

項目名

書式・制限

説明

orderId

取引 ID

半角英数字 100 桁以内

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

amount

取引金額

半角数字 7 桁以内返金する金額を指定 ※一部キャンセルも可能

設定

○
○

2.6.2 応答電文 ： PaypalRefundResponseDto
応答電文 ： PaypalRefundResponseDto
フィールド名

項目名

書式・制限

説明

serviceType

決済サービスタイプ

半角英数字 10 文字以内

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

mstatus

処理結果コード

半角英数字 32 文字以内

"success" ： 正常終了
"failure" ： 異常終了
"pending" ： 保留vResultCode

詳細結果コード

半角英数字 16 文字

merrMsg

エラーメッセージ

文字列 1024 バイト以内

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

marchTxn

電文 ID

文字列 100 桁以内

orderId

取引 ID

半角英数字 100 文字以内

決済サーバーにて決済処理電文（内部処理も含む）毎に付与する ID
１つの取引 ID に対して、複数の ID が付与されます。
決済要求時に店舗様にて任意に採番し送信された取引 ID

custTxn
txnVersion

取引毎に付く ID
MDK バージョン

文字列 100 桁以内
半角英数字 5 桁

決済サーバーがオーダー（取引 ID）と紐付ける為に採番する ID
電文のバージョン ※問題発生時などに用いますが、通常ご利用になることはありません。

feeRefundAmountrefundAmount

払い戻し手数料
返金金額

半角数字
半角数字

netRefundAmountprincipalAmount

純返金金額
元金額

半角数字
半角数字

settlementBalance
invoiceId

決済残高
請求番号

半角数字
半角英数字 127 文字以内

centerTxnId

決済センタ取引 ID

半角英数字 19 文字以内

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

設定

○
○

○

○
○
○
○
○
△
△
△
△
△
△
△
18

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

2-7 結果通知
PayPal 決済の結果通知には、速報と確報の 2 種類があります。
速報通知： 売上/返金の要求に対し、PayPal から成功応答を受信した直後に店舗様に送信します。（成功時のみ送信）
確報通知： 売上/返金の翌日以降に PayPal が作成する取引明細レポートの結果を、確定情報として店舗様に送信します。（成功、失敗を問わず送信）

確報通知は、原則として N+1 日に、N 日 0 時～24 時の取引明細を元に送信します。



速報の結果とは異なるステータスを通知する場合があります。



確報通知の処理結果コードが「保留」の場合は、その後「成功」または「失敗」に変更されます。その際は確報通知が再度送信されます。



消費者から異議申立てを受けた取引等は、N+1 日以降の取引明細レポートで結果が確定する場合がありますので、確報通知は N+1 日以降に送信される可能性があります。

結果通知に関するサービス共通の仕様については、『開発ガイド』を併せてご参照ください。
項番フィールド名

項目名

書式・制限

説明

1

numberOfNotify

通知件数

半角数字 4 桁以内

1 度に通知可能な件数は 1,000 件 （1,001 件以上は次回通知）

2

pushTime

送信時刻

半角数字 14 桁

決済サーバーから通知した時刻 （YYYYMMDDhhmmss 形式）

3

pushId

識別 ID

半角数字 8 桁

プッシュ処理を行うたびに採番される ID

4

fixed

速報・確報フラグ

半角数字 1 桁

注） 他の決済サービスで使用された ID と重複する場合があります。
"0"：速報データ"1"：確報データ

通知件数分下記の項番（5～12）を繰り返す。尚、フィールド名の後ろに 4 ケタの連番（0000～0999）を付与する。
5

orderId

取引 ID

半角英数字 100 桁以内

6mstatus

処理結果コード

半角英数字 32 文字以内

"success"：成功

7

txnType

トランザクションタイプ

半角英数字 32 桁以内"Capture"：売上 "Refund"：返金

8

receivedDatetime

受付日時

半角数字 14 桁

YYYYMMDDhhmmss 形式

9amount金額

半角数字 10 桁以内

決済要求時に設定した金額または返金金額

10payerId

お客様番号

半角英数字 13 桁以内

PayPal 側の消費者識別 ID

11

centerTxnId

取引識別子

半角英数字 19 桁以内

12

dummy

ダミー決済フラグ

半角数字 1 桁"failure"：失敗"pending"：保留ダミーデータを示す場合は"1"を設定（注意事項）


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



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

19

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

第3章 その他
3-1 売り手保護制度について「売り手保護制度」とは、消費者が PayPal 決済を利用し商品を購入した際、「未承認取引」や「商品未受領」等を理由とした消費者からのクレーム、チャージバック、支払いの取り消しが発生した場合に、店舗様が保護されるプログラムです。
尚、「売り手保護制度」は PayPal 社が提供する保護プログラムであり、その保護を受けるためには PayPal 社が定める適用条件を満たす必要があります。

「売り手保護制度」の対象とするためには、与信時（Authorize コマンド）、与信同時売上時（Capture コマンド）とも、アクションタイプが"get"で送信された要求電文（PaypalAuthorizeRequestDto／
PaypalCaptureRequestDto）に対応する応答電文（PaypalAuthorizeResponseDto／PaypalCaptureResponseDto）にて返戻される配送先情報※1 へ配送するようお願いいたします。

※1：応答電文（PaypalAuthorizeResponseDto／PaypalCaptureResponseDto）にて返戻される配送先情報
配送先氏名（shipName）、配送先住所１（shipStreet1）、配送先住所２（shipStreet2）、配送先市区町村名（shipCity）、配送先州名（shipState）、配送先国コード（shipCountry）、
配送先郵便番号（shipPostalCode）、配送先電話番号（shipPhone）

ただし、上記配送先情報へ配送した場合でも、必ず「売り手保護制度」の対象になるとは限りませんので、ご注意ください。
詳細につきましては、以下をご参照ください。
https://www.paypal.com/jp/webapps/mpp/ua/useragreement-full?locale.x=ja_JP#bus_premier_9
https://www.paypal.jp/jp/contents/support/faq/faq-060/

また、与信時（Authorize コマンド）、与信同時売上時（Capture コマンド）とも、要求電文（PaypalAuthorizeRequestDto／PaypalCaptureRequestDto）にて「配送先フラグ（shippingFlag）」に"2"（配送先の設定を連携・表示しない）を設定していた場合は、「売り手保護制度」の対象とはなりません。

20

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

3-2 処理結果コードが「pending(保留)」の取引について決済要求の結果、PayPal 側で保留判定となった場合は、処理結果コード「pending(保留)」を返します。保留となった取引については、その後、PayPal 側で「成功」または「失敗」の判定に変更されたら、弊社よりマーチャント様に確報通知を送信します。
保留判定となった原因につきましては、弊社より PayPal 社に確認いたしますので、弊社にお問い合わせください。

3-3 token の有効期限について
token の有効期限は発行後 3 時間です。
有効期限を超過すると PayPal 社にて決済の継続が拒否されます。
注） 2017 年 7 月現在の仕様です。この仕様は、PayPal 社にて予告なしに変更される可能性があります。

21