paypal-logo

前回に引き続き、PayPal(ペイパル)のAPIを利用した決済が可能となるエクスプレスチェックアウトについて説明します。

エクスプレスチェックアウトの処理の流れ

エクスプレスチェックアウトでは、状況に応じて3つのAPIを呼び出して決済を行います。

API名 説明
SetExpressCheckout エクスプレスチェックアウト取引を開始する
GetExpressCheckoutDetails エクスプレスチェックアウト取引に関する情報を取得する
DoExpressCheckoutPayment エクスプレスチェックアウト取引を完了する

expresscheckout

ECサイトの画面と、PayPal APIを呼び出す処理は自作する必要がありますが、PayPalサイトの画面は既に用意されているため作成する必要はありません。

エクスプレスチェックアウトの決済手順

では、もう少し詳しく決済の手順を見ていきましょう。

注意事項

APIは『KEY=VALUE』のNVP(Name-Value Pair)形式で指定しています
API、PayPalサイトの接続先はSandbox用のURLを使用しています
リクエスト、レスポンス情報は実際にはエンコードされています

① 商品購入画面

商品を購入する(決済)のために必要な商品名や商品価格、個数などをここで決定します。PayPal決済を開始するための購入ボタンも作成しておきましょう。

SetExpressCheckout API 呼び出し

SetExpressCheckout API を呼び出してエクスプレスチェックアウトの取引を開始します。リファレンスはこちら

リクエスト

https://api-3t.sandbox.paypal.com/nvp?METHOD=SetExpressCheckout&VERSION=93&USER=APIユーザ名&PWD=APIパスワード&SIGNATURE=署名&RETURNURL=決済内容同意時の遷移先URL&CANCELURL=キャンセル時の遷移先URL&L_PAYMENTREQUEST_0_AMT0=100.0&L_PAYMENTREQUEST_0_NAME0=バナナ&L_PAYMENTREQUEST_0_QTY0=1&L_PAYMENTREQUEST_0_TAXAMT0=8.00&L_PAYMENTREQUEST_0_ITEMCATEGORY0=Digital&EMAIL=購入者のアカウント名&PAYMENTREQUEST_0_PAYMENTACTION=Sale&PAYMENTREQUEST_0_CURRENCYCODE=JPY&PAYMENTREQUEST_0_AMT=108&PAYMENTREQUEST_0_ITEMAMT=100.0&PAYMENTREQUEST_0_TAXAMT=8.00&REQCONFIRMSHIPPING=0&NOSHIPPING=1&ALLOWNOTE=0&SOLUTIONTYPE=Mark&PAGESTYLE=スタイル名
【リクエストパラメータ】
フィールド 説明 必須
METHOD API名を指定
VERSION PayPal APIのバージョン番号を指定。API名とバージョン番号の組み合わせによって動作が決定される
USER クレデンシャル情報のAPIユーザ名
PWD クレデンシャル情報のAPIパスワード
SIGNATURE クレデンシャル情報の署名
RETURNURL 支払いに同意した際に遷移するURL
CANCELURL 支払いをキャンセルした際に遷移するURL
L_PAYMENTREQUEST_n_AMTm 商品の原価 ×
L_PAYMENTREQUEST_n_NAMEm 商品名 ×
L_PAYMENTREQUEST_n_QTYm 商品の個数 ×
L_PAYMENTREQUEST_n_TAXAMTm 商品の消費税 ×
PAYMENTREQUEST_n_PAYMENTACTION 支払いの取得方法。支払いを即時完了するか、売り手の商品を必要とするか ×
PAYMENTREQUEST_n_CURRENCYCODE 通貨コード。日本の場合は「JPY」を指定 ×
PAYMENTREQUEST_n_AMT 商品の配送料や消費税を含めた合計費用
PAYMENTREQUEST_n_ITEMAMT 注文に含まれるすべての商品の費用
PAYMENTREQUEST_n_TAXAMT 注文に含まれるすべての商品の合計税額 ×
EMAIL 購入者のPayPalアカウント ×

n には「支払い回数」、m には「品目」を 0 から順に指定します

