PayPal

PayPal 定期支払いの実装方法

定期支払いとは、予め定めた金額を予め定めた周期/期間で定期的に決済する機能です。
毎回の決済時には買い手は決済操作をする必要がありません。

定期支払いはかんたん決済ボタンでAPIを使わず導入することもできますが、ここではREST APIを使った実装方法について説明します。

REST APIの実装方法(各API共通部分)

APIエンドポイント
Sandbox:
https://api.sandbox.paypal.com

本番環境:
https://api.paypal.com

1. アプリケーションを登録する

PayPal REST API を利用するにはまずアプリケーションを登録する必要があります。アプリケーションの登録方法は以下です。

  1. https://developer.paypal.com/developer/applications に移動しPayPalにログインし、REST API appsの「create App」ボタンを押します。

  2. 「AppName」と「Sandbox Developer Account」を設定し、「Create App」ボタンを押します。

  3. 作成したAppのリンクをクリックし、右上の「Live」ボタンをクリックすると必要なClient IDとsecretが表示されます。(Sandboxを使う場合は、「sandbox」に表示されているものを使います)
    image.png

詳細は以下を参照してください。
https://developer.paypal.com/docs/integration/direct/make-your-first-call/#create-a-paypal-app

2. アクセストークンを取得する

アプリケーションに設定された情報(Client IDとsecret)を使って以下のようにアクセストークンを生成します。

サンプルリクエスト

curl -v https ://api.sandbox.paypal.com/v1/oauth2/token \
-H "Accept: application/json" \
-H "Accept-Language: ja_JP" \
-u "<Client ID>:<secret>" \
-d "grant_type=client_credentials"

レスポンス

{
"scope":"https ://api.paypal.com/v1/payments/.* https ://api.paypal.com/v1/vault/credit-card https ://api.paypal.com/v1/vault/credit-card/.*",
"access_token":"<Access-Token>",
"token_type":"Bearer",
"app_id":"APP-6XR95014SS315863X",
"expires_in":28800
}

<Access-Token>の部分がアクセストークンです。
詳細は以下をご参照ください。
https://developer.paypal.com/docs/integration/direct/make-your-first-call/#get-an-access-token

3. リクエストヘッダを設定する

生成したアクセストークンを含んだリクエストヘッダを生成し、各REST APIをコールします。

サンプルリクエスト

curl -v https ://api.sandbox.paypal.com/v1/各APIのパス \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{パラメータJSON

詳細は以下をご参照ください。
https://developer.paypal.com/docs/integration/direct/make-your-first-call/#make-an-api-call

GETパラメータによるレスポンスのコントロール

GETによる参照系のAPIは、取得開始のIDや日付、ソート順などをGETパラメータによって指定できます。

サンプルリクエスト

curl -v -X GET https ://api.sandbox.paypal.com/v1/payments/payment?sort_order=asc&sort_by=update_time \
-H Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"

詳細は以下をご参照ください。
https://developer.paypal.com/docs/api/overview/#paging-and-filtering

HATEOAS LINKs

REST APIのレスポンスには、関連するAPIオペレーション(例えば決済の実行についてはその決済情報の参照や返金など)を実行するためのREST APIのURIが含まれます。
これはHATEOAS LINKsと呼ばれ、これらのリンクにアクセスすることで関連する操作を行うことができ、実装コストやドキュメント参照コストを軽減することができます。

レスポンスサンプル

"links": [{
   "href" : "https ://api.sandbox.paypal.com/v1/payments/payment/PAY-2XR800907F429382MKEBWOSA",
   "rel" : "self",
   "method" : "GET",
}, {
   "href" : 

Webhookの登録

REST APIによるオペレーションの結果はWebhookを登録することで通知可能になります。WEebhookの登録方法は以下です。

  1. https://developer.paypal.com/developer/applications/ に移動し、登録しているアプリケーションをクリックし、編集画面を開きます。

  2. 「Add Webhook」を押し、通知先のURLと取得したいイベントにチェックをし、「Save」を押します。
    image.png

  3. 該当のイベントがREST APIの実行によって発生すると、上記で指定したURLにHTTP POSTでデータが送られます。

※定期支払いの場合、決済はPayPalがバッチ処理で行うので運用にはなんらかの通知が必要となります。

サンプルデータ

{
  "id": "WH-8PT597110X687430LKGECATA",
  "create_time": "2013-06-25T21:41:28Z",
  "resource_type": "authorization",
  "event_type": "PAYMENT.AUTHORIZATION.CREATED",
  "resource": {
    "id": "2DC87612EK520411B",
    "create_time": "2013-06-25T21:39:15Z",
    "update_time": "2013-06-25T21:39:17Z",
    "state": "authorized",
    "amount": {
      "total": "7.47",
      "currency": "USD",
      "details": {
        "subtotal": "7.47"
      }
    },
    "parent_payment": "PAY-36246664YD343335CKHFA4AY",
    "valid_until": "2013-07-24T21:39:15Z",
    "links": [
      {
        "href": "http s://api.paypal.com/v1/payments/authorization/2DC87612EK520411B",
        "rel": "self",
        "method": "GET"
      },
      {
        "href": "https ://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
        "rel": "capture",
        "method": "POST"
      },
      {
        "href": "https ://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
        "rel": "void",
        "method": "POST"
      },
      {
        "href": "https ://api.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
        "rel": "parent_payment",
        "method": "GET"
      }
    ]
  },
  "links": [
    {
      "href": "https ://api.paypal.com/v1/notfications/webhooks-events/WH-8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https ://api.paypal.com/v1/notfications/webhooks-events/WH-8PT597110X687430LKGECATA/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

WebhookはWebhook APIによってAPIで動的に登録、変更、削除することもできます。詳細は以下をご参照ください。
https://developer.paypal.com/docs/integration/direct/rest-webhooks-overview/

定期支払い用のAPI実装方法

上記を行った上で定期支払いを実現するためのAPIを実装します。

手順は以下となります。

  1. Billing Plan(いくらの金額をどのタイミングで課金するかなど)を作成します。 https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/#create-a-plan
  2. Planを有効化します。 https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/#activate-a-plan
  3. Billing Agreement(Planに対する同意情報)を作成します。 https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/#create-an-agreement
  4. 支払い者をPayPal決済画面に誘導してAgreementに承認してもらいます。 https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/#get-customer-approval
  5. Agreementを実行(定期支払いが開始できる状態)します。 https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/#execute-an-agreement

全ての情報は以下を参照してください。
https://developer.paypal.com/docs/integration/direct/billing-plans-and-agreements/

以上で実装は完了です。後はPlan通りに課金がされ、決済時に通知(Webhook)が届くのを待ちます。

定期支払いの決済結果の確認方法

以下の通知によって確認が可能です。

  • 通知メール(全ての導入方法共通)
  • IPN(Instant Payment Notification。全ての導入方法共通。但し、設定した場合のみ)
  • Webhook(REST APIでの実装でかつ登録した場合のみ)