ペイパルエクスプレスチェックアウトインテグレーションガイド

ペイパルエクスプレス
チェックアウト
インテグレーションガイド
最終更新日:2012年12月
PayPal エクスプレスチェックアウトインテグレーションガイド
文書番号: 100010.en_US-201212
© 2012 PayPal, Inc. All rights reserved. PayPal はPayPal, Inc.の登録商標です。PayPal ロゴはPayPal, Inc.の商標です。その他の商標およびブランドはそれぞれ各
社に帰属します。
本書に記載の情報はPayPal, Inc.に帰属します。PayPal, Inc.の書面による承認なしに情報を使用、複製、開示することはできません。Copyright © PayPal. All rights
reserved. PayPal S.à r.l. et Cie, S.C.A.、Société en Commandite par Actions登録住所：22-24 Boulevard Royal, L¬ 2449, Luxembourg, R.C.S. Luxembourg
B 118 349
消費者の皆様へ: PayPal™ 決済サービスは、シンガポールの法律上ではストアドバリュー設備とみなされています。よってシンガポール通貨金融庁（Monetary Authority
of Singapore）の承認を必要としません。ご利用の際には契約条件をよくご確認ください。
免責の告知:
PayPal, Inc.は、本書の内容を誤りも含めて「現状」で提供しています。PayPal, Inc.は本書の内容に関していかなる種類の（明示的、暗示的、法的）保証もいたしません。
PayPal, Inc.は、誤りや脱落に起因する、あるいは本書または本書の内容を使用した結果生じる、あるいは本書に記載の製品またはサービスの適用または使用の結果生じる
（直接的または間接的）損害に対していかなる責任も負わないものとします。PayPal, Inc.は、本書に記載のいかなる情報も予告なしに変更できる権利を留保します。
目次
はじめに·······························································································7
本ガイドについて ························································································· 7
対象 ·········································································································· 7
参考文書 ···································································································· 7
本書に対するフィードバック ··········································································· 7
Chapter 1
エクスプレスチェックアウトの導入 ········································9
エクスプレスチェックアウトの主な特徴 ···························································· 9
エクスプレスチェックアウト体験 ······························································ 10
ご利用可能な国・通貨·············································································· 12
エクスプレスチェックアウトとショッピングカートの関係 ····································· 12
エクスプレスチェックアウトの前提条件 ··························································· 12
もっとも簡単なエクスプレスチェックアウトインテグレーションの
インプリメンテーション ················································································ 13
エクスプレスチェックアウトボタンとPayPalマークの入手 ······························ 13
コーディングを開始する前に ····································································· 15
エクスプレスチェックアウト取引の設定 ······················································ 16
エクスプレスチェックアウト取引詳細の取得 ················································ 18
エクスプレスチェックアウト取引の完了 ······················································ 19
エクスプレスチェックアウトインテグレーションのテスト ······························ 20
セキュリティ ························································································· 24
エクスプレスチェックアウトインテグレーションのトラブルシューティング ············· 25
エラー処理 ··························································································· 25
タイムアウト ························································································· 26
APIオペレーションのロギング ··································································· 26
値のエンコーディングとデコーディング ······················································· 26
エクスプレスチェックアウトの特徴································································· 26
エクスプレスチェックアウトユーザーインターフェイスのカスタマイズ ·············· 27
決済と支払いの回収 ················································································ 27
払戻し ································································································· 28
定期支払い ··························································································· 28
モバイルエクスプレスチェックアウト ······················································· 29
エクスプレスチェックアウトを利用した平行支払い ········································ 29
エクスプレスチェックアウトインテグレーションガイド
2012年12月
目次
不正防止管理フィルタ·············································································· 29
イベント通知 ························································································· 29
動的画像の概要 ······················································································ 30
エクスプレスチェックアウト即時更新 ························································· 30
エクスプレスチェックアウト導入手順 ······························································ 30
エクスプレスチェックアウトボタン ·························································· 31
エクスプレスチェックアウトAPIオペレーション ············································ 31
エクスプレスチェックアウトコマンド ······················································· 32
エクスプレスチェックアウトトークンの使用 ··············································· 33
Chapter 2
エクスプレスチェックアウトユーザーインターフェイス要件 ······· 35
エクスプレスチェックアウトフロー ······························································· 35
決済指定ポイント ··················································································· 36
支払いオプション指定ポイント ·································································· 36
ペイパルボタンとロゴ画像 ············································································· 37
エクスプレスチェックアウト画像タイプ ······················································ 37
エクスプレスチェックアウト画像 ······························································ 37
支払いマーク ························································································· 38
Chapter 3
関連APIオペレーション ····················································· 39
エクスプレスチェックアウト用の販売支払いアクション········································ 39
エクスプレスチェックアウト用の与信支払いアクション········································ 39
エクスプレスチェックアウト用の注文支払いアクション········································ 40
払戻しの実行 ······························································································ 41
Chapter 4
ペイパルSDKとエクスプレスチェックアウトの統合 ·················· 43
Chapter 5
エクスプレスチェックアウトインテグレーションの実稼働 ········· 45
Chapter A
API信用証明書の取得 ························································ 47
API署名の作成 ···························································································· 47
API証明書の作成 ························································································· 48
証明書をPKCS12形式で暗号化する ····························································· 49
証明書のインポート ················································································ 50
Chapter B
ペイパルName-Value Pair APIの基本 ································ 53
ペイパルAPI クライアントサーバーアーキテクチャー ········································ 53
4
2012年12月
エクスプレスチェックアウトインテグレーションガイド
目次
ペイパルName-Value Pair APIリクエスト・レスポンス ··································· 54
UTF-8 文字エンコーディング ···································································· 54
複数のAPIオペレーション ········································································· 54
NVP形式 ··································································································· 55
NVPリクエストの作成··················································································· 56
ペイパルAPIオペレーションの指定 ······························································ 56
API信用証明書の指定 ·············································································· 57
URL エンコーディング ············································································ 58
Name-Value Pairのリスト構文·································································· 59
NVP APIオペレーションの実行 ······································································· 59
ペイパルサーバーの指定 ··········································································· 60
APIオペレーションのロギング ··································································· 60
NVPレスポンスへの対応 ················································································ 60
共通レスポンスフィールド ········································································ 61
エラーレスポンス ··················································································· 61
URLデコーディング ················································································ 62
Chapter C
ペイパルSOAP API の基本 ················································ 63
ペイパルWSDL/XSDスキーマ定義 ··································································· 64
ペイパルSOAP APIの定義·············································································· 64
セキュリティ ······························································································ 65
SOAP RequesterCredentials:ユーザー名、パスワード、署名、件名 ························ 65
SOAPサービスエンドポイント ········································································ 66
SOAP リクエストエンベロープ ······································································· 66
リクエストの構造 ························································································ 67
SOAPメッセージスタイル：doc-literal ····························································· 69
レスポンスの構造 ························································································ 69
エラーレスポンス ························································································ 70
ペイパルに問題を報告するためのCorrelationID ·················································· 72
UTF-8 文字エンコーディング ········································································· 72
日付形式 ··································································································· 72
基幹通貨金額の基本データタイプ ····································································· 72
改訂履歴
··············································································
エクスプレスチェックアウトインテグレーションガイド
2012年12月
75
5
目次
6
2012年12月
エクスプレスチェックアウトインテグレーションガイド
はじめに
本ガイドについて
本書では基本的なエクスプレスチェックアウトインテグレーションについて説明します。
対象
本書はエクスプレスチェックアウトのインプリメントを検討中のマーチャントやデベロッパーを対象
としています。
参考文書

エクスプレスチェックアウト応用機能ガイド

Name/Value Pair（NVP）APIデベロッパーガイド

SOAP API デベロッパーリファレンス

マーチャント設定・管理ガイド
本書に対するフィードバック
本書の改良のため、以下のアドレスまでフィードバックをお送りください。
[email protected]
エクスプレスチェックアウトインテグレーションガイド
2012年12月
7
はじめに
本書に対するフィードバック
8
2012年12月
エクスプレスチェックアウトインテグレーションガイド
1
Chapter 1
エクスプレスチェックアウトの
導入
エクスプレスチェックアウトボタンは、買い手に新しい支払い方法を提供するとともに、お客様の既
存の支払い手段を補足します。オンラインショッパーは、ペイパル残高、銀行口座、クレジットカード
で支払いを行えるペイパルの利便性やセキュリティを高く評価しています。
エクスプレスチェックアウトの主な特徴
エクスプレスチェックアウトによって、買い手はペイパルでの支払いを素早く簡単に行うことができま
す。エクスプレスチェックアウトでは、注文の詳細、発送オプション、保険の選択、税金の合計など、
取引の詳細を一括表示しますので、買い手が決済を行わない主な原因の1つを解決できます。
エクスプレスチェックアウトボタンをお客様のウェブサイトに追加した場合、売り上げを18%まで増
やすことができるという調査結果が出ています。既存のチェックアウトボタンとエクスプレスチェック
アウトボタンを並べて配置したウェブページを以下に示します。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
9
エクスプレスチェックアウトの導入
エクスプレス
チェックアウトの主な特徴
エクスプレスチェックアウトによって以下のことが可能になります。

ペイパルアカウントからの支払いを受け付けることができます。

顧客が配送、請求、支払いなどの個人情報を入力する必要がありません。

取引終了後も、顧客がお客様のサイトから移動しません。

一定の間隔で支払いができるように顧客を登録することができます。

その他の情報はこちらへ：https://merchant.paypal.com/cgibin/marketingweb?cmd=_render-content&content_ID=merchant/express_checkout&na
v=2.1.5
エクスプレスチェックアウト体験
エクスプレスチェックアウトを利用すると、買い手はオンライン決済をより簡単に行えるようになりま
す。お客様は買い手および全体の決済フローを管理しながら、ペイパルによる決済を受け付けられるよ
うになります。
エクスプレスチェックアウトをインプリメントする前に、買い手がどのような操作を行うのかシミュ
レーションしてみてください。一般的な流れを以下に示します。
10
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
エクスプレス
チェックアウトの主な特徴
一般的な決済フロー
一般的な決済フローでは、買い手は次のような操作を行います。
1. ショッピングカートページから決済を行う。
2. 配送先情報を入力する。
3. 支払い方法を選択し、請求・支払い情報を入力する。
4. 注文を見直し、支払いを行う。
5. 注文確定書を受け取る。
エクスプレスチェックアウトフローでも同じように最初に決済を行います。しかし、エクスプレス
チェックアウトではペイパルが保存している情報を利用するため、買い手が発送、請求、支払い情報を
入力する必要がありません。これによって決済処理を簡素化し素早く行うことができます。
エクスプレスチェックアウトのフローを以下に示します。
エクスプレスチェックアウトフロー
エクスプレスチェックアウトフローでは、買い手は次のような操作を行います。
1. [Check out with PayPal]ボタン（ペイパルでチェックアウトボタン）をクリックしエクスプレ
スチェックアウトを選択する。
2. ペイパルにログインし、ID認証を行う。
3. ペイパルでの取引を確認する。
注：オプションで（上の図には表示がありませんが）
、買い手がお客様のサイトで注文確認を行うこ
とも可能です。また、お客様の「注文確認」ページにアップセルを追加するなど、その他の決
済手順を追加することも可能です。
4. お客様のサイトで注文を確認し支払いを行う。
5. 注文確認書を受け取る。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
11
エクスプレスチェックアウトの導入
エクスプレス
チェックアウトとショッピングカートの関係
ご利用可能な国・通貨
エクスプレスチェックアウトをご利用になると様々な国および地域から支払いを受け付けることがで
きます。決済フローは地域ごとにローカライズされます。
エクスプレスチェックアウトでご利用可能な国および通貨については、ペイパルご利用可能国情報
（PayPal Offerings Worldwide）をご覧ください。地域別のフローと追加の国情報については、世界中で
より安全な支払いと受け取り（Send and Receive Payments Securely Worldwide）をご覧ください。
エクスプレスチェックアウトとショッピングカートの関係
お客様がご自身のショッピングカートを持っておらず、お客様のウェブサイトとエクスプレスチェック
アウトを統合していない場合、サードパーティのショッピングカートをご利用になるかと思います。
ショッピングカートは買い手が商品を入れておき、決済の際に商品の合計を計算するソフトウェアです。
ペイパルの提携会社が様々なショッピングカートをご用意しており、どれもペイパルで利用可能である
ことは言うまでもなく、お客様の買い手が安全に商品を購入できるようにサポートします。ショッピン
グカートベンダーは、自社製品をお客様のウェブサイトに組み込むための手順をご用意しています。ご
利用可能なショッピングカートにつきましてはペイパル提携会社一覧（パートナーディレクトリ）をご
覧ください。
重要：ショッピングカートをご選択の際、ペイパルへのご連絡は不要です。ペイパルはショッピングカー
トベンダーに対し何の権限も持っていないため、サードパーティ製ショッピングカートの組み込
みまたは使用によって生じる問題の解決には一切関与することができません。
エクスプレスチェックアウトの前提条件
エクスプレスチェックアウトの導入には、お客様が必要とするペイパルアカウントのタイプとプログラ
ミング技術と経験が必要となります。エクスプレスチェックアウトを利用したいけれど、必要な技術と
経験がない場合には、ペイパルウェブペイメントスタンダードや、ペイパルやサードパーティが提供す
るショッピングカートをご利用ください。
以下にエクスプレスチェックアウトを利用するために必要な項目をご説明します。
12

ビジネスアカウントまたはプレミアアカウント。ビジネスアカウントまたはプレミアアカウントを取
得すると、お客様の代わりにペイパルが買い手から商品やサービスの代金を回収します。この場合、
ペイパルが代金回収処理を管理し、お客様から少額の手数料と取引ごとに買い手から回収した代金か
ら一定の歩合をいただきます。

テスト用アカウント2件付きSandboxアカウント。ペイパル Sandboxはペイパルのシミュレーショ
ンの実施環境を提供しますので、お金のやりとりを実際に行うことなくエクスプレスチェックアウト
を組み込むことができます。一方のテスト用アカウントはお客様をマーチャント（Sandbox用語で
は売り手）とみなし、もう一方では買い手とみなします。テストはこの2つのアカウントに限定しま
せんが、テスト用アカウントを作成し実際のテストを行うためにはSandboxアカウントを保有する
必要があります。

