PayPal APIの使い方 その4 〜 定期支払いの実装

「PayPalの使い方 その２ - Express Checkout APIによる課金システムの実装 解説」で作成したExpress Checkoutの実装を変更して定期支払いも試してみたのでまとめてみました。

定期支払いの概要まとめ

定期支払いの概要についてはgihyoのサイトのPayPalの連載記事が参考になります。

「PayPal API導入・活用ガイド - 第3回　定期支払いを実現するリカーリングペイメントの実装」
http://gihyo.jp/dev/serial/01/paypal_api/0003

また、定期支払いはExpress Checkout APIを使わなくても、Subscribeボタンでも実現可能です。
https://www.paypal.com/cgi-bin/webscr?cmd=_pdn_subscr_techview_outside

定期支払いのPayPalの公式ドキュメントはこちら

英語：https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_ECRecurringPayments
日本語:https://cms.paypal.com/jp/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_WPRecurringPayments

定期支払いの流れ

以下の図は、定期支払いの流れを説明した図です(PayPalのドキュメントから引用)。


定期支払いの実装は、Express Checkout APIの呼び出しに加えて定期支払いの各種設定を保存するRecurring Payment Profile(定期支払い個人設定)を作成します。
図の中で、主な処理は以下のようになります。

  1. (1) L_BILLINGTYPE0=RecurringPaymentsプロパティを指定してSetExpressCheckoutを呼ぶ
  2. (3) Tokenを指定してRePayPalにリダイレクト
  3. (4) GetExpressCheckoutDetailsを呼び出して定期支払いプロフィールに指定する情報を取得
  4. (6) 入会金などワンタイムペイメントが必要な場合のみDoExpressCheckoutPaymentで課金
  5. (7) CreateRecurringPaymentsProfileを呼び出して定期支払いプロフィールを作成

今回も説明用のサンプルをGithubにアップしましたので参考にしてください。
https://github.com/hrendoh/PayPal-Recurring-Payment-example

アプリケーションは、前のブログで紹介したExpress Checkoutのサンプルを基に定期支払いの処理を追加しています。

以下、Express Checkoutで定期支払いを開始する際に必要な手順の詳細を解説します。

(1) L_BILLINGTYPE0=RecurringPaymentsプロパティを指定してSetExpressCheckoutを呼ぶ

定期支払いもSetExpressCheckoutでトランザクションを開始します。
提起し払いの際に指定する必要のあるパラメータは以下の通りです。

  1. BILLINGTYPE

「RecurringPayments」を指定します。

  1. BILLINGAGREEMENTDESCRIPTION

BILLINGTYPEごとに説明を指定します。複数指定する場合は、L_BILLINGTYPE0に対してL_BILLINGAGREEMENETDESCRIPTION0、L_BILLINGTYPE1に対してL_BILLINGAGREEMENETDESCRIPTION1というように0-9まで指定できます*1。

  1. 「If there is no associated purchase」ワンタイムペイメントを同時に利用しない場合は、AMT=0を指定とドキュメントには書いてあります。ちなみにAMTを指定しなくても通りました。

ちなみに、パラメータ足りない場合、以下の様なエラーが返されました。「BILLINGAGREEMENTDESCRIPTION」を追加し忘れ。

SetExpressCheckout API call failed. Detailed Error Message: Recurring payments profile description must be provided if the billing agreement type is recurring payments.Short Error Message: Invalid DataError Code: 10478Error Severity Code: Error

正しくパラメータを渡すと、以下のような契約に同意するページが表示されます*2。

「BILLINGAGREEMENTDESCRIPTION」に指定した値が[注文概要]の[説明]に表示されています。
また、定期支払用に[同意して続行]にボタンのラベルが変わっています*3。

GetExpressCheckoutDetailsを呼び出して定期支払いプロフィールに指定する情報を取得

ワンタイムペイメントを含まない場合も、次のCreateRecurringPaymentsProfileに指定するパラメータをGetExpressCheckoutDetailsを呼び出して取得する必要があります。

CreateRecurringPaymentsProfileを呼び出して定期支払いプロフィールを作成

CreateRecurringPaymentsProfileの実行は、PayPalで支払いの場合とクレジットカードでダイレクト決済する場合で指定するパラメータが異なるので注意が必要です。
また、いくつかのパラメータはGetExpressCheckoutDetailsで取得した値を指定する必要があります。

