PayPal NVP(名前-値ペア)API の基本

PayPal NVP(名前-値ペア)API の基本
NVP(名前-値ペア)API は、メッセージとその値のリクエストフィールドとレスポンスフィールド間におけるパラメータに基づく関連付け
を提供します。リクエストメッセージはこの API によりマーチャントの EC サイトから送信され、レスポンスメッセージはクライアント-サ
ーバーモデル(この場合マーチャントのサイトが PayPal サーバーのクライアント)を使って、PayPal によって返されます。
注: PayFlow API でも名前と値のペアを使って、メッセージとその値のリクエストフィールドとレスポンスフィールドのパラメータベース
の関連付けを提供しますが、PayFlow API は NVP API と同じではありません。PayFlow API の詳細については、Payflow
Gateway Developer Guide and Reference(Payflow ゲートウェイデベロッパーガイドおよびリファレンス) (HTML)をご覧
ください。
PayPal API クライアント・サーバーアーキテクチャ
PayPal API では、マーチャントの EC サイトが PayPal サーバーのクライアントになるクライアント-サーバーモデルが使用されてい
ます。
EC サイト上のページは、サーバーにリクエストを送信することで、PayPal API サーバー上のアクションを引き起こします。PayPal
サーバーは、リクエストされたアクションが実行されたかエラーが発生したかを示す確認応答を返します。この確認応答には、リクエ
ストに関する追加情報が含まれていることもあります。基本的なリクエストとレスポンスのメカニズムを以下の図に示します。
たとえば、PayPal から買い手の配送先住所を取得することができます。買い手の詳細を取得する API オペレーションを指定す
ることで、リクエストを開始できます。PayPal API サーバーからのレスポンスには、リクエスト内容の成否に関する情報が含まれま
す。オペレーションが成功すると、レスポンスには必要な情報が含まれます。この場合、レスポンスには買い手の配送先住所が含
まれることになります。オペレーションが失敗した場合、レスポンスには 1 件または複数のエラーメッセージが含まれます。
PayPal NVP API のリクエストとレスポンス
PayPal NVP API オペレーションを実行するには、NVP でフォーマットされたリクエストを PayPal NVP サーバーに送信し、返さ
れたレスポンスを解釈します。
下の図では、マーチャントの EC サイトでリクエストが生成されます。このリクエストは PayPal サーバーで実行され、レスポンスがマ
ーチャントのサイトに返されます。
リクエストの内容は以下のとおりです。

実行する API オペレーションの名前( METHOD=name で指定)と、そのバージョン
注: METHOD パラメータの後に、任意の順でパラメータを指定できます。

リクエストを生成した PayPal アカウントを識別する信用証明書

実行する API オペレーションを制御するリクエスト固有の情報
PayPal API サーバーでオペレーションが実行され、その結果を示すレスポンスが返されます。レスポンスの内容は以下のとおりで
す。

オペレーションの成否と警告メッセージが返されたかどうかを示す確認応答ステータス

API オペレーションの実行をトラッキングするために PayPal で使用できる情報

リクエストを満たすために必要となるレスポンス固有の情報
UTF-8 文字エンコーディング
PayPal API では、リクエストに含まれるすべてのデータが Unicode、具体的に述べると Unicode (または UCS)
Transformation Format の 8 ビットエンコーディング形式(UTF-8)であることが前提となります。
レスポンスのデータは常に UTF-8 で返されます。
複数の API オペレーション
エクスプレスチェックアウトなど、一部の機能では、複数の API オペレーションを呼び出す必要があります。
通常、これらの機能では、以下の手順を実行する必要があります。
1. PayPal で処理を終了した買い手のブラウザのリダイレクト先である復帰 URL を設定する API オペレーション
( SetExpressCheckout など)をコールします。その他の設定アクションも、この API オペレーションで実行できます。
2. PayPal に対する買い手の許可を受け取ったら、 GetExpressCheckoutDetails や DoExpressCheckoutPayment など
の追加 API オペレーションをコールします。
マーチャントの EC サイトと PayPal 間の実行手順を以下の図に示します。
トークンの使用
通常、PayPal へのリダイレクトをセットアップする API オペレーションでは、トークンが返されます。このトークンは、PayPal へのリダ
イレクトにおけるパラメータとして渡されます。トークンは、関連する API オペレーションでも必要となります。
NVP の形式
NVP は、文字列に名前と値を指定する方法です。NVP は、URI 仕様のクエリの非公式名です。NVP 文字列は URL に付加
されます。
NVP 文字列は、次のガイドラインに従います。