HTML体験。おそらくお客様はすでにウェブサイトをお持ちであり、ご自身のサイトで販売している
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
商品やサービス用の決済を体験済みかもしれません。この場合、[Check out with PayPal]ボタ
ンと[Express Checkout]マーク（エクスプレスチェックアウトマーク）と呼ばれるボタンを、ご
自身のウェブページに追加する必要があります。[Check out with PayPal]ボタンをクリックし
てペイパルの決済フローを開始します。買い手がエクスプレスチェックアウト決済を開始していな
い場合には、買い手は[Express Checkout]マークを利用して、支払い方法を指定するページ（支払
いページ）からエクスプレスチェックアウトを選択できます。

プログラミング体験。買い手がボタンをクリックしたときに、ペイパルサーバーに対し取引の設定や
処理を要求するコードや、レスポンスを処理するコードを提供しなければなりません。ペイパルは
HTTPリクエスト・レスポンスモデルをベースにした使い勝手のよいインターフェイスや、やや複雑
なSOAPウェブサービスを提供しています。ペイパルは、PHP、Ruby、Java、C#のような.NET言
語など多様なプログラミング言語のインターフェイスを提供するSoftware Development Kits
（SDKs）も提供しています。特定の言語の知識は必要ありませんが、プログラミング論理、特にリ
クエスト・レスポンスモデル、エラー処理、アプリケーションレベルのコード記述のニュアンスを理
解する必要があります。
注：もしプログラミング体験の前提条件の内容が難しい場合には（インターフェイスが何かわからな
い場合など）ペイパルやほかのショッピングカートベンダーが提供するエクスプレスチェック
アウトや、ウェブペイメントスタンダードなどほかのペイパル製品をご利用ください。十分な
プログラミング経験をお持ちでない限り、ご自身でエクスプレスチェックアウトの組み込みを
行うことはお薦めしません。プログラマやデベロッパーはエクスプレスチェックアウトを簡単に
使用できます。しかし、まったくの初心者が使用した場合、販売や商品を失うだけでなく、その
ことに気づかない場合もあります。
もっとも簡単なエクスプレスチェックアウトインテグレーションのイン
プリメンテーション
もっとも簡単なエクスプレスチェックアウトインテグレーションは、お客様がペイパルボタンを設定
し、お客様の買い手が[SetExpressCheckout]、[DoExpressCheckoutPayment]、
[GetExpressCheckoutDetails]のいずれかのボタンをクリックした際に、必要なペイパルAPIオペレー
ションを呼び出す方法です。
この場合、買い手が決済を開始した後、支払い方法にペイパルを選択する必要があります。これらのAPI
オペレーションは2箇所で行います。お客様ご自身の決済ページと支払い方法ページです。
関連情報:
35ページ「エクスプレスチェックアウトフロー」
エクスプレスチェックアウトボタンとPayPalマークの入手
ペイパルをご利用になる場合には、安全なペイパルサーバーがホストする[Check out with PayPal]
ボタンと[PayPal]マークをご使用ください。ボタンやマークが更新された場合は、自動的に新しいも
のがお客様のアプリケーションに表示されます。
エクスプレスチェックアウトボタンはお客様の決済ページに追加してください。以下の手順に従って
エクスプレスチェックアウトボタンを入手します。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
13
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
1. PayPal ボタンコードページ（https://www.paypal.com/express-checkout-buttons）にアクセ
スします。
以下に示すようなページが表示されます。
2. ボタンの下のウィンドウから画像ソーステキストを選択しコピーします。
3. お客様の決済ページのHTMLソース内でボタンを追加したい箇所に画像ソーステキストを貼り付け
ます。
結果:
ブラウザでお客様の決済ページを表示すると、[Check out with PayPal]ボタンが以下のように表示
されます。
タスク終了後:
[PayPal]マーク画像をお客様の支払いページに追加してください。画像は上述のボタンと同じ方法で
入手できます。マーク画像はエクスプレスチェックアウトボタンと同じボタンコードページ
（https://www.paypal.com/express-checkout-buttons）で入手できます。
14
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
コーディングを開始する前に
ペイパルAPIがどのように機能するかご存じない場合は本セクションをお読みください。ペイパル
Name/Value Pair（NVP）APIのご利用に最小限必要な情報をご説明します。
ペイパルAPIクライアントサーバーアーキテクチャー
ペイパルAPIは、お客様のウェブサイトがペイパルサーバーのクライアントとなるクライアントサー
バーモデルを使用しています。
お客様のウェブサイト上のページがペイパルAPIサーバーに要求を送信し、サーバー上のアクションを開
始します。ペイパルAPIサーバーは要求されたアクションが行われたこと、あるいはエラーが発生したこ
とを示すレスポンスを返します。レスポンスにはリクエストに関連する追加情報を含む場合があります。
以下の図に基本的なリクエスト・レスポンスのメカニズムを示します。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
15
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
たとえば、お客様が買い手の配送先住所をペイパルから入手したいとします。この場合、お客様は買い
手の詳細情報を入手するAPIオペレーションを指定するリクエストを開始します。ペイパルAPIサーバー
からのレスポンスにはリクエストが成功したかどうかの情報が含まれます。リクエストが成功した場合
には、レスポンスには要求された情報が含まれます。上記の例の場合には、買い手の配送先住所が含ま
れることになります。リクエストが失敗した場合には、1件以上のエラーメッセージがレスポンスに含ま
れます。
関連情報：
56ページ「NVPリクエストの作成」
60ページ「NVPレスポンスへの対応」
API信用証明書の入手
ペイパルAPIを利用するには、さまざまなAPIオペレーションを許可されているペイパルビジネスアカウ
ントまたはプレミアアカウント保持者であることを示すAPI信用証明書の入手が必要です。信用証明書と
してAPI署名またはAPI証明書のどちらを使用しても構いませんが、署名のご使用をお勧めします。
重要：署名と証明書の両方を保有することは可能ですが、両方同時に使用することはできません。
エクスプレスチェックアウト取引の設定
エクスプレスチェックアウト取引を設定するには、SetExpressCheckout APIオペレーションを呼び出
して、支払いフローを開始するために必要な情報を提供し、オペレーションが成功した場合にはペイパ
ルにリダイレクトする必要があります。
この例では、お客様がペイパルサーバーとの通信に使用する仕組みを設定済みであり、API信用証明書付
きのペイパルビジネスアカウントを保持しているものとします。また支払いアクションが最終的な販売
であると仮定します。
エクスプレスチェックアウト取引を設定する場合、SetExpressCheckoutリクエストの値を指定し、
APIを呼び出します。指定した値によってペイパルのページフローとお客様とお客様の買い手が利用可能
なオプションを制御します。オプションを後から追加できるスタンダードエクスプレスチェックアウ
ト取引の設定から初めてください。
スタンダードエクスプレスチェックアウト取引の最も簡単な設定方法を以下にご説明します。
1. SetExpressCheckout APIオペレーションの実行と使用したいバージョンを指定します。
METHOD=SetExpressCheckout
VERSION=XX.0
2. お客様のAPI信用証明書を指定します。
署名用の以下のパラメータを使用します。
16
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
USER=API_username
PWD=API_password
SIGNATURE=API_signature
Sandbox内ではいつでも以下の署名が使用できます。
USER=sdk-three_api1.sdk.com
PWD=QFZCWN5HZM8VBG7Q
SIGNATURE=A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU
3. 取引金額を指定します。USドル以外の通貨をご利用の場合は通貨も指定します。
取引の合計金額がわかっている場合は合計金額を指定します。合計金額が不明な場合は小計を指定し
ます。指定の通貨にかかわらず、小数点の右側は 2 桁で、左側はオプションで 3 桁ずつコンマで
区切ります。
たとえば、€2.000,00 EURは2000.00または2,000.00のように表記します。通貨にかかわらず、
＄10,000.00 USDを超える金額は指定できません。
PAYMENTREQUEST_0_AMT=amount
PAYMENTREQUEST_0_CURRENCYCODE=currencyID
4. 復帰URLを指定します。
復帰URLとは、お客様の買い手がペイパルにログインし支払いの承認を行った後、ペイパルが買い手
をリダイレクトするページです。通常、復帰 URL はお客様のサイト内の保護されたページ
（https://...）です。
注：復帰URLを使用して、お客様のサイトのページ間でパラメータをピギーバックできます。たとえ
ば、https://www.yourcompany.com/page.html?param=value... 構文を使用して、復帰
URLを設定し、追加パラメータを指定できます。指定したパラメータは、復帰URLで指定された
ページのリクエストパラメータとして利用できるようになります。
RETURNURL=return_url
5. キャンセル時のURLを指定します。
キャンセル時のURLとは、お客様の買い手が支払いの承認を行わなかった場合にペイパルが買い手を
リダイレクトするページです。通常、キャンセル時のURLはお客様のサイト内の保護されたページ
（https://...）で、買い手がペイパルにリダイレクトされる前のページです。
注：ペイパルが買い手をお客様のURLにリダイレクトした後、必要に応じてSetExpressCheckout
リクエストの値をお客様のURLのパラメータとして承認し、値を有効にすることができます。
CANCELURL=cancel_url
エクスプレスチェックアウトインテグレーションガイド
2012年12月
17
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
6. 支払いアクションの指定
初期設定の支払いアクションはSaleですが、支払いアクションを以下の値で明示的に指定しておく
ことを推奨します。
PAYMENTREQUEST_0_PAYMENTACTION=Sale
タスク終了後：
SetExpressCheckout APIの呼び出しに成功したら、買い手をペイパルサイトへとリダイレクトし、
SetExpressCheckoutレスポンスで返されたトークンを利用して_express-checkoutコマンドを実行
します。
注：以下の例ではペイパルSandboxサーバーを使用しています。
https://www.sandbox.paypal.com/webscr
?cmd=_express-checkout&token=tokenValue
エクスプレスチェックアウト取引詳細の取得
エクスプレスチェックアウト取引の詳細を取得するため、GetExpressCheckoutDetails APIオペレー
ションを行います。
この例では、お客様の買い手がペイパル上で取引を確認後、有効なトークンが付加された買い手のブラ
ウザをペイパルがリダイレクトすることを前提としています。
GetExpressCheckoutDetails APIオペレーションは必須ではありませんが、エクスプレスチェックア
ウトをインプリメントしたほとんどのお客様が本APIオペレーションで買い手の情報を入手しています。
お客様が SetExpressCheckout API の呼び出しに設定した復帰 URL で指定したページから
GetExpressCheckoutDetails APIオペレーションを開始します。通常、リダイレクトの発生後すぐに
このオペレーションを開始し、レスポンスの情報を使用してお客様の確認ページを表示します。
買い手の配送先住所および支払い者IDを入手する手順を以下にご説明します。
1. GetExpressCheckoutDetails APIオペレーションの実行と使用するバージョンを指定します。
METHOD=GetExpressCheckoutDetails
VERSION=XX.0
2. お客様のAPI信用証明書を指定します。
署名用に以下のパラメータを使用します。
18
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
USER=API_username
PWD=API_password
SIGNATURE=API_signature
3. ペイパルが買い手をお客様のサイトにリダイレクトする際に返すトークンを指定します。
SetExpressCheckout APIの呼び出し内で指定したURLへリダイレクトする場合のtokenHTTPリク
エストパラメータで使用するトークンをペイパルが返します。
TOKEN=tokenValue
4. GetExpressCheckoutDetails APIを実行し、買い手の情報を入手します。
5. GetExpressCheckoutDetails API レスポンス内のフィールドにアクセスします。
注：入力されたフィールドのみレスポンスで返されます。
エクスプレスチェックアウト取引の完了
エクスプレスチェックアウト取引を完了するにはDoExpressCheckoutPayment APIオペレーション
を呼び出します。
この例では、お客様がSetExpressCheckout APIを呼び出した後、ペイパルが有効なトークンを付与して、
買い手のブラウザをお客様のサイトにリダイレクトします。オプションでGetExpressCheckoutDetails
APIを呼び出してからDoExpressCheckoutPayment APIを呼び出すことも可能です。
最も簡単なケースでは、SetExpressCheckout APIを呼び出す際に注文の合計金額を設定します。
ただし、SetExpressCheckoutAPI を呼び出した時点で合計金額が不明だった場合には、
DoExpressCheckoutPaymentAPIの呼び出し前に金額を変更できます。
この例は最も簡単なケースで、SetExpressCheckoutAPIの呼び出し時に復帰URLで合計金額を指定し
ています。追加のオプションも指定できますが、この例では追加のオプションは使用していません。
エクスプレスチェックアウト取引を実施するためには以下の操作を行います。
1. DoExpressCheckoutPayment APIオペレーションの実行と使用するバージョンを指定します。
METHOD=DoExpressCheckoutPayment
VERSION=XX.0
2. お客様のAPI信用証明書を指定します。
以下の署名用のパラメータを使用します。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
19
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
USER=API_username
PWD=API_password
SIGNATURE=API_signature
3. ペイパルが買い手のブラウザをお客様のサイトにリダイレクトする際に返すトークンを指定します。
ペイパルは、お客様がSetExpressCheckout APIの呼び出しで指定したURLに買い手をリダイレク
トする際にtokenHTTPリクエストパラメータで使用するトークンを返します。
TOKEN=tokenValue
4. ペイパルが買い手のブラウザをお客様のサイトにリダイレクトする際に返す支払い者IDを指定し
ます。
ペイパルは、お客様がSetExpressCheckout APIの呼び出しで指定したURLに買い手をリダイレク
トする際にtokenHTTPリクエストパラメータで使用する支払い者IDを返します。オプションで、
GetExpressCheckoutDetails APIの呼び出しによって支払い者IDを取得できます。
PAYERID=id
5. 配送料、手数料、税金など含め、注文の合計金額を指定します。通貨がUSドル以外の場合には通貨
も指定します。
ほとんどの場合、配送料と税金を調整し、その結果SetExpressCheckout呼び出しに指定した額と
同額になります。
PAYMENTREQUEST_0_AMT=amount
PAYMENTREQUEST_0_CURRENCYCODE=currencyID
6. お客様がSetExpressCheckoutに指定した支払い処理と同一の処理を指定します。
PAYMENTREQUEST_0_PAYMENTACTION=Sale
エクスプレスチェックアウトインテグレーションのテスト
Sandboxでエクスプレスチェックアウトインテグレーションのテストを行うことができます。
ここでは、HTTPフォームを使用してAPIオペレーション用の値を入力し、お客様のサイトをシミュレーショ
ンする方法をご紹介します。この方法は初期のテストには利用できますが、より完全なテストを行うた
めには、HTTPフォームを実際のコードを使用したお客様のウェブページに置き換える必要があります。
SandboxをAPIサーバーとして使用したエクスプレスチェックアウト実行フローを以下の図に示しま
す。左側のページはお客様のサイトを表しています。
20
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
以下の手順番号は図中の番号を表しています。各手順を実行し、エクスプレスチェックアウトのテスト
を行ってください。
1. Sandbox上のSetExpressCheckout APIを呼び出すお客様のサイト上のフォームを起動してください。
APIを起動するには、お客様が設定したいフィールドのNVP名と同一名のフォームフィールドを設定し、
対応する値を指定し、以下の例に示すようにhttps://api-3t.sandbox.paypal.com/nvpなどのペイパ
ルSandboxサーバーにフォームをアップロードします。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
21
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
<form method=post action=https://api-3t.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=API_username>
<input type=hidden name=PWD value=API_password>
<input type=hidden name=SIGNATURE value=API_signature>
<input type=hidden name=VERSION value=XX.0>
<input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION
value=Sale>
<input name=PAYMENTREQUEST_0_AMT value=19.95>
<input type=hidden name=RETURNURL
value=https://www.YourReturnURL.com>
<input type=hidden name=CANCELURL
value=https://www.YourCancelURL.com>
<input type=submit name=METHOD value=SetExpressCheckout>
</form>
注：署名が存在する Sandboxビジネステスト用アカウントの APIユーザー名を使用します。
Sandboxのテスト証明タブで署名を確認できます。署名を使用しない場合は、別のSandbox
サーバーをご利用ください。
2. SetExpressCheckout APIオペレーションからレスポンス文字列を確認します。
ペイパルは以下のようなメッセージを返します。Successが設定されたACKを含むステータスと次の
手順で使用するトークンを確認してください。
TIMESTAMP=2007%2d04%2d05T23%3a23%3a07Z
&CORRELATIONID=63cdac0b67b50
&ACK=Success
&VERSION=XX%2e000000
&BUILD=1%2e0006
&TOKEN=EC%2d1NK66318YB717835M
3. 動作が成功した場合は指定のトークンを利用し、以下のようにお客様のブラウザをSandboxにリダ
イレクトしログインを行います。
https://www.sandbox.paypal.com/cgi-bin/webscr?
cmd=_express-checkout
&token=EC-1NK66318YB717835M
16進コードをASCIIコードに変換して、URLのエンコーディングと反対の操作であるURLのデコー
ディングが必要な場合があります。たとえば、トークンの%2d をハイフン（-）に置き換える必要
がある場合があります。
Sandboxテスト用アカウントにログインする前に、https://developer.paypal.comにログインし
てください。その後、お客様をマーチャントとみなす売り手用ビジネステストアカウントではなく、
買い手用テストアカウントにログインしてください。
4. 買い手用テストアカウントにログイン後、詳細を確認します。
確認が終了すると、以下に示すようにSandboxがお客様のブラウザをSetExpressCheckout API起
動時に指定した復帰URLへリダイレクトします。
22
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
http://www.YourReturnURL.com/
?token=EC-1NK66318YB717835M&PayerID=7AKUSARZ7SAT8
5. SandboxでGetExpressCheckoutDetails APIオペレーションを呼び出すお客様のサイト上の
フォームを起動します。
<form method=post action=https://api-3t.sandbox.paypal.com/nvp
<input type=hidden name=USER value=API_username>
<input type=hidden name=PWD value=API_password>
<input type=hidden name=SIGNATURE value=API_signature>
<input type=hidden name=VERSION value=XX.0>
<input name=TOKEN value=EC-1NK66318YB717835M>
<input type=submit name=METHOD value=GetExpressCheckoutDetails>
</form>
オペレーションが成功すると、GetExpressCheckoutDetails APIが以下に示すような支払い者の情
報を返します。
TIMESTAMP=2007%2d04%2d05T23%3a44%3a11Z
&CORRELATIONID=6b174e9bac3b3
&ACK=Success
&VERSION=XX%2e000000
&BUILD=1%2e0006
&TOKEN=EC%2d1NK66318YB717835M
&EMAIL=YourSandboxBuyerAccountEmail
&PAYERID=7AKUSARZ7SAT8
&PAYERSTATUS=verified
&FIRSTNAME=...
&LASTNAME=...
&COUNTRYCODE=US
&BUSINESS=...
&PAYMENTREQUEST_0_SHIPTONAME=...
&PAYMENTREQUEST_0_SHIPTOSTREET=...
&PAYMENTREQUEST_0_SHIPTOCITY=...
&PAYMENTREQUEST_0_SHIPTOSTATE=CA
&PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US
&PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME=United%20States
&PAYMENTREQUEST_0_SHIPTOZIP=94666
&PAYMENTREQUEST_0_ADDRESSID=...
&PAYMENTREQUEST_0_ADDRESSSTATUS=Confirmed
6. Sandbox上でDoExpressCheckoutPayment APIオペレーションを起動するお客様のサイト上の
フォームを起動します。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
23
エクスプレスチェックアウトの導入
もっとも簡単なエクスプレス
チェックアウトインテグレーションのインプリメンテー
ション
<form method=post action=https://api-3t.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=API_username>
<input type=hidden name=PWD value=API_password>
<input type=hidden name=SIGNATURE value=API_signature>
<input type=hidden name=VERSION value=XX.0>
<input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION
value=Authorization>
<input type=hidden name=PAYERID value=7AKUSARZ7SAT8>
<input type=hidden name=TOKEN value= EC%2d1NK66318YB717835M>
<input type=hidden name=PAYMENTREQUEST_0_AMT value= 19.95>
<input type=submit name=METHOD value=DoExpressCheckoutPayment>
</form>
7. DoExpressCheckoutPaymentAPIオペレーションでレスポンス文字列を確認します。
オペレーションが成功した場合は、
以下に示すようにレスポンスにはSuccessが設定されたACKが含
まれます。
TIMESTAMP=2007%2d04%2d05T23%3a30%3a16Z
&CORRELATIONID=333fb808bb23
ACK=Success
&VERSION=XX%2e000000
&BUILD=1%2e0006
&TOKEN=EC%2d1NK66318YB717835M
&PAYMENTREQUEST_0_TRANSACTIONID=043144440L487742J
&PAYMENTREQUEST_0_TRANSACTIONTYPE=expresscheckout
&PAYMENTREQUEST_0_PAYMENTTYPE=instant
&PAYMENTREQUEST_0_ORDERTIME=2007%2d04%2d05T23%3a30%3a14Z
&PAYMENTREQUEST_0_AMT=19%2e95
&PAYMENTREQUEST_0_CURRENCYCODE=USD
&PAYMENTREQUEST_0_TAXAMT=0%2e00
&PAYMENTREQUEST_0_PAYMENTSTATUS=Pending
&PAYMENTREQUEST_0_PENDINGREASON=authorization
&PAYMENTREQUEST_0_REASONCODE=None
セキュリティ
機密データの保護には常に注意を払う必要があります。機密データにはお客様のAPI信用証明書だけでは
なく、クッキーに保存された取引に関するデータなど顧客のブラウザに保存されたデータも含まれます。
24