RETURNURLにはECサイトの購入確認画面のURLを指定しましょう。購入する商品の総額だけでも決済可能ですが、商品ごとの原価や個数、商品名等を細かく指定しておくと、PayPalサイトで内訳が表示されます。一度の決済で複数の商品を指定する場合は以下のように記述します。

L_PAYMENTREQUEST_0_AMT0=150.0
L_PAYMENTREQUEST_0_NAME0=バナナ
L_PAYMENTREQUEST_0_QTY0=1
L_PAYMENTREQUEST_0_TAXAMT0=8.00
L_PAYMENTREQUEST_0_AMT1=120.0
L_PAYMENTREQUEST_0_NAME1=りんご
L_PAYMENTREQUEST_0_QTY1=4
L_PAYMENTREQUEST_0_TAXAMT1=8.00

商品の種類や決済方法に応じて指定するパラメータの追加も必要となります。
例えば、商品を発送する必要のないデジタルコンテンツの場合、以下のパラメータを追加します。

【デジタルコンテンツに必要なパラメータ】
パラメータ 説明
L_PAYMENTREQUEST_0_ITEMCATEGORY0=Digital 商品の発送は不要なので「Digital」を指定
REQCONFIRMSHIPPING=0 購入者の配送先住所と PayPal に登録済みの住所が一致するか確認不要なので「0」を指定
NOSHIPPING=1 PayPal サイトに配送先住所を表示しないので「1」を指定

レスポンス

TOKEN=EC-XXXXXXXXXX&TIMESTAMP=2014-10-10T11:12:42Z&CORRELATIONID=b2220b38a5117amp;ACK=Success&VERSION=93&BUILD=13637230

SetExpressCheckout APIを呼び出すとレスポンス情報が返却されます。
成功時はTokenが取得でき、GetExpressCheckoutDetails APIおよび、DoExpressCheckoutPayment APIを呼び出すために必要となります。

PayPal APIのレスポンス情報には共通して「ACK」フィールドが含まれており、この値を確認することで、APIの成功 or 失敗を判断することができます。

【ACK応答ステータス】
ステータス 説明
Success オペレーションが正常に実行されたことを示す
SuccessWithWarning オペレーションが正常に実行されたが、調査が必要であることを伝える警告メッセージが返却される
PartialSuccess 一部の支払いは正常に処理されたものの、残りの支払い処理が失敗したことを示す
Failure オペレーションが正常に実行されなかった。失敗の理由を示すエラーメッセージがレスポンスに表示される
FailureWithWarning オペレーションが正常に実行されなかったことを示し、調査が必要であることを伝えるメッセージが返却される

③ PayPalサイトにリダイレクト

https://www.sandbox.paypal.com/jp/cgi-bin/webscr?cmd=_express-checkout&token=EC-XXXXXXXXXX

レスポンス情報で取得したTokenを付加してPayPalサイトにリダイレクトします。

④ PayPalアカウントでログイン

Tokenが有効な場合は、PayPalサイトのログイン画面が表示されます。この画面はあらかじめ用意されたものが表示されているので、作成する必要はありません。注文の明細には、SetExpressCheckout APIで渡した商品の情報が表示されます。PayPalアカウントを入力してログインすると、決済内容の確認画面に遷移します。

expresscheckout1

⑤ 決済内容に同意する

PayPalサイトの支払確認画面が表示されます。この画面も作成する必要はありません。「続行」または「同意して続行」ボタンをクリックすると、「RETURNURL」フィールドで指定したURLに遷移します。キャンセルすると、「CANCELURL」フィールドで指定したURLに遷移します。決済を続けるために同意しましょう。

expresscheckout2

⑥ 購入確認画面

PayPalサイトから復帰する画面になります。購入確認画面も自作しましょう。GetExpressCheckoutDetail APIを呼び出して取得した決済内容を表示し、決済の最終的な確認を取ります。

GetExpressCheckoutDetails API 呼び出し

Tokenを付加してGetExpressCheckoutDetails APIを呼び出し、決済内容を取得します。リファレンスはこちら

リクエスト

https://api-3t.sandbox.paypal.com/nvp?METHOD=GetExpressCheckoutDetails&VERSION=93&USER=XXXXXXXXXX&PWD=XXXXXXXXXX&SIGNATURE=XXXXXXXXXX&TOKEN=EC-XXXXXXXXXX

