ペイアウトの導入方法

ペイアウトの実装はREST API を使用します。以下REST APIに共通する実装内容を記載します。

REST APIの実装方法

APIエンドポイント

Sandbox:

https://api.sandbox.paypal.com

本番環境:

https://api.paypal.com

アプリケーションを登録する
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」に表示されているものを使います)

詳細は以下を参照してください。

https://developer.paypal.com/docs/integration/direct/make-your-first-call/#create-a-paypal-app

アクセストークンを取得する
アプリケーションに設定された情報(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

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

生成したアクセストークンを含んだリクエストヘッダを生成し、各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」を押します。

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

{
  "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": [
      {
        "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"
    }
  ]
}
                                

4. WebhookはWebhook APIによってAPIで動的に登録、変更、削除することもできます。詳細は以下をご参照ください。

https://developer.paypal.com/docs/integration/direct/rest-webhooks-overview/

Payout API の実装方法

PayoutsのURIにリクエストをPOSTします。
URIs
https://api.paypal.com/v1/payments/payouts
https://api.paypal.com/v1/payments/payouts-item

サンプルリクエスト

curl -v https ://api.sandbox.paypal.com/v1/payments/payouts/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
    "sender_batch_header": {
        "sender_batch_id": "2014021801",
        "email_subject": "You have a Payout!",
        "recipient_type": "EMAIL"
    },
    "items": [
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": "1.0",
                "currency": "USD"
            },
            "note": "Thanks for your patronage!",
            "sender_item_id": "201403140001",
            "receiver": "shirt-supplier-one@mail.com"
        }
    ]
}'
                        

GETパラメータにsync_mode=trueを付与することで、同期処理(決済が完了するまで待つモード)で送金されます。単独アカウントへの送金に適しています。指定しない場合はsync_mode=falseで非同期処理(決済完了を待たず完了するモード)で送金されます。
非同期で送金した場合、決済の結果は、Webhookを登録することで通知されます。詳細は以下をご参照ください。

https://developer.paypal.com/docs/api/#payouts

4.その他

受取人のメールアドレスに該当するPayPalアカウントが存在しない場合は、その送金はエラーとなります。