ペイパルがエクスプレスチェックアウトのデモに使用する最も簡単な例などでAPI信用証明書が公
開される場合があります。そのため、例やSDKからコードをコピーした場合は、セキュリティの観
点から公開前に必ずサイトの確認と修正を行ってください。

ペイパル取引に関連する保存情報を暗号化します。たとえば、注文ステータス情報をクッキーに保存
した場合、情報が暗号化されていることを確認する必要があります。
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
エクスプレス

チェックアウトインテグレーションのトラブルシューティング
お客様のサイトとペイパル間で情報をやりとりする場合は、HTTPSのような安全な通信プロトコル
を使用してください。HTTPや保護されていないcURLは使用しないでください。
エクスプレスチェックアウトインテグレーションのトラブルシューティ
ング
インテグレーションがうまくいかない場合には、まず最初に確認していただきたい項目があります。こ
れらの項目を確認しても問題が解決しない場合には、マーチャントテクニカルサポート（MTS）にご連
絡ください。
MTSにご連絡の際には、エラーの原因となった動作ログなどの基本情報が必要となります。MTSへのご
連絡はhttps://www.paypal.com/mtsまでお願いします。
エラー処理
レスポンスメッセージにはACK値が含まれます。ACK = Success以外の場合、エラーや警告メッセージ
の確認を行ってください。
ペイパルサーバーからのレスポンスを確認し、エラーの発生を示しているものを探します。警告や失敗
の値は複数存在するため、確実な方法はACKの値がSuccessかどうか調べることです。ACKがSuccess
以外のレスポンスのエラー番号とメッセージを調べます。
失敗のレスポンスは1つ以上のエラー番号とメッセージを含む場合があります。エラーフィールドは
L_ERRORCODEnから始まり、0から始まるnはレスポンス内のエラーコード番号を表しています。各エ
ラー番号には、L_SHORTMESSAGEnとL_LONGMESSAGEn（nはL_ERRORCODEnのnと同一）の2
つのメッセージが含まれます。
重要：エラー番号が一意である保証はないため、エラー番号とメッセージの両方をもとにエラーに対す
る適切な対処を決定します。
APIコール別に分類されているエラーコードの一覧は、次に記載されているマーチャントAPIエ
ラーコードを参照してください：
https://www.x.com/developers/paypal/documentation-tools/api/errorcodes
ペイパル側の問題に関するエラーなど、一時的に発生するエラーもあるため、操作をやり直してみてく
ださい。ペイパルサーバーはほぼ24時間稼働しているので、もし問題が1時間以上続く場合は、エクス
プレスチェックアウトのインプリメンテーションに問題があると考えられます。
買い手のアカウントに関するエラーもあります。たとえば、資金源が有効でない場合や、買い手のアカ
ウントが何らかの理由で制限されている場合です。エラーメッセージには、買い手に解決方法を指示す
るメッセージをサイト上に作成するための情報が含まれています。別の資金源を選択するように買い手
に指示する場合もあります。買い手のアカウントに関する問題はリスクを伴うため、解決するまで商品
の発送を差し控えたいとお考えになることでしょう。エラーコード10486が返された際に買い手をペイ
パルサイトにリダイレクトする手順については、こちらのHow-to Guide（英語版のみ）に情報が記載
されています。
お客様のサイトへの入力値が無効だった場合や、その値をリクエストメッセージでペイパルに送信した
場合など、インテグレーションの問題に関するエラーもあります。サイト公開後の問題発生を防ぐため、
Sandboxを使用して十分なテストを行ってください。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
25
エクスプレスチェックアウトの導入
エクスプレス
チェックアウトの特徴
タイムアウト
APIオペレーションの終了ステータスが不明の場合や、ペイパルがオペレーションを完了する前にレスポ
ンスを受信するページから買い手が移動した場合にタイムアウトが発生します。ペイパルが支払いを受
領したことを示す有効な取引IDを受領するまで商品を発送しないでください。
ステータスが不明な場合はAPIオペレーションを再度実行したほうが安全です。DoExpressCheckout
の場合、GetExpressCheckoutDetailsを実行し、CheckoutStatusフィールドを確認できます。値が
PaymentCompleted以外の場合は、支払いは完了していません。DoExpressCheckoutPayment また
は GetExpressCheckoutDetailsの呼び出しから有効な取引IDを受領するまで商品を発送しないでく
ださい。
APIオペレーションのロギング
実行したペイパルAPIオペレーションのリクエスト・レスポンスメッセージ中の基本情報を記録します。
ペイパルに対するAPIオペレーションを識別するCorrelation IDをレスポンスメッセージから記録し、特
定の取引に関するサポートが必要な場合にこのIDをマーチャントテクニカルサポートに提示します。
ペイパルAPIオペレーションに対するすべてのレスポンスにはデバッグ処理に役立つ情報が含まれてい
ます。レスポンスメッセージ中のCorrelation IDだけではなく、取引IDやタイムスタンプなどの情報も
記録しておくと、ペイパルウェブサイトやAPIで取引を確認することができます。
「冗長（verbose）」モー
ドでリクエストとレスポンスをそのまま記録するスキームをすることもインプリメントすることも可能
です。ただしリクエスト中のパスワードは決して記録しないでください。
値のエンコーディングとデコーディング
APIオペレーションで送信する値はすべてエンコーディングとデコーディングが必要です。値のみをエン
コードし、NVP中の名前とSOAP中のタグはエンコードしません。
ペイパルへのリクエストに含まれるリクエストフィールドの値はすべてエンコードし、レスポンスに含
まれるフィールドの値はすべてデコードします。エンコーディングやデコーディングはひとつひとつの
値に対して行ってください。メッセージ全体のエンコーディングやデコーディングは行わないでくださ
い。ブラウザへリダイレクトされたメッセージや、ブラウザからリダイレクトしたメッセージをブラウ
ザ自身がエンコードやデコードをする場合があります。この場合、フィールドの値に対してのみエンコー
ディングとデコーディングが適切に行われたことを確認します。
エクスプレスチェックアウトの特徴
エクスプレスチェックアウトの特徴には、エクスプレスチェックアウトのAPIリクエストの構成、ペイ
パルチェックアウトページのカスタマイズ、お客様による追加設定などがあります。
26
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
エクスプレス
チェックアウトの特徴
エクスプレスチェックアウトユーザーインターフェイスのカスタマイズ
ペイパルエクスプレスチェックアウトページのレイアウトはカスタマイズ可能です。カスタマイズに
よって決済フローが変わる場合もあります。
エクスプレスチェックアウトには、買い手が決済中にペイパルにログインしたときに決済ページを表示
するオプションがあります。オプションの中には、ペイパルページをお客様のページのように見せ、買
い手に統一された表示を提供するものもあります。

ロゴの表示

背景および境界色

ペイパルコンテンツの表示言語

顧客のサービス番号
注：上記のカスタマイズ項目はすべてお客様の個人設定に設定できます。お客様の個人設定の初期設定を
上書きする場合のみ、エクスプレスチェックアウトAPIオペレーションに項目を設定してください。
さらに、買い手がペイパルで支払いを完了できるようにフローを簡略化したり、決済中に表示する情報
を変更したりするオプションがあります。ペイパル確認ページで以下の操作を行うことができます。

項目ごとに詳細を追加する。

税金、保険、配送料、配送割引などを追加する。

ページに表示された合計が正確な金額か、税金や配送料を含まない見積もり額かを表示する。

買い手にメモを表示する。配送オプションなどを提示できる。

買い手がお客様に対し指示を出せるようにする。

支払いに対して請求書番号を指定する。
特別な場合には以下の機能がご利用可能です。

配送先住所の表示と使用

eBay発行のインセンティブ

ギフト包装の選択

広告送付に対する買い手の承諾