レスポンス

TOKEN=EC-XXXXXXXXXX&BILLINGAGREEMENTACCEPTEDSTATUS=0&CHECKOUTSTATUS=PaymentActionNotInitiated&TIMESTAMP=2014-10-10T11:13:50Z&CORRELATIONID=b2220b38a5117&ACK=Success&VERSION=93&BUILD=13630372&EMAIL=buyer@piyo.jp&PAYERID=XXXXXXXXXX&PAYERSTATUS=verified&FIRSTNAME=Taro&LASTNAME=Yamada&COUNTRYCODE=JP&CURRENCYCODE=JPY&AMT=108&ITEMAMT=100&SHIPPINGAMT=0&HANDLINGAMT=0&TAXAMT=8&INSURANCEAMT=0&SHIPDISCAMT=0&L_NAME0=バナナ&L_QTY0=1&L_TAXAMT0=8&L_AMT0=100&L_ITEMWEIGHTVALUE0=0.00000&L_ITEMLENGTHVALUE0=0.00000&L_ITEMWIDTHVALUE0=0.00000&L_ITEMHEIGHTVALUE0=0.00000&L_ITEMCATEGORY0=Digital&PAYMENTREQUEST_0_CURRENCYCODE=JPY&PAYMENTREQUEST_0_AMT=108&PAYMENTREQUEST_0_ITEMAMT=100&PAYMENTREQUEST_0_SHIPPINGAMT=0&PAYMENTREQUEST_0_HANDLINGAMT=0&PAYMENTREQUEST_0_TAXAMT=8&PAYMENTREQUEST_0_INSURANCEAMT=0&PAYMENTREQUEST_0_SHIPDISCAMT=0&PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED=false&L_PAYMENTREQUEST_0_NAME0=バナナ&L_PAYMENTREQUEST_0_QTY0=1&L_PAYMENTREQUEST_0_TAXAMT0=8&L_PAYMENTREQUEST_0_AMT0=100&L_PAYMENTREQUEST_0_ITEMWEIGHTVALUE0=0.00000&L_PAYMENTREQUEST_0_ITEMLENGTHVALUE0=0.00000&L_PAYMENTREQUEST_0_ITEMWIDTHVALUE0=0.00000&L_PAYMENTREQUEST_0_ITEMHEIGHTVALUE0=0.00000&L_PAYMENTREQUEST_0_ITEMCATEGORY0=Digital&PAYMENTREQUESTINFO_0_ERRORCODE=0

SetExpressCheckout APIで指定した情報を含め、決済に関するレスポンス情報が返却されます。注意する点として、「ACK」フィールドを確認するとともに「PAYERSTATUS」フィールドの値も確認しましょう。

【PAYERSTATUS 購入者ステータス】
ステータス 説明
Verified PayPalアカウント認証済み。商品の購入が可能
Unverified PayPalアカウント未認証。商品を購入することができない

⑧ 購入を完了するボタンをクリック

購入確認画面ではPayPal決済を完了するためのボタンを作成しておきましょう。このボタンをクリックすると決済完了処理を行います。

DoExpressCheckoutPayment API 呼び出し

Tokenを付加してDoExpressCheckoutPayment APIを呼び出し、決済を完了します。リファレンスはこちら

リクエスト

https://api-3t.sandbox.paypal.com/nvp?METHOD=DoExpressCheckoutPayment&VERSION=93&USER=XXXXXXXXXX&PWD=XXXXXXXXXX&SIGNATURE=XXXXXXXXXX&TOKEN=EC-XXXXXXXXXX&PAYERID=XXXXXXXXXX&PAYMENTREQUEST_0_ITEMAMT=100&PAYMENTREQUEST_0_TAXAMT=8&PAYMENTREQUEST_0_AMT=108&PAYMENTREQUEST_0_PAYMENTACTION=Sale&PAYMENTREQUEST_0_CURRENCYCODE=JPY

レスポンス

