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 エンコード System.Web.HttpUtility.UrlEncode(buffer, Encoding.Default) デコード System.Web.HttpUtility.UrlDecode(buffer, Encoding.Default) Classic ASP エンコード Server.URLEncode デコード 組込関数なし インターネットで いくつかの実装例を見ることができます Java エンコード java.net.urlencoder.encode デコード java.net.urldecoder.decode PHP エンコード urlencode() デコード urldecode() ColdFusion エンコード 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 プロトコルを介して返されたすべてのデータを正しく表示できるようにデコーディングする必要があります ほとんどのプログラミング言語では 文字列のデコーディングを実行できます