アンケート
決済と支払いの回収
エクスプレスチェックアウトを使用すると、支払いを即時に回収したり、商品発送後などに支払いを後
から回収したりすることができます。エクスプレスチェックアウトでは、支払いの後回収用の取引設定
を複数ご用意しています。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
27
エクスプレスチェックアウトの導入
エクスプレス
チェックアウトの特徴
多くの場合は支払いの受領と商品の発送を即時に行います（販売）。即時支払いに加え、エクスプレス
チェックアウトでは、後回収する支払いの与信を行うこともできます（与信）
。与信は、たとえば、商品
の発送まで買い手の資金を保留しておきたい場合などに有効です。実際の支払いの回収は、商品の発送
時に行います。たとえば与信後3日以内に商品を発送できない場合など、必要な場合には一度だけ再与信
を行うことができます。
エクスプレスチェックアウトには、ひとつの与信では足りない場合に利用する、注文と呼ばれる追加オ
プションがあります。与信を複数作成し、同一注文の一部として回収することができます。注文の発送
が複数回に分かれてしまい、発送ごとに支払いを回収する必要がある場合などに便利です。
払戻し
支払いの全額あるいは一部の払戻しができます。最初に回収した支払いや、これから行われる決済の一
部として回収した支払いに対し払戻しを行います。
払い戻し期間（通常60日間）が経過した後に取引が発生した場合、払戻しはできません。
関連情報：
41ページ「払戻しの実行」
定期支払い
エクスプレスチェックアウトの定期支払い機能を利用して、定期的に購読やほかの支払いの管理を行う
ことができます。参照取引の使用許可をペイパルから得れば、任意のスケジュールでの変動支払いを提
供できます。
買い手に定期支払いを提供する場合は、定期支払い個人設定を作成します。個人設定には、オプション
のトライアル期間と通常の支払い期間の詳細を含む定期支払い情報が含まれます。どちらの期間にも支
払い回数と支払い額（適用される場合は配送料と税金を含む）が含まれます。
定期支払い個人設定を作成後、請求開始日、請求回数、請求額をもとに、ペイパルが自動的に支払いを
キューに保存します。設定の期限が切れるか、支払い不履行が何度も続くか、お客様が設定をキャンセ
ルするまで支払いが繰り返し行われます。
定期支払いの許可は、ペイパル上で買い手がマーチャントと請求処理規約を交わすことによって確立さ
れます。エクスプレスチェックアウトでは、請求処理規約はあらかじめ設定するか、買い手の1回目の
購入時に設定します。どちらの場合も、エクスプレスチェックアウトAPIオペレーションを呼び出した
際に行われます。
参照取引を利用した定期支払い
参照取引を利用した定期支払いは、任意のスケジュールで任意の金額の支払いを処理する場合に使用し
ます。参照取引は、次の取引を派生する決済取引です。たとえば、買い手がお客様のサイトで商品を購
入し、参照取引IDと呼ばれるペイパルの取引IDを使って、あとでほかの取引を開始することができます。
28
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
エクスプレス
チェックアウトの特徴
モバイルエクスプレスチェックアウト
ペイパルは様々な形態のモバイルエクスプレスチェックアウトをサポートしています。お客様は完全
なモバイルサイトを提供したり、決済ボタンをアプリケーション自身やモバイルサイトに組み込んだ、
携帯電話用のアプリケーションを作成したりできます。
モバイルエクスプレスチェックアウトでは、速い決済や、モバイル装置の小さな画面やキーボードに
合わせた支払いページを提供しています。買い手がお客様のサイトで支払いを行うかペイパルで支払い
を行うか、お客様が設定できます。
エクスプレスチェックアウトを利用した平行支払い
平行支払いを利用して、買い手はエクスプレスチェックアウトフロー内の複数のマーチャントに支払
いを行うことができます。本機能はモバイルエクスプレスチェックアウトでは提供されていません。
平行支払いでは、マーチャントがマーケットプレイスホストを務めます。オンライン旅行会社を例に考
えてみます。買い手は複数のマーチャントから航空券を購入し、現地のホテル、レンタカー、娯楽施設
の予約を行います。エクスプレスチェックアウトで平行支払いを設定すると、マーケットプレイスホス
トがペイパルを支払い方法として受け付けます。ホストは買い手に対し、費用、旅程、その他の情報を
まとめた一括注文をペイパルの確認ページで受け付けます。買い手はサプライヤからキャンセル料など
の旅行情報を「取引の詳細」ページやメールで確認します。
不正防止管理フィルタ
不正防止管理フィルタ（FMF）は、不正と疑われる取引を識別するフィルタを提供します。フィルタに
は2つのカテゴリがあります。

基本フィルタは取引開始国や取引の値などのデータを審査します。ペイパルではビジネスアカウント
とウェブペイメントプロアカウントに基本フィルタを提供します。

高度フィルタはクレジットカード、住所、高リスク指標、追加の取引特性などのデータを審査します。
アップグレードしたウェブペイメントプロマーチャントが高度フィルタを使用できます。
注：高度フィルタの使用には追加料金がかかる場合があります。
不正防止管理フィルタの詳細は、不正防止管理フィルタをご覧ください。
イベント通知
ほとんどの場合において、必要な取引情報の決定にペイパルAPIオペレーションを使用できます。しかし、
IPNの設定が必要な場合もあります。たとえば異議の発生や異議の解決などのアクションに関する自動通
知が必要な場合などです。
IPNは以下に示すイベントをペイパルがお客様に通知するメッセージサービスです。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
29
エクスプレスチェックアウトの導入
エクスプレス
チェックアウト導入手順

エクスプレスチェックアウトや適応支払い、ダイレクトクレジットカード決済などの即時支払いや、
与信（支払いが未回収の販売）など

eCheckペイメントとそれに伴うステータス（未決済、決済完了、決済拒否など）および不正取引の
可能性やその他の理由で未決済の支払い

定期支払い・購読アクション

取引に伴うチャージバック、異議、支払い取り消し、払戻し
IPNの詳細は、即時支払い通知ガイドをご覧ください。
動的画像の概要
動的画像を利用して、ペイパルはエクスプレスチェックアウトボタンをキャンペーンやイベント用に
変更します。モバイルエクスプレスチェックアウトではこの機能はサポートしていません。
お客様がペイパルキャンペーンやイベントに参加される場合、ペイパルは自動的に画像を更新して、キャ
ンペーン情報を反映させます。キャンペーンが終了すると、デフォルト画像に戻します。お客様はキャ
ンペーンの前後およびキャンペーン中に、スケジュール管理やご自身のウェブサイトのアプリケーショ
ンコードの変更を行う必要はありません。動的画像を設定すれば、スケジュール管理やコード変更は自
動的に処理されます。
エクスプレスチェックアウト即時更新
即時更新機能により、配送情報を含む返信メッセージを作成し、ロケーションベースの発送、保険、税
金情報を提供できます。即時更新機能はモバイルエクスプレスチェックアウトではサポートしていま
せん。
ペイパルに保存してある買い手の住所に基づいた情報を提供するURLを指定します。買い手の実際の住
所を見ることはできません。
エクスプレスチェックアウト導入手順
エクスプレスチェックアウトボタン、ペイパルAPIオペレーション、ペイパルコマンド、トークンを含
むエクスプレスチェックアウトフローをインプリメントします。
以下の概念図にエクスプレスチェックアウトをお客様のウェブサイトに導入する手順を示します。
30
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
エクスプレス
チェックアウト導入手順
トークンはペイパルが割り当てる値で、APIオペレーションやコマンドの実行をユーザー体験フローの特
定のインスタンスに関連付けます。
注：トークンは図には表示されていません。
エクスプレスチェックアウトボタン
ペイパルはお客様のウェブサイト用のボタンや画像をご用意しています。
以下のボタンをお客様のサイトのショッピングカートページにインプリメントし、エクスプレスチェッ
クアウトのショッピングカートをお試しください。
エクスプレスチェックアウト体験版の一部なのですが、ペイパルを支払いオプションとしてインプリメ
ントするには、支払いオプションに[PayPal]マーク画像を追加してください。支払いオプションの選
択にはラジオボタンのご使用をお勧めします。
エクスプレスチェックアウトAPIオペレーション
ペイパルAPIはエクスプレスチェックアウト用に3種類のAPIオペレーションをご用意しています。これ
エクスプレスチェックアウトインテグレーションガイド
2012年12月
31
エクスプレスチェックアウトの導入
エクスプレス
チェックアウト導入手順
らのAPIオペレーションで、取引設定、買い手情報の入手、支払い処理を行い、取引を完了します。
APIオペレーション
内容
SetExpressCheckout
エクスプレスチェックアウト取引を設定します。お客様が指定したペイパル
サイトのルックアンドフィールをカスタマイズするための情報を表示します。
必要な情報を以下に示します。
 買い手がペイパルにログインし支払いを承認した後、ペイパルが買い手を
リダイレクトするお客様のサイトのURL
 買い手が買い物をキャンセルした場合にペイパルが買い手をリダイレク
トするお客様のサイトのURL
 注文の合計金額または合計見積もり額。できるだけ正確な額をご入力くだ
さい。
GetExpressCheckout
配送情報を含む買い手の情報をペイパルから入手します。
DoExpressCheckoutPayment
注文の正確な合計金額を含むエクスプレスチェックアウト取引を完了し
ます。
エクスプレスチェックアウトコマンド
ペイパルではお客様の買い手をブラウザからペイパルへとリダイレクトするコマンドをご用意していま
す。このコマンドによって、お客様の買い手はペイパルにログインし、エクスプレスチェックアウトに
よる支払いを承認します。
お客様が買い手をブラウザからペイパルにリダイレクトするには、エクスプレスチェックアウトの
ExpressCheckoutコマンドを指定する必要があります。またSetExpressCheckout APIオペレーショ
ンに返された、取引の識別トークンを指定します。
注：ペイパルがお客様のサイトへの再度リダイレクトを行うには、SetExpressCheckout APIオペレー
ションを起動し、再リダイレクト先のURLを指定しておく必要があります。買い手がペイパルで支
払いを行う場合、ペイパルは成功時のURLへリダイレクトします。それ以外の場合にはキャンセル
時のURLへリダイレクトします。
買い手が支払いを承認した場合、ペイパルは以下の情報とともに成功時のURLへリダイレクトを行い
ます。

ペイパルへのリダイレクトに含まれていたトークン

買い手の一意な識別子（支払い者ID）
買い手がキャンセルした場合、ペイパルへのリダイレクトに含まれていたトークンとともにキャンセル
時のURLへリダイレクトします。
32
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトの導入
エクスプレス
チェックアウト導入手順
エクスプレスチェックアウトトークンの使用
エクスプレスチェックアウトはトークンを使用してペイパルへのアクセスを制御し、エクスプレス
チェックアウトAPIオペレーションを実行します。
SetExpressCheckout APIオペレーションは、ほかのエクスプレスチェックアウトAPIオペレーション
や_ExpressCheckoutコマンドが取引の識別に利用するトークンを返します。トークンの寿命は約3時
間です。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
33
エクスプレスチェックアウトの導入
エクスプレス
34
チェックアウト導入手順
2012年12月
エクスプレスチェックアウトインテグレーションガイド
2
Chapter 2
エクスプレスチェックアウト
ユーザーインターフェイス要件
お客様のエクスプレスチェックアウトインテグレーションは、ボタンの使用方法や位置に関するペイ
パルの要件に準拠しなければなりません。ペイパルがホストするボタンのみ利用可能であり、ボタンは
決済ページと支払いページの両方に追加する必要があります。
エクスプレスチェックアウトフロー
エクスプレスチェックアウトをご利用になるには、決済オプションと支払い方法の両方にインプリメン
トする必要があります。通常は、お客様のショッピングカートページと支払いオプションページからエ
クスプレスチェックアウトフローを開始します。
エクスプレスチェックアウトをお客様のフローに追加するには、「ショッピングカート」ページに
「支払い方法」ページに[PayPal]マークを追加します。以下の
[Checkout with PayPal]ボタンを、
図にフロー全体を表示します。
以下の変更を行い、エクスプレスチェックアウトフローをすべてインプリメントしてください。

お客様の「ショッピングカート」ページに、[Check out with PayPal]ボタンを追加します。エ
クスプレスチェックアウト設定リクエストを送信し、クリックを制御します。レスポンスを受領後、
お客様の買い手のブラウザをペイパルへリダイレクトします。

「支払い方法」ページのオプションに[PayPal]マークを追加します。エクスプレスチェックアウ
ト設定リクエストを送信し、クリックを制御します。レスポンスを受領後、買い手のブラウザをペイ
パルへリダイレクトします。

ペイパルから戻った後、配送情報をペイパルから取得し、支払いを受領し、エクスプレスチェック
アウト取引を完了します。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
35
エクスプレスチェックアウトユーザーインターフェイス要件
エクスプレス
チェックアウトフロー
注：買い手による支払いをペイパル確認ページで行うこともできます。この場合、お客様の決済フロー
で、マーチャント確認ページを省略し、直接確認ページに進むことができます。
関連情報：
13ページ「もっとも簡単なエクスプレスチェックアウトインテグレーションのインプリメンテーション」
決済指定ポイント
決済指定ポイントは、エクスプレスチェックアウトをインプリメントするポイントのひとつです。買い
手はお客様のショッピングカートページで[Check out with PayPal]ボタンをクリックし、エクスプ
レスチェックアウトフローを開始します。
エクスプレスチェックアウトを通常の決済フローに組み込む手順を以下の図に示します。
支払いオプション指定ポイント
支払いオプション指定ポイントは、エクスプレスチェックアウトをインプリメントするポイントのひと
つです。買い手はお客様の支払い方法ページでデフォルトオプションにペイパルを選択し、エクスプレ
スチェックアウトフローを開始します。
エクスプレスチェックアウトをお客様の支払い方法ページに組み込む手順を以下の図に示します。
36
2012年12月
エクスプレスチェックアウトインテグレーションガイド
エクスプレスチェックアウトユーザーインターフェイス要件
ペイパルボタンとロゴ画像
ペイパルボタンとロゴ画像
ペイパルがお客様のサイトで利用できることを買い手に知らせるために、ペイパルボタンとロゴ画像を
決済フローに追加します。ボタンやロゴには動的画像のご利用をお勧めします。
安全なペイパルサーバーがホストする[Check out with PayPal]ボタンと[PayPal]マーク画像をご
使用ください。画像が更新された場合には、お客様のアプリケーション上の画像も自動的に更新されま
す。お客様のサーバー上でペイパル画像のコピーをホストしないでください。古いペイパルボタンや画
像の使用によって買い手の信用を失いかねません。
エクスプレスチェックアウト画像タイプ
[Check out with PayPal]ボタンと[PayPal]マーク画像は2種類ご用意しています。

