PayPal APIの使い方 その3 〜Express Checkoutを利用したリファレンストランザクションの実装
前回は「PayPalの使い方 その２ - Express Checkout APIによる課金システムの実装 解説」でExpress Checkout APIの実装について解説しました。
今回は、説明したExpress Checkout APIの応用で、リファレンストランザクションについて調査したのでまとめてみます。
リファレンストランザクションとは
リファレンストランザクションとは、携帯電話など月ごとに支払い額が変わる場合に利用する決済ソリューションです。
クレジットカードと同様に、購入者が同意後はサイトが決めた金額を請求することができるようになります。
PayPal公式の解説
https://cms.paypal.com/jp/cgi-bin/marketingweb?cmd=_render-content&content_ID=marketing_jp/ReferenceTransactions
APIのドキュメントはこちら
https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_LRD_RefTrns.pdf
リファレンストランザクションを利用するには、PayPalからリファレンストランザクション利用の承認を受ける必要があります。
申請に必要な提出書類は、会社の2年間の財務諸表やサイトの課金ポリシーなどがあります。
一般的には書類を用意してから2,3週間で承認が降りるようです。
また、sandboxアカウントでもデフォルトではリファレンストランザクションを試すことは出来ませんが、
フォーラムなどに、sandboxのビジネスアカウントでリファレンストランザクションが使えるようにしてください、と書き込むとPayPalの方が有効にしてくれます。
以降、実装について説明していきます。説明の中でふれていますが、Express Checkoutを利用したリファレンストランザクションではいくつか不明な点が残ってしまいました。
今後、本家に質問をしたりして解決した際には、追記していきたいと思いますので少々お待ちください。
リファレンストランザクションの流れ
リファレンストランザクションで課金を実行するのはDoReferenceTransactionメソッドですが、これを利用するためにBillingAgreementIdを取得する必要があります。
このBillingAgreemenetIDを取得する場合も、これまでに説明したExpress Checkoutの流れで実装します。
もう一つはSetCustomerBillingAgreementメソッドで開始されるトランザクションを利用する方法がありましたが、現在のバージョンでは使えません。
実際に試してみるとPayPalにリダイレクトしたところで「You have requested an outdated version of PayPal. This error often results from the use of bookmarks.」というエラーメッセージが表示されました。
Express Checkoutの流れは以下の図のようになります。
図に沿って主な処理について説明していきます。
(番号)は図に対応しています。
- (1) BILLINGTYPE=MerchantInitiatedBillingを指定してSetExpressCheckoutを実行
- (3) Tokenを指定してRePayPalにリダイレクト
- (5) DoExpressCheckoutPaymentを実行してBillingAgreementIDを取得
- BillingAgreementIDを指定してDoReferenceTransactionを実行
(1)BILLINGTYPE=MerchantInitiatedBillingを指定してSetExpressCheckoutを実行
リファレンストランザクションを開始するにはBILLINGTYPEとBILLINGAGREEMENTDESCRIPTIONが必須パラメータとなります。
BILLINGTYPE(必須)
「MerchantInitiatedBilling」を指定します。
BILLINGAGREEMENTDESCRIPTION(オプション)
商品またはサービスの説明を指定します。
BILLINGAGREEMENTCUSTOM(オプション)
アプリケーションで利用可能な属性情報を保持できるようです。
PAYMENTTYPE(オプション)
「Specifies type of PayPal payment you require for the billing
agreement, which is one of the following values.」
「Any」または「InstantOnly」を指定するらしいですが調べても分かりませんでした。オプションなのでいいか。
(5)DoExpressCheckoutPaymentを実行してBillingAgreementIDを取得
PayPalの画面にてリファレンストランザクションが承認された後、アプリケーションの画面に戻りDoExpressCheckoutメソッドを実行してBillingAgreementIdを取得します。
以下は、実際にDoExpressCheckoutを実行した際のレスポンスです。
array(18) { ["BILLINGAGREEMENTID"]=> string(19) "B-1WF45337P00142631" ["TIMESTAMP"]=> string(20) "2011-06-21T01:46:28Z" ["CORRELATIONID"]=> string(12) "567e639c798b" ["ACK"]=> string(7) "Success" ["VERSION"]=> string(2) "64" ["BUILD"]=> string(7) "1863577" ["TRANSACTIONID"]=> string(17) "1R4545627Y569194G" ["TRANSACTIONTYPE"]=> string(9) "merchtpmt" ["PAYMENTTYPE"]=> string(7) "instant" ["ORDERTIME"]=> string(20) "2011-06-21T01:46:27Z" ["AMT"]=> string(5) "30.00" ["FEEAMT"]=> string(4) "1.47" ["TAXAMT"]=> string(4) "0.00" ["CURRENCYCODE"]=> string(3) "USD" ["PAYMENTSTATUS"]=> string(7) "Pending" ["PENDINGREASON"]=> string(13) "paymentreview" ["REASONCODE"]=> string(4) "None" ["PROTECTIONELIGIBILITY"]=> string(10) "Ineligible" }
レスポンスのパラメータに「BILLINGAGREEMENTID」が含まれています(リファレンストランザクションの利用が向こうの場合は同じパラメータを指定して実行しても「BILLINGAGREEMENTID」は返ってきません)。
Express Checkoutを利用してリファレンストランザクションを開始する際に気をつけることは、AMTを0にできないことです。
https://www.x.com/message/170065;jsessionid=59B55B4ABB71108C5060D0E942144B1F.node0
フォーラムによるとカードが有効かどうかチェックするために必要とのことですが、定期支払いでは契約時に請求が無い場合はAMT=0を指定すると書いてあるのに不思議な仕様です。
とりあえず、PAYMENTACTION=Authorizationにして適当にAMTを指定するなどで回避するしかなさそうです。
BillingAgreementIDを指定してDoReferenceTransactionを実行
BillingAgreementIdを取得すると、DoReferenceTransactionを実行して課金することが可能となります。
DoReferenceTransactionに指定するパラメータのうち必須のものは「REFERENCEID」と「AMT」だけです。
REFERENCEID
BillingAgreemenetIdを指定します。
AMT
合計金額を指定します。
CURRENCYCODE
通貨をしています。オプションですが、デフォルトはUSDなので通常はJPYを指定すると思います。
サンプルアプリケーション
今回も実際に試したサンプルアプリケーションをGithubにアップしました。前回のIntegration Wizardを使って作成したExpress Checkoutのサンプルを元にしています。
まだとりあえずな感じですが、参考にしてみてください。
https://github.com/hrendoh/PayPal-Reference-Transaction-example
参考
APIの呼び出し方流れなどが載っているページを挙げておきます。
公式ブログの解説その１: https://www.x.com/blogs/Nate/2011/02/23/express-checkout-with-reference-transactions
公式ブログの解説その２: https://www.x.com/blogs/magarvin/2010/04/20/reference-transaction-with-paypal-express-checkout-paypal-api
DoReferenceTransaction APIリファレンスの解説: https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_nvp_r_DoReferenceTransaction
支払いの停止について:https://cms.paypal.com/jp/cgi-bin/?cmd=_render-content&content_ID=ua/RecurringPymts_full&locale.x=ja_JP