名前と値は等号記号(=)で区切られます。以下に例を挙げます。

FIRSTNAME=Robert

名前と値のペアはアンパサンド(&)で区切られます。以下に例を挙げます。

FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore

NVP 文字列の各値は URL エンコードされます。
NVP リクエストの作成
NVP リクエストは、実行する API オペレーション、PayPal がマーチャントのアカウントにアクセスすることを承認する信用証明書、
およびリクエストで使用される追加情報を含むフィールドを指定しています。
PayPal API オペレーションの指定
PayPal API の NVP バージョンでは、API オペレーションのバージョンとともに、各リクエスト内で実行する PayPal API オペレー
ションの名前を指定する必要があります。
NVP リクエストに含まれる API オペレーションの部分を以下の図に示します。
method で、実行する PayPal オペレーションを指定します。各メソッドは version に関連付けられています。メソッドとバージョ
ンの組み合わせで、API オペレーションの正確な動作が決まります。通常、API オペレーションの動作はバージョンごとに異なりま
せん。ただし、バージョンを変更した場合は、コードの再テストを十分に実施する必要があります。
メソッドとバージョン番号を指定するには:
1. 使用する PayPal API オペレーションを選択します。 METHOD=operation
2. 適切なバージョンを選択します。ほとんどの場合、最新バージョンの API オペレーションを使用します。
VERSION=version_number
署名を使用した API 信用証明書の指定
PayPal API オペレーションの実行リクエストごとに API 信用証明書を指定する必要があります。署名または証明書を使用でき
ますが、両方を使用することはできません。
PayPal API オペレーションを実行する場合は、API オペレーションをリクエストしていることを認証するために署名などの信用証
明書を使用します。 NVP リクエストに含まれる API 信用証明書の部分を以下の図に示します。
重要: 実装では、 USER 、 PWD 、および SIGNATURE の値を保護する必要があります。これらの値は、ウェブサーバーのド
キュメントルート以外のセキュアな場所に保存し、E コマースアプリケーションを実行するシステムユーザーのみがアクセスできるよう
にファイルのアクセス許可を設定してください。
PayPal がリクエストを認証できるようにするには
1. アカウントに関連付けられた API ユーザー名を指定します。 USER=API_username
2. API ユーザー名に関連付けられたパスワードを指定します。 PWD=API_password
3. API 証明書ではなく API 署名を使用している場合は、API ユーザー名に関連付けられた API 署名を指定します。
SIGNATURE=API_signature
4. オプションで、サードパーティのマーチャントの代わりに API オペレーションをコールする場合、そのマーチャントの PayPal 登録メー
ルアドレスを指定できます。 SUBJECT=merchantEmailAddress
注: 通常、マーチャントはサードパーティの権限をショッピングカートに付与します。マーチャントによって、あらかじめ、API オペレー
ションの実行を許可されている必要があります。
cURL を使用した信用証明書の指定
以下の例は、cURL を使用して署名を指定する 1 つの方法を示しています。
curl --insecure https://api-3t.sandbox.paypal.com/nvp -d ^
"METHOD=name^ &VERSION=XX.0^ &USER=API_username^ &PWD=API_password^ &SIGN
ATURE=API_signature^ &..."
注: この例ではセキュアな接続は確立されないため、paypal.com の実稼働環境での使用は控えてください。
URL エンコーディング
HTTP を介して送信される PayPal API オペレーションの実行リクエストをすべて、URL エンコーディングする必要があります。エ
ンコーディングにより、等号記号やアンパサンドなど、URL で使用できない文字や URL 内で特別な意味を持つ特殊文字を確実
に送信できます。
PayPal NVP API では、PayPal API サーバーへのリクエストの送信と PayPal API サーバーからのレスポンスの受信に HTTP
プロトコルを使用します。HTTP プロトコルを介して送信されるすべてのデータをエンコーディングする必要があります。この理由とし
て、エンコーディングされていないデータはリクエストの一部ではなく HTTP プロトコルの一部として誤って解釈される可能性がある
ためです。ほとんどのプログラミング言語では、このように文字列のエンコーディングを実行できます。常に API リクエスト全体を
URL エンコーディングする必要があります。このように URL エンコーディングしないと、予期しないデータが原因でエラーが発生する
可能性があります。
注: HTTP 形式は、ほとんどのブラウザで自動的に URL エンコーディングされます。
たとえば、次の NVP 文字列について考えてみましょう。
NAME=Robert Moore&COMPANY=R. H. Moore & Associates
以下のようにエンコーディングされます。
NAME=Robert+Moore&COMPANY=R.+H.+Moore+%26+Associates
NVP 文字列の URL エンコードおよび URL デコードには以下のメソッドを使用します。
表 1. 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])
NVP のリスト構文
PayPal API では、リストとして定義された NVP フィールドに専用の構文が使用されます。
PayPal API への NVP インターフェースの場合は、フィールドごとに一意の名前が必要となります。この API では、リストに L_ と
いうプレフィックスが付加されます。
リスト内の要素を特定するには、リストの先頭からのオフセット(最初の要素が 0 で始まる)を使用します。たとえば、 L_DESC0
は説明の先頭行になり、 L_DESC1 は 2 番目の行になり、以下同様になります。
注: プレフィックス L_ はすべてのリストに付加されるわけではありませんが、すべてのリストの最初の要素は 0 で始まります。
NVP API オペレーションの実行
PayPal NVP API オペレーションを実行するには、HTTPS POST リクエストを PayPal API サーバーに送信するか、cURL ま
たは別のメカニズムを使用して買い手のブラウザと PayPal API サーバー間のセキュアなアクセスを提供します。たとえば、買い手
のブラウザを継続的にマーチャントのサーバーのクライアントにし、マーチャントのサーバーを PayPal API サーバーのクライアントに
するシステムを実装できます。
PayPal サーバーの指定
PayPal API オペレーションを実行するには、リクエストを PayPal API サーバーに送信します。
PayPal NVP API オペレーションを実行する場合は、以下のいずれかのエンドポイントにリクエストを送信します。
サーバーエンドポイント
説明
https://api-3t.sandbox.paypal.com/nvp
API 署名で使用する Sandbox サーバー(API のテストに使用)
https://api-3t.paypal.com/nvp
API 署名で使用する PayPal の実稼働サーバー
https://api.sandbox.paypal.com/nvp
API 証明書で使用する Sandbox サーバー(API のテストに使用)
https://api.paypal.com/nvp
API 証明書で使用する PayPal の実稼働サーバー
注: 各サーバーエンドポイントに対して、異なる API 信用証明書を使用する必要があります。通常は、Sandbox でテストを実
施する場合に一連の API 信用証明書を取得し、実稼働サーバー用に別の一連の API 信用証明書を取得します。実稼働時
に新しい信用証明書を使用するようにそれぞれの API リクエストを変更する必要があります。
API オペレーションのログ作成
実行する各 PayPal API オペレーションのリクエスト/レスポンスメッセージの基本情報を記録してください。PayPal に対する API
オペレーションを識別する相関 ID をレスポンスメッセージから記録し、特定の取引に関するサポートが必要な場合に、この ID を
マーチャントテクニカルサポートに提示する必要があります。
PayPal API オペレーションに対するすべてのレスポンスには、デバッグに役立つ情報が含まれています。レスポンスメッセージから
相関 ID を記録するほか、取引 ID やタイムスタンプなどの情報を記録することで、PayPal のサイトでの取引や API 経由の取
引を確認できます。リクエストとレスポンス全体を「verbose」モードで記録するスキームを実装できますが、リクエストからパスワー
ドを記録しないよう十分注意してください。
NVP レスポンスへの応答
NVP レスポンスには、NVP リクエストに対するレスポンスだけでなく、API オペレーションとそのオペレーションがどのような方法で実
行されたかを示す共通フィールドも含まれています。
PayPal NVP API オペレーションに対するレスポンスに含まれるフィールドを以下の図に示します。
共通のレスポンスフィールド
PayPal API では常に、リクエストされた PayPal API オペレーションに固有のフィールドだけでなく、共通フィールドも返されます。
PayPal API レスポンスに含まれるフィールドを以下に示します。
フィールド
ACK
説明
以下のいずれかの値が示される確認応答ステータス:

Success : オペレーションが正常に実行されたことを示します。

SuccessWithWarning : オペレーションが正常に実行されたことを示します。ただし、調査する
必要のあるメッセージがレスポンスとともに返されます。

Failure : オペレーションが正常に実行されなかったことを示します。問題の内容が示された 1 つ
以上のエラーメッセージが含まれます。

FailureWithWarning : オペレーションが正常に実行されなかったことを示します。また、調査する
必要のあるメッセージがレスポンスとともに返されます。
CORRELATIONID
PayPal との取引を一意に識別する相関 ID。
TIMESTAMP
リクエストされた API オペレーションが実行された日時。
VERSION
API のバージョン。
BUILD
API のサブバージョン。
エラーレスポンス
ACK の値が Success ではない場合、API レスポンスのフィールドは返されない可能性があります。エラーレスポンスは以下の
標準形式を取ります。
表 2. エラーレスポンスの形式
エラ
ーの
レス
ポン
ACK=notSuccess&TIMESTAMP=date/timeOfResponse&
CORRELATIONID=debuggingToken&VERSION=VersionNo&
BUILD=buildNumber&L_ERRORCODE0=errorCode&
複数のエラーが返
される場合があり
ます。各エラーセッ
トには異なる数字
スフ
L_SHORTMESSAGE0=shortMessage& L_LONGMESSAGE0=longMessage&
のサフィックスが付
ィー
L_SEVERITYCODE0=severityCode
きます。この数字
ルド
は、0 から始まり、
エラーごとに 1 ず
つ増えます。
さらにパススルー情報が、 L_ERRORPARAMIDn および L_ERRORPARAMVALUEn フィールドに表示される場合があります。
以下のエラーレスポンスについて考えてみましょう。
TIMESTAMP=2011%2d11%2d15T20%3a27%3a02Z&CORRELATIONID=5be53331d9700&ACK
=Failure&VERSION=78%2e0&BUILD=000000&L_ERRORCODE0=15005&L_SHORTMESSAGE0=
Processor%20Decline&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processe
d%2e&L_SEVERITYCODE0=Error&L_ERRORPARAMID0=ProcessorResponse&L_ERRORPA
RAMVALUE0=0051&AMT=10%2e40&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M
この場合、パラメータ ID は ProcessorResponse です。これはクレジット/デビットカードプロセッサによるエラーレスポンスを示し
ています。値には、プロセッサ固有のエラーが含まれています。これらの値は、PayPal が設定するのではなく、発信元から渡されま
す。
注: PayPal は、 L_ERRORPARAMIDn および L_ERRORPARAMVALUEn フィールドで選択された値を渡すだけです。
URL のデコーディング
PayPal NVP API で使用された HTTP POST オペレーションに対するすべてのレスポンスをデコーディングする必要があります。
PayPal NVP API では、PayPal API サーバーへのリクエストの送信と PayPal API サーバーからのレスポンスの受信に HTTP
プロトコルを使用します。HTTP プロトコルを介して返されたすべてのデータを正しく表示できるようにデコーディングする必要があり
ます。ほとんどのプログラミング言語では、文字列のデコーディングを実行できます。

Download Report