動的画像

静的画像
動的画像を使用した場合、ペイパルのデザインを動的に変更できます。たとえばお客様がペイパルのキャ
ンペーンに参加した場合、キャンペーン期間中はお客様が画像URLに追加したパラメータ情報をもとに
画像を動的に変更します。
一方、静的画像は動的に変更できません。ペイパルキャンペーンに参加するには、手動で画像コードを
修正し表示画像を変更し、キャンペーン終了後、元の画像に戻す必要があります。画像管理をペイパル
にまかせるには、インプリメントした静的画像を動的画像に変更するしかありません。
エクスプレスチェックアウト画像
[Check out with PayPal]ボタンは、お客様のショッピングカートページに追加する画像です。米国
版の画像を以下に示します。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
37
エクスプレスチェックアウトユーザーインターフェイス要件
ペイパルボタンとロゴ画像
エクスプレスチェックアウトボタンの作成方法は、https://www.paypal.com/us/cgi- bin/webscr?
cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outsidをご覧ください。米国以外の
国用のボタンもご用意しています。該当するページをご覧になるには、リンクの国略記号をusからご覧
になりたい国の記号に変更してください。たとえば、英国向けのボタンをご覧になる場合は、以下のように
usをukに変更してください。https://www.paypal.com/uk/cgi- bin/webscr?cmd=xpt/Merchant/
merchant/ExpressCheckoutButtonCode-outsidペイパルでは各国向けの画像をご用意しています。
国別ボタンと画像
国名
URL 上の
変更
国名
URL 上の
変更
国名
URL 上の
変更
国名
URL 上の
変更
ｵｰｽﾄﾗﾘｱ
au
オーストリア
at
ベルギー
be
カナダ
ca
中国
cn
フランス
fr
ドイツ
de
イタリア
it
日本
j1
オランダ
nl
ポーランド
pl
スペイン
es
スイス
ch
英国
uk
米国
us
注： URL中の文字は大文字・小文字の区別があります。URL中の略語は国コードとは異なる場合がり
ます。
支払いマーク
[PayPal]マークはお客様の支払い方法ページに追加する画像です。以下のような画像になります。
支払いオプションへのペイパルの追加は、エクスプレスチェックアウト体験の一部ですが、それには
[PayPal]マーク画像をお客様の支払いオプションに追加する必要があります。支払いオプションには
ラジオボタンのご使用をお勧めします。
[PayPal]マークの作成に関しては、https://www.paypal.com/cgi- bin/webscr?cmd=xpt/
Marketing/general/OnlineLogoCenter-outsideをご覧ください。
38
2012年12月
エクスプレスチェックアウトインテグレーションガイド
3
Chapter 3
関連APIオペレーション
もっとも簡単なエクスプレスチェックアウトインテグレーションを作成する場合、Saleを支払いアク
ションに指定し、お客様が支払いを即座に受領できるようにします。あとから回収する支払いの設定や、
支払いの払戻しもできます。
エクスプレスチェックアウト用の販売支払いアクション
販売支払いアクションは、指定された金額の購入を完了する1件の支払いを表します。
エクスプレスチェックアウト支払いアクションのデフォルト設定は販売ですが、SetExpressCheckout
やDoExpressCheckoutPaymentリクエストで以下のアクションを指定することができます。
PAYMENTREQUEST_n_PAYMENTACTION=Sale
販売は最も簡単な支払いアクションです。商品の発送を含め取引を即時に完了できる場合は、この支払
いアクションをご選択ください。販売支払いアクションを使用するための条件を以下に示します。

DoExpressCheckoutPayment APIオペレーションを開始した時点で支払いの最終金額がわかって
いること

デジタル商品や即時に発送できる在庫のある商品など、注文を即時に処理できること
DoExpressCheckoutPayment APIオペレーションの実行後、支払いが完了しますので、ほかのアクショ
ンを行う必要はありません。この支払いアクションを使用した場合、追加の支払いを回収したり、支払
いの一部を無効にしたりはできません。
エクスプレスチェックアウト用の与信支払いアクション
与信支払いアクションは、買い手の資金を最長3日間保留する同意を表します。
与信を設定するには、SetExpressCheckoutリクエストおよびDoExpressCheckoutPaymentリクエ
ストに以下の支払いアクションを指定します。
PAYMENTREQUEST_n_PAYMENTACTION=Authorization
エクスプレスチェックアウトインテグレーションガイド
2012年12月
39
関連APIオペレーション
エクスプレス
チェックアウト用の注文支払いアクション
与信では、お客様がDoExpressCheckoutPaymentリクエストに指定した金額の115%まで、または指
定金額に$75USDを加えた額までの複数の支払いを回収することができます。支払いを回収する前に商
品の発送が必要な場合や、支払いを即座に受け取らない理由がある場合には、この支払いアクションを
ご選択ください。
資金を保留しておく信用期間は3日間です。与信の有効期間は29日間です。29日間の有効期間中に1回だ
け3日間の信用期間を再与信できます。
DoExpressCheckoutPaymentリクエストで指定した金額の未回収分が無効になり、回収できなくなっ
た場合、与信を無効にできます。支払いがまったく回収されていない場合は、その支払い自体が無効に
なり、回収は一切行われません。
エクスプレスチェックアウトの与信支払いアクションに伴うAPIオペレーション
APIオペレーション
内容
DoCapture
与信支払いを回収します。
DoReauthorization
支払いの再与信を行います。
DoVoid
注文または与信を無効にします。
エクスプレスチェックアウト用の注文支払いアクション
注文支払いアクションは、指定された金額までの1件または複数の与信金額を、最長29日にわたって支
払う同意を表します。
注文を設定するには、SetExpressCheckoutリクエストとDoExpressCheckoutPaymentリクエストで
以下の支払いアクションを指定します。
PAYMENTREQUEST_n_PAYMENTACTION=Order
注文アクションでは29日間にわたって複数の与信を作成できます。作成した与信ごとに、買い手の資金
を最長3日間保留します。お客様がDoExpressCheckoutPaymentリクエストに指定した金額の115%
まで、または指定金額に$75USDを加えた額までの複数の支払いを各与信に対し回収できます。
注：お客様のペイパルアカウント内の子与信のデフォルト数は1です。与信数を増やしたい場合はペイパ
ルにご連絡ください。
注文支払いアクションは柔軟性が最も高く、販売、または与信1回と再与信1回ではお客様のニーズを満
足できない場合にご利用ください。注文支払いアクションは次のような場合に適切です。
40

繰り越し注文。在庫の商品を即時配送し、残りの商品は入荷次第配送し、配送が2回以上に分かれる
可能性のある注文。

分割注文。商品を複数の住所に配送する場合など、配送が1回以上に分かれ、配送別に支払いを回収
する注文。
2012年12月
エクスプレスチェックアウトインテグレーションガイド
関連APIオペレーション
払戻しの実行

ドロップシッピング。ほかのベンダーが配送する商品の支払いをお客様が回収する方法。
再与信はできません。与信の保留期間または有効期間が経過した場合など、再与信が必要な場合は、新
規に与信を作成してください。
注文や注文から作成した与信を無効にできます。注文を無効にすると、DoExpressCheckoutPayment
リクエストで指定した金額の未回収部分が無効になり、回収ができなくなります。支払いがまったく回
収されていない場合は、その支払い自体が無効になり、回収は一切行われません。
注文に伴う与信を無効にした場合は、与信で指定した金額の未回収部分が無効になり、回収ができなく
なります。与信がまったく回収されていない場合は、その与信支払い自体が無効になります。
エクスプレスチェックアウトの注文支払いアクションに関連するAPIオペレーション
APIオペレーション
内容
DoAuthorization
支払いの与信を行います。
DoCapture
与信支払いを回収します。
DoVoid
注文または与信を無効にします。
払戻しの実行
RefundTransactionペイパルAPIオペレーションで払戻しを実行できます。
RefundTransaction APIを使用して、支払いの回収によって作成された取引などに関連する1件以上の
払い戻しを発行します。支払いの回収時にペイパルが割り当てた取引IDで取引を識別します。
注：払戻し期間の経過後に発生した取引に対しては、払戻しはできません。通常の払戻し期間は60
日間です。
最初の取引の合計額まで払戻しできます。全額払戻しを指定した場合、全額を払戻します。一部払戻し
を指定した場合、払戻し金額、通貨、そしてメモに払戻し内容を記入する必要があります。
RefundTransaction APIを呼び出すと、（最初の取引ではなく）払戻しに関連する別の取引IDと払戻し
に関する追加情報がペイパルから返されます。追加情報には以下の項目が含まれます。

支払い者に返金される払戻し総額

お客様に返金される、最初の取引手数料に関連する払戻し額

お客様の残高から差し引かれる払戻し額
エクスプレスチェックアウトインテグレーションガイド
2012年12月
41
関連APIオペレーション
払戻しの実行
払戻しを実行するには以下の手順に従ってください。
RefundTransactionリクエストで、払戻しを行う支払いの取引IDを指定します。
TRANSACTIONID=transaction_id
1. RefundTransactionリクエストで、払戻しを行う支払いの取引IDを指定します。
TRANSACTIONID=transaction_id
2. 全額（Full）または一部（Partial）いずれかの払戻し方法を指定します。
REFUNDTYPE=Full
または
REFUNDTYPE=Partial
3. 一部払戻しを指定した場合は、通貨と払戻し額を指定します。
AMT=amount
CURRENCYCODE=currencyID
4. 一部払戻しを指定した場合は、メモに内容を記述します。
NOTE=description
5. RefundTransactionオペレーションを実行します。
6. RefundTransactionレスポンスの確認応答ステータスをチェックし、オペレーションが成功したこ
とを確認します。
関連情報:
28ページ「払戻し」
42
2012年12月
エクスプレスチェックアウトインテグレーションガイド
4
Chapter 4
ペイパルSDKとエクスプレス
チェックアウトの統合
NVP文字列やSOAP構造のメッセージを作成する代わりにペイパルSDKを使用することができます。
SDKを使用すると、Java、PHP、Rubyなどお客様のお好きなプログラミング言語でコーディングでき
ます。
SDKではプログラミング言語を選択できるだけでなく、メッセージのエンコーディングやデコーディン
グ、証明書管理などの一般的な作業を簡単に行うことができます。SDKの詳細とお客様の環境に適切な
SDKをダウンロードするには以下のサイトをご覧ください。

ペイパルAPI: Name-Value Pair（NVP）のインターフェイス

ペイパルAPI: SOAPインターフェイス
エクスプレスチェックアウトインテグレーションガイド
2012年12月
43
ペイパルSDKとエクスプレスチェックアウトの統合
44
2012年12月
エクスプレスチェックアウトインテグレーションガイド
5
Chapter 5
エクスプレスチェックアウト
インテグレーションの実稼働
お客様のアプリケーションをペイパルSandboxと統合し、運用開始の準備ができたら、必要な手順がす
べて完了していることを確認してください。
1. お客様の本番用ペイパルアカウントを作成し構成します。
注：ほかのマーチャントの代理でエクスプレスチェックアウトやほかのペイパルAPIオペレーショ
ンを実行する場合、本番環境でAPIオペレーションを行う許可を得なければなりません。つまり、
本番環境でAPIオペレーションを行うためには、依頼元のマーチャントから許可を得る必要があ
ります。
2. お客様の本番用アカウントの個人設定が、sandboxアカウントの個人設定と一致していること、ま
たはお客様が個人設定の相違について理解し是認していることを確認します。
3. お客様の本番用ペイパルアカウントの信用証明書を設定します。
API信用証明書はアカウントに関連付いています。したがって、本番用の信用証明書はsandbox用の
信用証明書とは異なります。お客様の本番アカウント用に、別の署名を入手するか、別の証明書をダ
ウンロードしてください。
4. アプリケーションにペイパルSDKを使用する場合、お客様の本番用アカウントの詳細情報を含むAPI
Profileオブジェクトを作成します。
environmentフィールドにはliveを設定し、証明書を使用する場合は、お客様の本番用アカウントに
関連付けられたAPIユーザー名、APIパスワード、API証明書のパスを記入してください。
5. お客様のファイアウォールやネットワーク機器に必要な信用できるIPアドレスのリストにペイパル
のIPアドレスを追加してください。詳細はこちら
へ: https://cms.paypal.com/us/cgi-bin/?cmd=_rendercontent&content_ID=developer
/howto_api_golivechecklist
エクスプレスチェックアウトインテグレーションガイド
2012年12月
45
エクスプレスチェックアウトインテグレーションの実稼働
46
2012年12月
エクスプレスチェックアウトインテグレーションガイド
A
Chapter A
API信用証明書の取得
ペイパルAPIを使用するには、お客様がさまざまなAPIオペレーションの実行を承認されたペイパルビジ
ネスアカウント保持者またはペイパルプレミアアカウント保持者であることを示すAPI信用証明書が必
要です。信用証明書にはAPI署名または証明書を使用できますが、署名のご使用をお勧めします。
重要：署名と証明書の両方を保持できますが、両方同時に使用することはできません。
API署名の作成
API署名は、ペイパルが割り当てたAPIユーザー名とそれに関連付けられたAPIパスワードと署名から構
成されています。ペイパルAPIオペレーションを実行する際には、上記の情報が必ず必要になります。
署名の作成にはペイパルビジネスアカウントが必要です。
API署名の作成手順は以下のとおりです。
1. ペイパルにログインし、[マイアカウント]内の[個人設定]をクリックします。
2. [販売ツール]をクリックします。
3. [APIアクセス]をクリックします。
4. [API信用証明書リクエスト]をクリックします。
5. [API署名リクエスト]をチェックし、[同意して送信]をクリックします。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
47
API信用証明書の取得
API証明書の作成
6. [Done]をクリックし、手順を終了します。
API証明書の作成
お客様のウェブサイトが必要する場合のみAPI証明書を作成します。一般的には信用証明書にはAPI署名
を作成します。
API証明書の作成にはペイパルビジネスアカウントが必要です。
注： API信用証明書用の証明書は、お客様のウェブサイト用のSSL証明書とは異なります。これらの証明
書に関連性はありません。
証明書が必要な場合は、以下の指示に従ってください。
1. ペイパルにログインし、[マイアカウント]の[個人設定]をクリックします。
2. [販売ツール]をクリックします。
3. [APIアクセス]をクリックします。
4. [API信用証明書リクエスト]をクリックします。
5. [API証明書リクエスト]をチェックし、[同意して送信]をクリックします。
48
2012年12月
エクスプレスチェックアウトインテグレーションガイド
API信用証明書の取得
API証明書の作成
6. あとで使用するためAPI UsernameとAPI Passwordの値を保存します。
7. [証明書をダウンロード] をクリックしファイルを保存します。
8. ファイル名をpaypal_live_cert.pemなどわかりやすい名前に変更します。
拡張子は.txt以外でも構いません。ファイルの保存先を忘れないでください。
タスク終了後:

Java用ペイパルSDK、.NET用ペイパルSDK、Classic ASP用ペイパルSDKのいずれかをご利用の場
合は、PCKS12形式で証明書を暗号化する必要があります。

.NET用ペイパルSDKまたはClassic ASP用ペイパルSDKをご利用の場合には、追加の作業を行って
証明書をインポートする必要があります。
証明書をPKCS12形式で暗号化する
Java用ペイパルSDK、.NET用ペイパルSDK、Classic ASP用ペイパルSDKでは、証明書をPKCS12形式
で暗号化するための追加作業が必要です。Sandbox証明書と本番用証明書の両方に対して本作業を行っ
てください。
注： PHP用ペイパルSDKをご利用の場合は、本作業は必要ありません。
ペイパルからダウンロードした証明書はPEM形式です。この証明書にはお客様の公開証明書と関連付け
られたプライベートキーが含まれます。PEM証明書は人間には読めませんが、暗号化はされていません。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
49
API信用証明書の取得
API証明書の作成
本作業にはOpenSSL暗号化ツールが必要です。基本的にUnixには本ツールがインストールされています。
Windowsをお使いの場合には、ご自身でOpenSSLをダウンロードしなければなりません。この場合、
OpenSSLをインストールしOpenSSLをパスに追加する際にデフォルト設定をご使用ください。
注： Windowsでは、Pathは、[マイコンピュータ]アイコンを右クリックして表示したプロパティの[詳
細情報]タブからアクセスできるシステム環境変数です。[システム変数]パスと[ユーザー変数]パ
スを間違えないでください。OpenSSLを[システム変数]パスに追加します。
証明書をPKCS12形式に暗号化する手順を以下に示します。
1. OpenSSLを使用して、ダウンロードしたPEM形式の証明書からPKCS12形式の証明書を作成します。
openssl pkcs12 -export -in download.txt -inkey download.txt -out
certificate.p12
2. プロンプトに証明書用のエクスポートパスワードを入力します。
3. エクスポートパスワードを保存します。
証明書のインポート
.NET用ペイパルSDKまたはClassic ASP用ペイパルSDKの場合、Windows HTTPサービス証明書構成
ツール（WinHTTPCertCfg）をダウンロードし実行してください。.NET形式を利用し、.NET用ペイパ
ルSDKで開発を行う場合は、証明書をご利用になる前に追加の作業が必要です。
WinHTTPCertCfgを使用して証明書をWindows証明書ストアにインポートし、お客様のウェブアプリ
ケーションを実行するユーザーにプライベートキーへのアクセスを許可します。これはペイパル要件で
はなく、Windows要件です。WinHTTPCertCfgはマイクロソフトのWindows Server 2003リソース
キットツールページからダウンロードできます。マイクロソフトの文書作成に関して
は、WinHttpCertCfg.exe（証明書構成ツール）をご覧ください。
証明書のインポートは以下の手順で行ってください。
1. WinHTTPCertCfgを実行し、証明書をWindows証明書ストアにインポートして、お客様のウェブア
プリケーションを実行する相手方に対しプライベートキーへのアクセスを許可します。
WinHttpCertCfg -i certificate.p12 -p privateKeyPassword -c
上記でcertificateはお客様のPKCS12証明書を指し、privateKeyPasswordはエクスポートパスワー
ドを指します。
50
2012年12月
エクスプレスチェックアウトインテグレーションガイド
API信用証明書の取得
API証明書の作成
2. WinHTTPCertCfgを使用して、LOCAL_MACHINE¥My -a username内のユーザー名を以下の設定
値に変更します。
構成
ユーザー名の設定値
ASP. NET
ASPNET
Windows IIS 5 デフォルト構成
IWAM_machineName
（machineNameはコンピュータ名のこと）
Windows IIS 6 デフォルト構成
“NETWORK SERVICE”
（必ず引用符を付けること）
エクスプレスチェックアウトインテグレーションガイド
2012年12月
51
API信用証明書の取得
API証明書の作成
52
2012年12月
エクスプレスチェックアウトインテグレーションガイド
B
Chapter B
ペイパルName-Value Pair APIの
基本
Name-Value Pair（NVP）APIは、メッセージのリクエスト・レスポンスフィールド間の関連付けや、
フィールド値の関連付けをパラメータに基づいて行います。リクエストメッセージはAPIがお客様のウェ
ブサイトから送信し、レスポンスメッセージは、お客様のサイトがペイパルサーバーのクライアントと
なるクライアントサーバーモデルを使用してペイパルが返します。
注： PayFlow APIもName-Value Pairを使用して、メッセージのリクエスト・レスポンスフィールドの
関連付けや値の関連付けを行います。しかしPayFlow APIとNVP APIは同一ではありません。
PayFlow APIの詳細は、ウェブペイメントプロPayflow用デベロッパーガイドをご覧ください。
ペイパルAPI クライアントサーバーアーキテクチャー
ペイパルAPIは、お客様のサイトがペイパルサーバーのクライアントとなるクライアントサーバーモデル
を使用しています。
お客様のサイト上のページからペイパルAPIサーバーにリクエストを送り、サーバー上でアクションを開
始します。ペイパルサーバーはリクエストされたアクションの受領通知またはエラー発生通知を返しま
す。レスポンスにはリクエストに関する追加情報が含まれる場合があります。下の図に基本的なリクエ
スト・レスポンスのメカニズムを表示します。
ペイパルから買い手の配送先住所を入手する場合の例を説明します。買い手の詳細情報を入手するAPI
オペレーションを指定してリクエストを開始します。ペイパルAPIサーバーからのレスポンスには、リク
エストが成功したかどうか記述されています。オペレーションが成功した場合には、要求した情報がレ
スポンスに含まれます。この例の場合、買い手の配送先住所がレスポンスに含まれます。オペレーショ
ンが失敗した場合には、1件以上のエラーメッセージがレスポンスに含まれます。
関連情報:
56ページ「NVPリクエストの作成」
60ページ「NVPレスポンスへの対応」
エクスプレスチェックアウトインテグレーションガイド
2012年12月
53
PayPal名前/値ペアAPIの基本
ペイパルAPI
クライアントサーバーアーキテクチャー
ペイパルName-Value Pair APIリクエスト・レスポンス
ペイパルNVP APIオペレーションを実行するには、NVP形式のリクエストをペイパルNVPサーバーに送
信し、返されたレスポンスの解釈を行います。
下の図の例では、お客様のサイトでリクエストを作成しています。ペイパルサーバーがリクエストを実
行し、お客様のサイトにレスポンスを返します。
リクエストの内容は以下のとおりです。

METHOD=名前で指定する実行APIオペレーション名とバージョン
注： METHODパラメータ以降のパラメータの順序は任意です。

リクエストを作成したペイパルアカウントを識別する信用証明書

実行するAPIオペレーションを制御するリクエスト固有の情報
ペイパルAPIサーバーがオペレーションを実行しレスポンスを返します。レスポンスの内容は以下のとお
りです。

オペレーションの成功・失敗、警告メッセージの有無を示す確認応答ステータス

ペイパルがAPIオペレーションの実行状況をトラッキングするための情報

リクエストに応じるために必要なレスポンス固有の情報
UTF-8 文字エンコーディング
PayPal APIでは、リクエストに含まれるすべてのデータがUnicode、具体的にはUnicode (またはUCS)
変換形式の8ビットエンコーディング方式 (UTF-8) であることを前提としています。
レスポンスは必ずUTF-8データを返します。
複数のAPIオペレーション
エクスプレスチェックアウトなど一部の機能では複数のAPIオペレーションの呼び出しが必要です。
通常、このような機能では以下の操作が必要となります。
54
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal名前/値ペアAPIの基本
NVP形式
1. ペイパルがお客様の買い手のブラウザをリダイレクトする復帰URLを指定するSetExpressCheckout
などのAPIオペレーションを呼び出します。このAPIオペレーションでその他の設定も行うことがで
きます。
2. ペイパルで買い手の許可を受領した後、GetExpressCheckoutDetails や
DoExpressCheckoutPaymentなどほかのAPIオペレーションを呼び出します。
以下の図にお客様のサイトとペイパル間の実行フローを示します。
トークンの使用
通常、ペイパルへのリダイレクトを設定するAPIオペレーションがトークンを返します。トークンはペイ
パルへのリダイレクト中のパラメータとして渡されます。このトークンは関連するAPIオペレーションで
も必要となる場合があります。
NVP形式
NVPは文字列で名前や値を指定する方法です。NVPはURI指定におけるクエリ用の略式名称です。NVP文字
列はURLに追加されます。
NVP文字列は以下のガイドラインに準拠しています。

等号（=）で名前と値を分割します。以下に例を示します。
FIRSTNAME=Robert
エクスプレスチェックアウトインテグレーションガイド
2012年12月
55
PayPal名前/値ペアAPIの基本
NVPリクエストの作成

Name-Value Pairはアンパサンド（&）で分割します。以下に例を示します。
FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore

NVP文字列中の各値はURLでエンコードされています。
NVPリクエストの作成
Name-Value Pairのリクエスト形式で、実行するAPIオペレーション、ペイパルがお客様のアカウント
にアクセスすることを承認する信用証明書、リクエストに使用する追加情報のフィールドを指定します。
関連情報:
15ページ「ペイパルAPIクライアントサーバーアーキテクチャー」
ペイパルAPIオペレーションの指定
ペイパルAPIのNVPバージョンでは、各リクエストに実行するペイパルAPIオペレーションの名前とバー
ジョンを指定する必要があります。
NVPリクエストのAPIオペレーション部分を以下の図に示します。
メソッドでお客様が実行したいペイパルオペレーションを指定し、各メソッドにはバージョンが関連付
けられています。また、メソッドとバージョンでAPIオペレーションの詳細動作を定義しています。通常、
APIオペレーションの動作のバージョンによる違いはありません。ただし、バージョンを変更した場合は、
コードの再テストを十分に実施してください。
メソッドとバージョンの指定方法を以下に説明します。
1. ご使用になるPayPal APIオペレーションを選択します。
METHOD=operation
2. 適切なバージョンを選択します。
通常APIオペレーションの最新バージョンを使用します。
VERSION=version_number
56
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal名前/値ペアAPIの基本
NVPリクエストの作成
API信用証明書の指定
ペイパルAPIオペレーションを実行する各リクエストにAPI信用証明書を指定する必要があります。
ペイパルAPIオペレーションを実行する場合、APIオペレーションをリクエストしていることを認証する
ために署名などの信用証明書を使用します。NVPリクエストに含まれるAPI信用証明書部分を以下の図に
示します。
重要：インプリメンテーションの際にUSER、PWD、SIGNATUREの値を保護する必要があります。お
客様のウェブサーバのドキュメントルート以外の安全な場所にこれらの値を保存し、お客様のeコ
マースアプリケーションを実行するシステムユーザーのみがアクセスできるように、ファイルに
アクセス制限を設定してください。
以下の手順に従ってペイパルがお客様のリクエストを認証できるようにしてください。
1. お客様のアカウントに関連付けられたAPIユーザー名を指定します。
USER=API_username
2. APIユーザー名に関連付けられたパスワードを指定します。
PWD=API_password
3. API証明書ではなく、API署名を使用している場合、APIユーザー名に関連付けられたAPI署名を指定
します。
SIGNATURE=API_signature
4. オプションとなりますが、サードパーティのマーチャントの代わりにAPIオペレーションの呼び出し
を行う場合、そのマーチャントのペイパルに登録されたメールアドレスを指定できます。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
57
PayPal名前/値ペアAPIの基本
NVPリクエストの作成
SUBJECT=merchantEmailAddress
注：通常、マーチャントがショッピングカートに対してサードパーティによる許可を与えます。そのま
えにマーチャントがお客様に対しAPIオペレーションの実行許可を与える必要があります。
cURLでの信用証明書の指定
cURLを使った署名の指定方法例を以下に示します。
curl --insecure https://api-3t.sandbox.paypal.com/nvp -d ^
"METHOD=name^
&VERSION=XX.0^
&USER=API_username^
&PWD=API_password^
&SIGNATURE=API_signature^
&..."
注：上記の例は安全な接続を確立していないため、paypal.comでは実際には使用しないでください。
URL エンコーディング
HTTPで送信されるペイパルAPIオペレーション実行リクエストはすべてURLエンコーディングが必要で
す。エンコーディングによって、特殊文字、URLで利用できない文字、等号やアンパサンドなどURLで
特別な意味をもつ文字を送信できるようになります。
ペイパルNVP APIはHTTPプロトコルを使ってリクエストを送信したり、ペイパルAPIサーバーからレス
ポンスを受信したりします。エンコーディングしていないデータは、リクエストの一部としてではなく、
HTTPプロトコルの一部として誤って解釈される可能性があるため、HTTPプロトコルで送信されるデー
タはすべてエンコーディングする必要があります。ほとんどのプログラミング言語は文字列をURLエン
コーディングする機能を備えています。必ずAPIリクエスト全体をURLエンコーディングしてください。
エンコーディングしないと、予期しないデータがエラーの原因となる場合があります。
注： HTTP 形式は、ほとんどのブラウザで自動的に URLエンコーディングされます。
以下のNVP文字列の場合、
NAME=Robert Moore&COMPANY=R. H. Moore & Associates
以下のようにエンコーディングされます。
NAME=Robert+Moore&COMPANY=R%2E+H%2E+Moore+%26+Associates
NVP文字列のURLエンコーディング、URLデコーディングには以下の方法を使用してください。
58
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal名前/値ペアAPIの基本
NVP
APIオペレーションの実行
URLエンコーディング・デコーティング方法
言語
ASP.NET
Classic ASP
Java
PHP
ColdFusion
方法
エンコーディング
System.Web.HttpUtility.UrlEncode(buffer,
Encoding.Default)
デコーディング
System.Web.HttpUtility.UrlDecode(buffer,
Encoding.Default)
エンコーディング
Server.URLEncode
デコーディング
組み込み機能ではありません。インプリメンテーション例はインターネットをご
覧ください。
エンコーディング
java.net.URLEncoder.encode
デコーディング
java.net.URLDecoder.decode
エンコーディング
urlencode()
デコーディング
urldecode()
エンコーディング
URLEncodedFormatstring [, charset ]
デコーディング
URLDecodeurlEncodedString[, charset])
関連情報:
62ページ「URLデコーディング」
Name-Value Pairのリスト構文
ペイパルAPIは、リストとして定義されたNVPフィールド用に特殊な構文を使用します。
ペイパル APIへのNVPのインターフェイスでは、各フィールドに一意の名前が必要です。このAPIにお
いては、リストにL_というプリフィックスが付加されます。リスト中の要素を識別するために、第一要
素を0とする、リストの先頭から始まるオフセットを使用します。たとえば、記述の1行目がL DESC0の
場合、2行目はL_DESC1、以下同様となります。
注：すべてのリストの先頭にL_が付加されるわけではありませんが、いずれのリストも第一要素は0で
始まります。
NVP APIオペレーションの実行
ペイパルNVP APIオペレーションを実行するには、HTTPS POSTリクエストをペイパルAPIサーバーに
送信するか、買い手のブラウザとペイパルAPIサーバー間のアクセスを安全に行うためにcURLやほかの
仕組みを使用します。たとえば、買い手のブラウザをお客様のサーバーのクライアントとし、お客様の
サーバーをペイパルAPIサーバーのクライアントにするようなシステムをインプリメントします。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
59
PayPal名前/値ペアAPIの基本
NVPレスポンスへの対応
ペイパルサーバーの指定
ペイパルAPIサーバーにリクエストを送信しペイパルAPIオペレーションを実行します。
ペイパルNVP APIオペレーションを実行するには、以下のいずれかのエンドポイントにリクエストを送
信してください。
サーバーエンドポイント
内容
https://api3t.sandbox.paypal.com/nvp
API署名で使用するSandboxサーバー。お客様のAPIテストに使用
します。
https://api-3t.paypal.com/nvp
API署名で使用するペイパル実稼働サーバー。
https://api.sandbox.paypal.com/nvp
API証明書で使用するSandboxサーバー。お客様のAPIテストに使
用します。
https://api.paypal.com/nvp
API証明書で使用するペイパル実稼働サーバー。
注：サーバーエンドポイントごとに異なるAPI信用証明書を使用する必要があります。通常Sandboxで
のテスト時にAPI信用証明書を取得し、実稼働サーバー用には新たに別の信用証明書を取得します。
実稼働時に新しい信用証明書を使用するには各APIリクエストを変更する必要があります。
APIオペレーションのロギング
実行したペイパルAPIオペレーションのリクエスト・レスポンスメッセージ中の基本情報を記録します。
ペイパルに対するAPIオペレーションを識別するCorrelation IDをレスポンスメッセージから記録し、特
定の取引に関するサポートが必要な場合にこのIDをマーチャントテクニカルサポートに提示します。
ペイパルAPIオペレーションに対するすべてのレスポンスにはデバッグ処理に役立つ情報が含まれてい
ます。レスポンスメッセージ中のCorrelation IDだけではなく、取引IDやタイムスタンプなどの情報も
記録しておくと、ペイパルウェブサイトやAPIで取引を確認することができます。
「冗長（verbose）」モー
ドでリクエストとレスポンスをそのまま記録するスキームをすることもインプリメントすることも可能
です。ただしリクエスト中のパスワードは決して記録しないでください。
NVPレスポンスへの対応
Name-Value Pairのレスポンスは、リクエストへの回答に加え、APIオペレーションと実行の詳細を示
す共通のフィールドで構成されています。
ペイパルNVP APIオペレーションに対するレスポンス内のフィールドを以下の図に示します。
60
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal名前/値ペアAPIの基本
NVPレスポンスへの対応
関連情報：
15ページ「ペイパルAPIクライアントサーバーアーキテクチャー」
共通レスポンスフィールド
ペイパルAPIは、要求されたペイパルAPIオペレーションに固有のフィールドだけではなく、常に共通の
フィールドも返します。
ペイパルAPIレスポンスに含まれるフィールドを以下に示します。
フィールド
内容
ACK
以下のいずれかの確認応答ステータス
 Success: オペレーションが正常に実行されたことを示します。
 SuccessWithWarning：オペレーションが正常に実行されたことを示します。ただし調査