必須パラメータ

  • PROFILESTARTDATE

定期支払いの請求開始日。

  • DESC

SetExpressCheckoutに指定したBILLINGAGREEMENTDESCRIPTIONパラメータと同じ値を指定します。
同じ値じゃないとエラーになるので注意。

  • AMT

各課金の金額

  • CURRENCYCODE

通貨

  • BILLINGPERIOD:課金スケジュールの周期を指定します。
    • Day
    • Week
    • SemiMonth
    • Month
    • Year
  • BILLINGFREQUENCY

ドキュメントの説明が分かりにくい。
BILLINGPERIOD内の請求頻度、BILLINGPERIOD=MonthのときにBILLINGFREQUENCY=5にすると1ヶ月に5回請求される？

以下は、支払方法によって異なる必須パラメータ

  • TOKEN:PayPal支払いの場合、Express CheckoutのTOKENを指定します。また、TOKENを指定する場合は以下のパラメータも必須になります。
    • SHIPTONAME
    • SHIPTOSTREET
    • SHIPTOCITY
    • SHIPTOSTATE
    • SHIPTOZIP
    • SHIPTOCOUNTRY
  • CreditCard:クレジットカードによるダイレクト決済を利用する場合、このときTOKENは省略する。
    • CREDITCARDTYPE
    • ACCT
    • EXPDATE
    • CVV2

ダイレクト決済の例は実際には試していませんので、以下の説明などを参考にしてみてください。
https://www.x.com/blogs/magarvin/2009/12/21/sample-createrecurringpaymentsprofile--direct-payment

作成したPayPal決済のサンプルを実行してPOSTしたパラメータはこのようになります。

METHOD=CreateRecurringPaymentsProfile&VERSION=64&PWD=1308542256&USER=Seller_1308542242_biz_api1.gmail.com&SIGNATURE=A4U73r.r18rhxStXoULiMg6K9OGOAuMapjAYMHD5UPtAMTjgTgK5VKnK&TOKEN=EC-99H66270JP9985642&SHIPTONAME=Test+User&SHIPTOSTREET=Nishi+4-chome%2C+Kita+55-jo%2C+Kita-ku&SHIPTOCITY=Shibuya-ku&SHIPTOSTATE=Tokyo&SHIPTOZIP=150-0002&SHIPTOCOUNTRY=JP&PROFILESTARTDATE=2011-07-01T0%3A0%3A0&DESC=Test+Recurring+Payment%28%241+monthly%29&BILLINGPERIOD=Month&BILLINGFREQUENCY=5&AMT=1&CURRENCYCODE=USD&IPADDRESS=::1&BUTTONSOURCE=PP-ECWizard

CreateRecurringPaymentsProfileメソッドは応答に「PROFILEID」を返します。定期支払いプロフィールの情報を後から参照する際に必要となるので値はアプリケーション側で保持しておく必要があります。

マイアカウントページで定期支払いを確認

定期支払いを契約すると、その情報は購入者のマイアカウントの概要で確認することができます。

詳細を開くとこんな感じ

プロフィール情報の参照

実際にサービスを提供する際には、定期支払いプロフィールのステータスが有効かどうかを定期的にチェックする必要があります。
最後に、定期支払いプロフィールステータスを確認するメソッドについて簡単にまとめておきます。

GetRecurringPaymentsProfileDetails

定期払いプロフィール情報を取得します。CreateRecurringPaymentsProfileを実行して取得した「PROFILEID」をパラメータに指定します。

ManageRecurringPaymentsProfileStatus

定期払いのキャンセル、一時停止、再開を実行します。
CreateRecurringPaymentsProfileを実行して取得した「PROFILEID」と以下の「ACTION」が必須パラメータです。

  • Cancel: 有効または一時停止状態の設定のみをキャンセル
  • Suspend: 有効状態の設定のみを一時停止
  • Reactivate: 一時停止状態の設定のみを利用再開
UpdateRecurringPaymentsProfile

定期払いプロフィール情報を更新します。未払いの対応はこのメソッドで行います。

*1:1つの場合は「L_」と「n」は不要です。L_はリストの略？

*2:これはSandboxのページなので実際のページとは異なるかもしれません

*3:リファレンストランザクションの時と同じ