定期支払の実装方法

PayPal画面にて定期支払いへの同意を取得し、定期支払を実現する方法です。
SetExpressCheckout APIの”L_BILLINGTYPE0”に“RecurringPayments”を、
”L_BILLINGAGREEMENTDESCRIPTION0”に定期支払いに関する説明文(日本語可能)を指定することで実現します。

サンプルリクエスト

curl -v https://api-3t.sandbox.paypal.com/nvp -d
  "USER={YourUserID}
  &PWD={YourPassword}
  &SIGNATURE={YourSignature}
  &METHOD=SetExpressCheckout
  &VERSION=124
  &cancelUrl=http://your.cancel.url/
  &returnUrl=http://your.return.url/
  &L_BILLINGTYPE0=RecurringPayments
 &L_BILLINGAGREEMENTDESCRIPTION0=定期支払
                            

SetExpressCheckoutで取得したTokenを使って、CreateRecurringPaymentProfile APIを呼び出すことで定期支払い設定(開始日時や請求サイクルの設定)の作成を行います。以後作成された設定を元にPayPalが定期決済を実行します。

サンプルリクエスト

curl -v https://api-3t.sandbox.paypal.com/nvp -d
  "USER={YourUserID}
  &PWD={YourPassword}
  &SIGNATURE={YourSignature}
  &METHOD=CreateRecurringPaymentsProfile
  &VERSION=124
  &TOKEN=EC-8HE824118B312064U
  &PROFILESTARTDATE=2016-01-01T00:00:00Z
  &AMT=1000
  &BILLINGPERIOD=Day
  &BILLINGFREQUENCY=1
  &DESC=定期支払
                            

DESCはL_BILLINGAGREEMENTDESCRIPTION0と同じものを指定します。

CreateRecurringPaymentProfile APIによる定期支払いの実現

CreateRecurringPaymentProfileで作成された設定によってPayPalが毎月の決済を行います。決済結果はエラーを含め即時支払い通知(IPN)で指定されたURLへ送信されます。

定期支払いフロー

定期決済でエラーがおきた場合は、PayPalは予定日から、5日後、10日後に計2回リトライします。
リトライしても決済できなかった場合は、その決済はエラーとみなされます。決済がエラーとなった場合に、定期支払いを停止したり、次の定期決済に繰り越すなどの指定をすることができます。

  • 無料期間の設定

定期支払いの設定内容に無料(試用)期間のオプションがありますが、APIで実装する場合は、実装が簡単で運用しやすい開始日時を無料期間後に設定する方法を推奨します。

IPNによる定期支払い結果の取得

定期支払いが実行されると、PayPal管理画面([アカウント設定]-> [プロフィール設定]-> [販売ツール]->[即時支払い通知])で指定したURLにその結果は通知されます。決済金額の確認やエラー時の対応を行う際に利用できます。

PayPalのIPN設定と履歴画面

IPNの処理概要

IPNの詳細については以下を ご参照ください。

https://developer.paypal.com/docs/classic/ipn/integration-guide/IPNIntro/

ManageRecurringPaymentsProfileStatus APIによる定期支払いの停止

定期支払いは、PayPalの管理画面から停止することもできますが、APIによって停止することも可能です。会員サイトでの解約操作と連動して定期支払いを止める場合は、APIによる停止を推奨します。

支払い者がPayPal管理画面で定期支払いを停止した場合の対応

支払い者がPayPalの管理画面で定期支払いを無効にした場合も決済されなくなります。この場合も無効にされたタイミングでIPNによる通知がされるので会員サイトの無効化の実装も可能です。

定期支払いエラー時リカバリ

定期支払いのエラーはIPNによって通知されます。IPNの項目のpayment_statusが“Completed”以外の場合は支払いが完了していないので、他の項目内容を確認し適宜対応をしてください。

payment_cycle=Daily&txn_type=recurring_payment_failed&last_name=test&next_payment_date=03:00:00 Aug 26, 2015 PDT&residence_country=JP&
initial_payment_amount=0.00&currency_code=USD&time_created=23:48:26 May 21, 2015 PDT&
verify_sign=AmrZscqAufOBlvUqnx80IjZKdPlyAzkmVnvr-RpGiPLppxjeZfvC6.ou&period_type= Regular&payer_status=unverified&test_ipn=1&tax=0.00&
payer_email=hogehoge+P0522@gmail.com&first_name=test&receiver_email=hogehoge+B@gmail.com&payer_id=RVFDEMDQ9WA7G&product_type=1&shipping=0.00&
amount_per_cycle=102.00&profile_status=Active&charset=UTF-8¬ify_version=3.8&amount=102.00&outstanding_balance=9690.00&
recurring_payment_id=I-GR2J9UD2PAK3&product_name=MY_RECURRSIVE_PAYMENT_102&ipn_track_id=cddc113ab08fb
                            

定期支払いエラーのIPN例:

決済エラー時のIPNはそれぞれ以下のようなtxn_typeになります。

予定日の失敗: txn_type=recurring_payment_skipped

リトライ1回目: txn_type=recurring_payment_skipped

リトライ2回目: txn_type=recurring_payment_failed

支払い者側での停止: txn_type=recurring_payment_profile_cancel

定期支払については、API仕様書一覧の応用機能ガイドも参照ください。