が必要な警告メッセージがレスポンスで返されます。
 PartialSuccess：一部の支払いは正常に処理されたものの、残りの支払い処理が失敗した
ことを示します。
PartialSuccess は、平行支払いインテグレーションのDoExpressCheckoutPaymentで
のみ返されます。
 Failure：オペレーションが正常に実行されなかったことを示します。失敗の理由を示す1件
以上のエラーメッセージがレスポンスに表示されます。
 FailureWithWarning：オペレーションが正常に実行されなかったことを示し、調査が必要
なメッセージがレスポンスで返されます。
CORRELATIONID
ペイパルとの取引を識別する一意のCorrelation ID
TIMESTAMP
リクエストされたAPIオペレーションが実行された日時
VERSION
APIのバージョン
BUILD
APIのサブバージョン
エラーレスポンス
ACKの値がSuccess以外の場合、APIレスポンスフィールドが返されない場合があります。エラーレスポ
ンスは以下に示す一般的なフォーマットです。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
61
PayPal名前/値ペアAPIの基本
NVPレスポンスへの対応
エラーレスポンスのフォーマット
エラーのレスポンス
フィールド
ACK=notSuccess&TIMESTAMP=date/timeOfResponse&
CORRELATIONID=debuggingToken&VERSION=VersionNo&
BUILD=buildNumber&L_ERRORCODE0=errorCode&
L_SHORTMESSAGE0=shortMessage&
L_LONGMESSAGE0=longMessage&
複数のエラーが返されます。
各エラーの末尾に数値が付
加され、0から始まる数値は
エラーごとに1ずつ増えてい
きます。
L_SEVERITYCODE0=severityCode
L_ERRORPARMIDn および L_ERRORPARAMVALUEn フィールドに追加のパススルー情報が表示される
場合があります。レスポンス例を以下に示します：
TIMESTAMP=2011%2d11%2d15T20%3a27%3a02Z&CORRELATIONID=5be53331d9700&ACK=Fail
ure&VERSION=78%2e0&BUILD=000000&L_ERRORCODE0=15005&L_SHORTMESSAGE0=Processo
r%20Decline&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e&
L_SEVERITYCODE0=Error&L_ERRORPARAMID0=ProcessorResponse&L_ERRORPARAMVALUE0=
0051&AMT=10%2e40&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M
この場合、パラメータIDは ProcessorResponse で、クレジットカードまたはデビットカードの処理
端末によるエラーレスポンスを示します。この値には処理端末特有のエラーが含まれています。値はペ
イパルが設定するのではなく、発信元から渡されます。
注：ペイパルは、L_ERRORPARMIDn および L_ERRORPARAMVALUEn フィールドに含まれる特定の値の
み渡します。
URLデコーディング
ペイパルNVP APIで使用するHTTP POSTオペレーションに対するレスポンスはすべてデコーディング
する必要があります。
ペイパルNVP APIは、リクエストの送信やペイパルAPIサーバーからのレスポンスの受信にHTTPプロト
コルを使用します。HTTPプロトコルで返されるデータを正しく表示するには、データをすべてデコー
ディングする必要があります。ほとんどのプログラミング言語は文字列をデコーディングする機能を備
えています。
関連情報:
58ページ「URLエンコーディング」
62
2012年12月
エクスプレスチェックアウトインテグレーションガイド
C
Chapter C
ペイパルSOAP API の基本
ペイパルSOAP APIは、簡易オブジェクトアクセスプロトコル（SOAP）
、Web サービス定義言語（WSDL）
、
XML スキーマ定義言語（XSD）など、総称してウェブサービスと呼ばれるオープンスタンダードに基づ
いています。各種プラットフォーム上のさまざまな開発ツールがウェブサービスをサポートしています。
多くのウェブサービスと同様に、ペイパルSOAPもクライアント側・サーバー側スキーマ、ハードウェア、
ソフトウェアサーバー、コアサービスで構成されています。
ペイパルSOAP概略図
オブジェクト指向処理モデルでは、SOAPリクエスト・レスポンスのインターフェイスは、お客様のアプ
リケーションのネイティブプログラミング言語で記述されたオブジェクトになります。サードパーティ
のSOAPクライアントは、PayPal SOAPメッセージの構造、メッセージの内容、PayPal APIサービスの
バインディングが指定されたペイパル提供のWSDLとXSDファイルからビジネスオブジェクトインター
フェイスとネットワークスタブを生成します。ビジネスアプリケーションは、オブジェクトメソッドを
呼び出してデータの送受信を行うために、オブジェクトプロパティ形式でデータを処理します。
SOAP クライアントは、SOAP リクエストの構築、ペイパルサービスへの SOAP リクエストの送信、
およびオブジェクトへのレスポンスの変換を詳細に処理します。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
63
PayPal SOAP APIの基本
ペイパルWSDL/XSDスキーマ定義
ペイパルWSDL/XSDスキーマ定義
ペイパルウェブサービスAPIを利用してアプリケーションを開発するには、ペイパルウェブサービスス
キーマとその基礎となるeBayビジネス言語（eBL）のベースコンポーネントおよびコアコンポーネント
が必要となります。WDSLファイルとXSDファイルの場所を以下に示します。
ペイパルWSDLファイルとXSDファイルの場所
ペイパルSandbox API サービスを利用した開発とテスト
ペイパルスキーマ
https://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl
eBLベースコンポーネントと
コンポーネントタイプ
https://www.sandbox.paypal.com/wsdl/eBLBaseComponents.xsd
https://www.sandbox.paypal.com/wsdl/CoreComponentTypes.xsd
本番ペイパルウェブサービスAPIサービスでの実稼働
ペイパルスキーマ
https://www.paypal.com/wsdl/PayPalSvc.wsdl
eBLベースコンポーネントと
コンポーネントタイプ
http://www.paypal.com/wsdl/eBLBaseComponents.xsd
http://www.paypal.com/wsdl/CoreComponentTypes.xsd
ペイパルSOAP APIの定義
ペイパルSOAP APIは、特定の業務向けの個別のAPI 定義で構成されています。APIはeBay ビジネス言
語（eBL）のベースコンポーネントおよびコアコンポーネントを基盤としています。eBLのコア構造であ
るAbstractRequestType と AbstractResponseTypeは、各ペイパルAPIのSOAPリクエストとSOAP
レスポンスのベースとなります。AbstractResponseTypeは、すべてのペイパルAPIに共通のエラーメッ
セージのフレームワークとなります。
ペイパルが決定した一部のスキーマ設計は、企業が独自のアプリケーションを設計する際に影響を与え
る可能性があります。

列挙：ペイパルAPIスキーマで直接定義されます。

トラブルシューティング情報：ペイパルAPIがエラーの原因となった要素に関する情報を返します。