TOKEN=EC-XXXXXXXXXX&SUCCESSPAGEREDIRECTREQUESTED=false&TIMESTAMP=2014-10-10T11:15:08Z&CORRELATIONID=b2220b38a5117&ACK=Success&VERSION=93&BUILD=13630372&INSURANCEOPTIONSELECTED=false&SHIPPINGOPTIONISDEFAULT=false&PAYMENTINFO_0_TRANSACTIONID=XXXXXXXXXX&PAYMENTINFO_0_TRANSACTIONTYPE=expresscheckout&PAYMENTINFO_0_PAYMENTTYPE=instant&PAYMENTINFO_0_ORDERTIME=2014-10-10T11:15:08Z&PAYMENTINFO_0_AMT=108&PAYMENTINFO_0_FEEAMT=44&PAYMENTINFO_0_TAXAMT=8&PAYMENTINFO_0_CURRENCYCODE=JPY&PAYMENTINFO_0_PAYMENTSTATUS=Completed&PAYMENTINFO_0_PENDINGREASON=None&PAYMENTINFO_0_REASONCODE=None&PAYMENTINFO_0_PROTECTIONELIGIBILITY=Ineligible&PAYMENTINFO_0_PROTECTIONELIGIBILITYTYPE=None&PAYMENTINFO_0_SECUREMERCHANTACCOUNTID=XXXXXXXXXX&PAYMENTINFO_0_ERRORCODE=0&PAYMENTINFO_0_ACK=Success

決済処理の実行結果を含めたレスポンス情報が返却されます。「ACK」フィールドを確認するとともに、商品別の支払い詳細情報の内容を確認しましょう。

【支払い処理詳細情報】
ステータス 説明
PAYMENTINFO_n_TRANSACTIONID 一意の取引ID
PAYMENTINFO_n_TRANSACTIONTYPE 取引タイプ。エクスプレスチェックアウト取引かどうかなど
PAYMENTINFO_n_PAYMENTTYPE 支払いタイプ。即時支払い or 遅延決済
PAYMENTINFO_n_ORDERTIME 支払いの日時
PAYMENTINFO_n_AMT 配送料や税金を含んだ最終的な請求金額
PAYMENTINFO_n_FEEAMT 取引に課されるPayPalの手数料
PAYMENTINFO_n_TAXAMT 取引に課される税金
PAYMENTINFO_n_CURRENCYCODE 通貨コード
PAYMENTINFO_n_PAYMENTSTATUS 支払いステータス。支払いが完了していれば「Completed」、未決済の場合は「Pending」など
PAYMENTINFO_n_PENDINGREASON 未決済になっている場合の理由
PAYMENTINFO_n_ACK 支払い処理別の結果

n には 0 から始まる「支払い件数」がはいります

⑩ 購入完了画面に遷移

最後に決済処理の結果を出力する完了画面を表示しておしまいです。

エラーレスポンス

レスポンス情報に含まれる「ACK」フィールドの値がSuccess以外の場合、何らかのエラーが発生している可能性があります。エラーが発生していた場合は、レスポンス情報に含まれているエラーコードとエラーメッセージを解析して原因を突き止めましょう。一度に複数のエラーが返却される場合もあります。

レスポンス

TIMESTAMP=2014-10-11T00:36:07Z&CORRELATIONID=47a3b8314fa93&ACK=Failure&VERSION=93&BUILD=13630372&L_ERRORCODE0=10411&L_SHORTMESSAGE0=This Express Checkout session has expired.&L_LONGMESSAGE0=This Express Checkout session has expired.  Token value is no longer valid.&L_SEVERITYCODE0=Error
【エラーレスポンス】
フィールド 説明
L_ERRORCODEn API エラーコード
L_SHORTMESSAGEn エラーコードに関する短めのエラーメッセージ
L_LONGMESSAGEn エラーコードに関する長めのエラーメッセージ
L_SEVERITYCODEn エラーの程度を表す。Error / Warningなど

n には 0 から始まる「エラー数」がはいります

エラーコード表はこちら

日本語マニュアル

PayPal関連の日本語の文書も公開されていますが、APIのバージョンが古いので注意が必要です。

まとめ

どうでしょう?エクスプレスチェックアウトの使用方法についてなんとなくイメージできたでしょうか。次回はサンプルコードの作成方法などを紹介できたらと思います。

PayPal APIについて調べてみた その3へ

ではでは