下位互換性：ペイパルAPIはバージョン管理されているため、サーバー側スキーマに新しい要素が導
入された場合でも、ビジネスアプリケーションの下位互換性が維持されます。
注： eBLでは、オークションの処理専用の構造を多数定義しています。ペイパルのSOAPスキーマには、
eBayのSOAPとの互換性を維持し、将来的にSOAPをeBayとペイパルで共用できるようにこれらの
定義が含まれています。本書では、ペイパルSOAP APIの使用に関するSOAP定義のみを取り上げて
います。
64
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal SOAP APIの基本
セキュリティ
セキュリティ
ペイパル SOAP APIサービスは、承認されたペイパル会員しか使用できないように保護されています。
セキュリティには以下の4つのレベルがあります。
1. 必須APIユーザー名（Usernameフィールド）とAPIパスワード（Passwordフィールド）
2. 以下のいずれかの3番目の必須認証メカニズム
- ペイパル発行のAPI証明書によるクライアント側リクエストの署名
- リクエスト内のAPI署名によるリクエスト認証（Signatureフィールド）
3. ほかのアカウントの代理でAPIコールを行うためのオプションのサードパーティ認証（オプションの
Subjectフィールド）
4. セキュアソケットレイヤー（SSL）データ転送
上記レベルのいずれかでセキュリティの認証に失敗した場合は、ペイパル SOAP APIサービスへのアク
セスは拒否されます。
SOAP RequesterCredentials:ユーザー名、パスワード、署名、件名
お客様のビジネスの安全のために、ペイパルはマーチャントやサードパーティデベロッパーが取引を開
始する前に、取引の許可を得ていることを確認する必要があります。ペイパルはリクエストごとに認証
を行います。リクエストを認証できない場合は、SOAPセキュリティ違反が返されます。
API ユーザー名と API パスワードの組み合わせを渡す場合は、SOAPクライアントの SOAPリクエス
トヘッダーで Username要素と Password要素を設定する必要があります。また、Signature要素また
は Subject要素を設定して、API署名文字列とオプションのサードパーティアカウントのメールアドレ
スを認証用に指定することもできます。
RequesterCredentials要素の一部を以下に示します。これらの要素はすべてのSOAPリクエストに必須
です。
<SOAP-ENV:Header>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”
xsi:type=”ebl:CustomSecurityHeaderType”>
<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”
xsi:type=”ebl:UserIdPasswordType”>
<Username>api_username</Username>
<Password>api_password</Password>
<Signature>api_signature</Signature>
<Subject>authorizing_account_emailaddress</Subject>
</Credentials>
</RequesterCredentials>
</SOAP-ENV:Header>
エクスプレスチェックアウトインテグレーションガイド
2012年12月
65
PayPal SOAP APIの基本
SOAPサービスエンドポイント
SOAPヘッダーのRequesterCredentialsの認証要素
要素
値
内容
<Username>
api_username
ペイパル SOAP APIを利用するためのデジタル証明書の申請時に、ペイ
パルが自動的に生成するお客様のAPIユーザー名。この値を確認するに
は、https://www.paypal.com/の[個人設定]から[APIアクセス] >
[API証明書情報]を選択してください。
<Password>
api_password
ペイパル SOAP APIを利用するためのデジタル証明書の申請時にお客
様が指定したAPIパスワード。
<Signature>
api_signature
API署名（API証明書の代わりにAPI署名を使用する場合）
<Subject>
authorizing_
account_
emailaddress
サードパーティの代理でペイパル SOAP APIにリクエストを送信して
いる場合のサードパーティのメールアドレス。特定のペイパル APIリク
エストを実行する場合、APIユーザー名にサードパーティからの許可が
付与されていなければなりません。
関連情報:
67ページ「リクエストの構造」
SOAPサービスエンドポイント
選択した認証メカニズムによって異なるサービスエンドポイントでSOAPリクエストの処理を行う必要
があります。
SOAP サービスエンドポイント
認証
メカニズム
実稼働エンドポイント
テスト（Sandbox）エンドポイント
API署名
https://api-3t.paypal.com/2.0/
https://api-3t.sandbox.paypal.com/2.0/
API 証明書
https://api.paypal.com/2.0/
https://api.sandbox.paypal.com/2.0/
SOAP リクエストエンベロープ
ペイパル SOAPリクエストエンベロープの内容を以下の図に示します。
ペイパル APIはすべてAbstractRequestTypeとAbstractResponseTypeの2つのコア構造に基づい
ています。
66
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal SOAP APIの基本
リクエストの構造
SOAP リクエストエンベロープ図
リクエストの構造
ペイパル SOAP APIの必須要素を示すSOAPリクエスト構造を注釈付きで以下に説明します。
ペイパル API SOAPリクエストの一般的な構造
<?xml version=”1.0” encoding=”UTF-8”?>
<SOAP-ENV:Envelope xmlns:xsi= ” http://www.w3.org/2001/XMLSchema-instance”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”>
<SOAP-ENV:Header>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”>
<Credentials xmlns=”urn:ebay:apis:eBLBaseComponents”>
<Username>api_username</Username>
エクスプレスチェックアウトインテグレーションガイド
2012年12月
67
PayPal SOAP APIの基本
リクエストの構造
<Password>api_password</Password>
<Signature/>
<Subject/>
</Credentials>
</RequesterCredentials>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<specific_api_name_Req xmlns=”urn:ebay:api:PayPalAPI”>
<specific_api_name_Request>
<Version xmlns=urn:ebay:apis:eBLBaseComponents”>service_version
</Version>
<required_or_optional_fields xsi:type=”some_type_here”>data
</required_or_optional_fields>
</specific_api_name_Request>
</specific_api_name_Req>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
一般的なSOAPリクエストに関する注釈
行
コメント
12、13
<Usename>と<Password>フィールドは、ペイパルSOAP API<RequesterCredentials>セキュリ
ティ認証メカニズムの一部であり、すべてのSOAPリクエストヘッダーに構築する必要があります。
14
API信用証明書にAPI署名をご利用の場合、<Signature>要素にお客様のAPI署名文字列を入力してく
ださい。
15
<Subject>要素には、お客様がリクエストの実行許可を得たサードパーティのペイパルアカウントを
指定できます。
19～27
すべてのペイパルAPIのSOAPリクエストは、この要素・名前付けパターンに準拠します。
APIに固有の名前にReqに付加し、この要素内でspecific_api_name_Requestをネストします。
specific_api_name_Requestごとに対応するspecific_api_name_RequestTypeが存在します。
22
各SOAPリクエストでペイパルSOAP APIバージョン番号が必要となります。
バージョン番号はns:versioninの値になります。
https://www.paypal.com/wsdl/PayPalSvc.wsdl.
24
特定のリクエストの必須要素およびオプション要素の詳細に関しては、各APIの説明をご覧ください。
関連情報:
65ページ「SOAP RequesterCredentials：ユーザー名、パスワード、署名、件名」
68
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal SOAP APIの基本
SOAPメッセージスタイル：doc-literal
SOAPメッセージスタイル：doc-literal
ペイパルはrpc-encoding ではなく、doc-literal SOAPメッセージングを使用しています。doc-literal
では、単一のサービスインターフェイスコールにより、XMLドキュメントをリクエストでペイパルAPI
サーバーに渡し、このリクエストに対してXMLドキュメントインスタンスが返されます。
レスポンスの構造
レスポンスがSuccessの場合にペイパルAPIから返されるSOAPレスポンスの構造について、注釈付きで
以下に説明します。
<?xml version=”1.0”?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV= ”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
xmlns:xs=”http://www.w3.org/2001/XMLSchema”
xmlns:cc=”urn:ebay:apis:CoreComponentTypes”
xmlns:wsu=”http://schemas.xmlsoap.org/ws/2002/07/utility”
xmlns:saml=”urn:oasis:names:tc:SAML:1.0:assertion”
xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”
xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xmlns:ebl=”urn:ebay:apis:eBLBaseComponents”
xmlns:ns=”urn:ebay:api:PayPalAPI”>
<SOAP-ENV:Header>
<Security
xmlns=”http://schemas.xmlsoap.org/ws/2002/12/secext”
xsi:type=”wsse:SecurityType”
/>
<RequesterCredentials xmlns=”urn:ebay:api:PayPalAPI”
xsi:type=”ebl:CustomSecurityHeaderType”>
<Credentials
xmlns=”urn:ebay:apis:eBLBaseComponents”
xsi:type=”ebl:UserIdPasswordType”
/>
</RequesterCredentials>
</SOAP-ENV:Header>
<SOAP-ENV:Body id=”_0”>
<specific_api_name_Response xmlns=”urn:ebay:api:PayPalAPI”>
<Timestamp xmlns=”urn:ebay:api:PayPalAPI”> dateTime_in_UTC/GMT
</TIMESTAMP>
<Ack xmlns=”urn:ebay:apis:eBLBaseComponents”>Success</Ack>
<Version xmlns=”urn:ebay:apis:eBLBaseComponents”>
serviceVersion
</Version>
エクスプレスチェックアウトインテグレーションガイド
2012年12月
69
PayPal SOAP APIの基本
エラーレスポンス
<CorrelationId xmlns=”urn:ebay:apis:eBLBaseComponents”>
applicationCorrelation
</CorrelationID>
<Build xmlns=”urn:ebay:apis:eBLBaseComponents”>
api_build_number
</Build>
<elements_for_specific_api_response> data
</elements_for_specific_api_response>
</specific_api_name_Response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
一般的なSOAPレスポンスの注釈
行
コメント
22、31
specific_api_name_Responseの開始要素と終了要素
23
各APIレスポンスは、UTC/GMT形式の日時タイムスタンプを含みます。
24
対応するリクエストが成功した場合、<Ack>要素にSuccessの文字列が挿入されます。
リクエストが失敗した場合は、AckにSuccess以外の値が設定され、エラーの原因解決に役立つ情報
を含む<Errors>要素がレスポンスの本文に含まれます。70ページの「エラーレスポンス」をご覧く
ださい。
26
<CorrelationID> 要素には、リクエストを処理したペイパルアプリケーションに関する情報が含ま
れます。
リクエストで発生した問題を解決する必要がある場合は、この要素の値を使用してください。
27～30
各ペイパルAPIはレスポンスの定義に応じて異なる構造を返します。詳細については各APIの説明を
ご覧ください。
注：フィールドがAPIレスポンスの正規の構造に定義されていたとしても、必ずしもそのフィールド
が返されるわけではありません。ペイパルがフィールドに対応するデータを記録している場合の
み、データがレスポンスで返されます。
関連情報:
70ページ「エラーレスポンス」
エラーレスポンス
リクエストの形式やその他に誤りがある場合は、エラー原因の解決に役立つ<Errors>要素とほかの要素
がSOAPレスポンスの本文に含まれます。
エラーメッセージの構造は以下の通りです：
70
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal SOAP APIの基本
エラーレスポンス
このような追加要素のうち、特に重要なものを以下に示します。

ShortMessage

LongMessage

ErrorCode
ErrorParametersType の一部として追加情報が表示される場合があります。例えば、ParamID の
エラーが ProcessorResponse の場合、Value には 0091 のようにプロセッサ特有のエラーが含まれ
ます。ErrorParametersType の値はペイパルが設定するのではなく、発信元から渡されます。
お客様のAPIユーザー名とパスワードが、ペイパルが保存している正式APIユーザー名とパスワードと一
致しない場合のエラーレスポンスの例を以下に示します。
SOAPエラーレスポンス例：不正なユーザー名またはパスワード
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV: Envelope details not shown >
<S OAP-ENV:Header>... details not shown.</SOAP-ENV:Header>
<SOAP-ENV:Body id="_0">
<GetTransactionDetailsResponse xmlns="urn:ebay:api:PayPalAPI">
<Timestamp xmlns="urn:ebay:apis:eBLBaseComponents">
2005-02-09T21:51:26Z
</Timestamp>
<Ack xmlns="urn:ebay:apis:eBLBaseComponents">Failure</Ack>
<Errors
xmlns="urn:ebay:apis:eBLBaseComponents"
xsi:type="ebl:ErrorType">
<ShortMessage xsi:type="xs:string">
Authentication/Authorization Failed
</ShortMessage>
<LongMessage xsi:type="xs:string">
Username/Password is incorrect
</LongMessage>
<ErrorCode xsi:type="xs:token">10002</ErrorCode>
<SeverityCode xmlns="urn:ebay:apis:eBLBaseComponents">
Error
</SeverityCode>
</Errors>
<CorrelationID xmlns="urn:ebay:apis:eBLBaseComponents">
debugging_info
</CorrelationID>
<Version xmlns="urn:ebay:apis:eBLBaseComponents">
エクスプレスチェックアウトインテグレーションガイド
2012年12月
71
PayPal SOAP APIの基本
ペイパルに問題を報告するためのCorrelationID
1.000000
</Version>
<Build xmlns="urn:ebay:apis:eBLBaseComponents">1.0006</Build>..
other elements in response.
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
関連情報:
69ページ「レスポンスの構造」
ペイパルに問題を報告するためのCorrelationID
CorrelationIDで返される値は、発生したエラーの原因をペイパルが正確に判断するための重要な情報です。
お客様がリクエストで発生した問題を解決しなければならない場合、問題をペイパルに報告できるよう
にCorrelationIDの値を記録しておいてください。
UTF-8 文字エンコーディング
ペイパルSOAP APIサービスでは、SOAPリクエストに含まれるデータはすべてUnicode、具体的には
Unicode（またはUCS）変換形式の8ビットエンコーディング方式（UTF-8）であることを前提としてい
ます。
SOAPレスポンスでは、必ずUTF-8でデータを返します。
日付形式
ペイパルSOAP APIスキーマは、ISO8601形式とns: dateTime 型を使用して、協定世界時（UTC/GMT）
で日付と時刻を定義しています。たとえば日付・時刻スタンプは2006-08-24T05:38:48Zのようにな
ります。
基幹通貨金額の基本データタイプ
BasicAmountTypeと呼ばれる通貨額データの基本タイプは文字列から抽出されます。すべての通貨額
フィールドは以下の構造になります。
1. currencyID属性が必要です。
2. 金額は小数点第2位まで表示します。
3. currencyID属性が必要です。
4. 金額は小数点第2位まで表示します。
72
2012年12月
エクスプレスチェックアウトインテグレーションガイド
PayPal SOAP APIの基本
基幹通貨金額の基本データタイプ
5. 小数点記号はピリオド（
「.」
）を使用します。
6. 桁区切り記号は使用できません。
7. BasicAmountTypeは、多数の異なる通貨コードを定義するデータタイプebl:CurrencyCodeType
となります。ただし、処理を正常に実行するには、有効な通貨コードをcurrencyCodeに設定する必
要があります。APIの中には、一部の通貨しかサポートしていないものもあります。
以下に例を示します。フィールド名の一例としてAmountを使用しています。実際のフィールド名はAPI
によって異なります。
<Amount currencyID=”currencyCode”>3.00</Amount>
エクスプレスチェックアウトインテグレーションガイド
2012年12月
73
PayPal SOAP APIの基本
基幹通貨金額の基本データタイプ
74
2012年12月
エクスプレスチェックアウトインテグレーションガイド
改訂履歴
ペイパルエクスプレスチェックアウトインテグレーションガイド改訂履歴
発行日
内容
12/12/12
メンテナンスリリース。エラー処理セクションにおけるエラー10386の処理に関する
情報をアップデート。
4/3/12
ウェブペイメントスタンダードをペイパルウェブペイメントスタンダード、ウェブペ
イメントプロをペイパルウェブペイメントプロに記述変更。
02/13/12
ユーザー体験に関する画像を更新。
06/21/11
概要の章、SOAPの追加情報、信用証明書、SDKs、実稼働を追加。定期支払いの章を
エクスプレスチェックアウト応用機能ガイドに移動。
05/02/11
モバイルエクスプレスチェックアウトの章をエクスプレスチェックアウト応用機
能ガイドに移動。
01/24/11
モバイル装置のゲストチェックアウトインテグレーション情報を追加、モバイル装
置での参照取引・定期支払いの使用制限を削除、モバイル装置でのドイツペイパルア
カウントの使用制限の削除。
12/20/10
例で使用しているフィールド名のうち指摘のあったものを変更。
11/15/10
モバイル装置用エクスプレスチェックアウトの対応地域の最新情報を含むバージョ
ン65.3へ更新。
10/26/10
「モバイル装置用エクスプレスチェックアウト」章の追加。
08/11/10
エクスプレスチェックアウトインテグレーションガイドを以下の2冊に分割。エク
スプレスチェックアウトインテグレーションガイド、エクスプレスチェックアウ
ト応用機能ガイド。
05/11/10
航空会社での使用を含む、NVPとSOAP APIを利用した平行支払いのインテグレー
ションの詳細を追加。新しい即時支払い機能の追加。最新の請求先住所を入手し、請
求同意書作成を省略し、BAUpdate APIの使用を明示する機能を持つ請求同意書の更
新。
03/10/10
平行支払いサポートの追加。
01/21/2010
買い手の連絡先情報、ギフトオプション、宣伝、ペイパルページに関するアンケート
を提供するの新しいエクスプレスチェックアウトフィールドの追加。配送情報を含
まない、新しいコールバック用レスポンスAPIフィールドの追加。
10/05/2009
即時支払いの追加。
技術的な正確さのための修正。
ペイパルプレースメントガイドラインの削除。
06/30/2009
支払い確認セクションの追加。
エクスプレスチェックアウトインテグレーションガイド
2012年12月
75
改定履歴
76
発行日
内容
06/04/2009
ペイパル確認ページの実稼働前に関する章の追加。ペイパル確認ページの更新。カス
タマイズに関する一部のトピックを本ガイドから別のガイドへ移動。カスタマイズに
関する一部のトピックは、現在はマーチャント設定管理ガイドに記載。
04/30/2009
企業レベルマーチャント向け初版作成および参照取引の章を追加。
04/08/2009
即時更新コールバックAPIに関する章の追加。
03/03/2009
eBayインセンティブ向けにuseraction = continue設定を追加。
11/13/2008
動的画像の統合に関する情報を追加。ペイパル確認ページに表示可能な注文詳細の情
報を追加。
06/30/2008
全面改訂
2012年12月
エクスプレスチェックアウトインテグレーションガイド

Download Report