収益トラッキングのためにPayPalをどのように統合しますか？

PayPalを接続することで、Zenovayはトラフィックデータと並べて収益を表示できます — どのマーケティングソースが有料顧客を生み出したか、どのページでコンバートしたか、どのキャンペーンが取引を成立させたか。

PayPal Developerアカウントから必要な認証情報は3つです：Client ID、Client Secret、そしてWebhook IDです。PayPalダッシュボードでWebhookを作成し（Zenovayが貼り付ける正確なURLを表示します）、そのIDをZenovayにコピー戻します。すべてが正しく動作することを確認するため、まずSandboxでセットアップし、その後Liveに切り替えることをお勧めします。

⚠️ 重要 — まず最初にお読みいただきたいテストに関するヒント

PayPalのWebhooks Simulator（PayPal Developer Dashboardの「Send Test」ボタン）が送信するモックイベントは、仕様上、署名検証ができません。これはPayPalで文書化されている挙動であり、シミュレーターは署名を実際のWebhook IDではなくプレースホルダーのWEBHOOK_IDにバインドするため、検証APIはシミュレーターのイベントに対して常にFAILUREを返します。

統合が実際に動作することを確認するには、実際のSandboxチェックアウトを実施してください（下記のステップ5）— こちらは適切に署名されたイベントを生成し、Zenovayが検証可能です。

ステップ1：PayPal REST APIアプリを作成する — そしてWebhooks機能を有効化する

⚠️ アプリでWebhooks機能を有効化してください。

新規のPayPal REST APIアプリは、デフォルトで「Accept payments only（支払いの受付のみ）」になっています。アプリでWebhookを作成・検証できるようにするには、Webhooks機能が有効化されている必要があります。これは30秒で済む一度きりのセットアップです。

1. 1

   PayPal Developerにサインインする

   developer.paypal.comにアクセスし、PayPalビジネスアカウントでサインインします。無料で、約1分かかります。

2. 2

   Apps & Credentialsを開く

   ダッシュボードでApps & Credentialsをクリックします。テストにはSandbox、本番環境にはLiveに切り替えます。

3. 3

   新しいアプリを作成する

   Create Appをクリックします。「Zenovay Analytics」のような名前を付けます。アプリタイプとしてMerchantを選択します。Create Appをクリックします。

4. 4

   Client IDとSecretをコピーする

   PayPalはClient ID（長い英数字の文字列）とSecret（Showをクリックすると表示されます）を表示します。このタブを開いたままにしてください — ステップ3でこれらをZenovayに貼り付けます。

5. 5

   Webhooks機能のチェックボックスにチェックを入れる

   アプリの設定ページのまま、Featuresセクション（場合によってはApp settingsと表示されます）までスクロールしてください。Accept payments、Vault、Payouts、Subscriptions、Log in with PayPal、そしてWebhooksといったチェックボックスが表示されます。

   Webhooksのチェックボックスにチェックを入れ、ページ下部のSave Changesをクリックします。

   Client Secretを再生成する必要はありません — 新しい権限は、新規に取得したOAuthトークンに即座に適用されます。

ステップ2：PayPalでWebhookを作成してそのWebhook IDをコピーする

Zenovayで自分のサイトの設定を開き、Revenueタブ（Analyticsセクションの下）に移動し、PayPalカードをクリックします。フォームには、あなたのサイトIDを既に含むコピー可能なWebhook URLが表示されます — これをコピーし、PayPal側でWebhookを登録してください。

1. 1

   ZenovayのWebhook URLをコピーする

   ZenovayのPayPalカードで、フォーム上部に表示されているWebhook URLをコピーしてください。以下のようになっています：

   https://api.zenovay.com/api/webhooks/paypal/YOUR_WEBSITE_ID
   

   URLはすでにサイトIDで満たされています — ご自分で構築する必要はありません。

2. 2

   PayPalでWebhookを追加する

   PayPal Developerに戻り、アプリの設定内で、Sandbox Webhooks（またはLive Webhooks）までスクロールしてください。Add Webhookをクリックし、コピーしたURLを貼り付けます。

3. 3

   適切なイベントをサブスクライブする

   最低限以下をチェックしてください：

   • Payment capture completed
   • Payment capture refunded
   • Checkout order approved（オプション、観測性のためにログ記録されます）

   Saveをクリックしてください。PayPalがWebhook IDを生成します — ステップ3のために保管しておきます。

ステップ3：Zenovayで接続する

サイト設定のRevenueタブにあるPayPalカードでの作業を続けます：

1. 1

   3つの認証情報を貼り付ける

   • Client ID — ステップ1から
   • Client Secret（これがAPI Keyフィールドです） — ステップ1から
   • Webhook ID — PayPalがステップ2で生成したID（必須）
2. 2

   SandboxまたはLiveを選択する

   ステップ1でセットアップした環境と一致させてください。Sandboxはapi-m.sandbox.paypal.comを使用し、Liveはapi-m.paypal.comを使用します。モードを混在させると署名検証が失敗します。

3. 3

   Saveをクリックする

   Zenovayは、OAuth2アクセストークンを取得することで認証情報を検証し、その後Webhook IDをPayPalに対して検証します。カードはConnectedに切り替わります。

ステップ4：注文に訪問者IDをタグ付けする（推奨）

支払いとトラフィックソースの帰属を最も正確に機能させるためには、サーバー上でPayPal注文を作成する際に、訪問者の匿名Zenovay IDをcustom_idとして設定してください：

// Node.js example using @paypal/paypal-server-sdk
const visitorId = req.cookies['zv_visitor_id']; // or however your client passes it

await paypalClient.ordersCreate({
  body: {
    intent: 'CAPTURE',
    purchase_units: [{
      amount: { currency_code: 'USD', value: '42.00' },
      custom_id: visitorId, // ← Zenovay visitor UUID goes here
    }],
  },
});

キャプチャが完了すると、Zenovayはpurchase_units[0].custom_idを読み取り、支払いを訪問者のセッションに結合します — 支払い前に訪問したソース、キャンペーン、ページを含みます。

custom_idを設定しなくても、支払い者のメールアドレスを介して帰属は機能しますが、精度は低くなります（訪問者が以前に同じメールアドレスで自身を識別した場合のみマッチします）。

帰属がどのように機能するか

Zenovayは各支払いをトラフィックソースに帰属させ、Revenueタブから複数の帰属モデルの間で切り替えることができます：

• Last Touch（デフォルト） — 100%のクレジットがコンバージョン前の最後のチャネルに帰属します。取引を成立させるものを測定するのに良いです。
• First Touch — 100%のクレジットが訪問者を最初に連れてきたチャネルに帰属します。発見を促進するものを測定するのに良いです。
• Linear — クレジットは訪問者が使用したすべてのチャネル間で均等に分割されます。
• Position-Based — 最初のチャネルに40%、最後のチャネルに40%、中間のすべてに残り20%。
• Time-Decay — 7日間の半減期で、コンバージョンに近いチャネルにより多くのクレジット。

Revenueタブでモデルを選択してください。選択したモデルに対して内訳が再計算されます。

ステップ5：Sandboxテスト — Simulatorではなく実際のチェックアウトを使用してください

PayPalのWebhooks Simulatorを使ってテストしないでください。 Simulatorのイベントは、仕様上、署名検証ができません（PayPalで文書化されています） — Zenovayの検証チェックに常に失敗します。代わりに、以下に説明するように実際のSandboxチェックアウトを使用してください。

Sandbox統合を検証する正しい方法：

1. PayPal Developer Dashboard → Sandbox → Accounts。デフォルトの**Personal (buyer)**サンドボックスアカウントが、ダミーのメールアドレスとパスワードと共に表示されているはずです — これがテスト用買い手の認証情報です。
2. ご自身のアプリケーションまたはPayPal SDKから、サンドボックスのclient_idを使ってサンドボックス注文を作成します（最良の帰属を得たい場合は、purchase_units[0].custom_id = visitorIdを設定します — 上記のステップ4をご参照ください）。
3. ステップ1のサンドボックス買い手アカウントでチェックアウトを完了します。
4. 約10秒以内に、PayPalは実際の署名済みPAYMENT.CAPTURE.COMPLETED WebhookをZenovayに送信します。サイトダッシュボードのRevenueタブを開いて到着を確認してください — キャプチャは買い手のサンドボックスメールアドレスと金額と共に表示されるはずです。

約30秒経ってもキャプチャが表示されない場合：

• Revenue設定のPayPalカード上のVerification statusバッジを確認してください — 直近のエラーが表示されます。
• SandboxとLiveのモードが一致していることを確認してください：Sandbox WebhookがLive統合に対して発火（またはその逆）すると、署名検証が失敗します。
• WebhookがまだPayPalに登録されていることを確認してください：PayPal Dashboard → ご自身のアプリ → Webhooks。削除されている場合は、Zenovayカードで再度追加して新しいWebhook IDを貼り付けてください。

SandboxからLiveへの切り替え

本番環境の準備が整ったら：

1. PayPal Developerで、Live REST APIアプリとLive Webhookを作成してください（ステップ1とステップ2をLiveタブで再度行う — Live Webhookは独自のWebhook IDを取得します）。
2. Zenovayで、PayPalカードを開き、Live認証情報とLive Webhook IDを貼り付け、トグルをLiveに切り替え、Saveをクリックしてください。

PayPalは登録されたWebhook IDに一致する環境にイベントを送信するため、認証情報とWebhook IDを同じ環境に保つようにしてください。

切断

サイト設定を開く → Revenueタブ → PayPalカードをクリック → Disconnect。

デフォルトでは、切断によってPayPalの認証情報のみが削除されます。既存の支払い記録、アトリビューション履歴、収益ダッシュボードのデータはそのまま残ります（プランのデータ保持期間に従う）。いつでも再接続でき、中断したところから続けられます。

オプション：PayPalの履歴データもまとめて削除する

切断ダイアログにはチェックボックスがあります： 「N件のPayPalレコード（合計X円）も完全に削除する」。テスト統合を撤去する、プライバシーの整理をするなど、まっさらな状態にしたい場合のみチェックしてください。

チェックを入れると、Zenovayは次を実行します：

• このサイトのPayPalのpayment_events行をすべて削除
• このサイトのPayPalのpayments行をすべて削除
• 識別済みユーザーのpaypal_customer_idフィールドをクリア（ユーザーレコード自体は保持され、Stripe IDなどはそのまま残ります）

削除は単一のトランザクションで実行されます — いずれかのステップが失敗した場合、3つすべてがロールバックされるため、中途半端な状態になることはありません。この操作は元に戻せません。

PayPal側のWebhookの削除も忘れずに

Zenovay側で切断しても、Zenovayがイベントを受信しなくなるだけです。PayPalはあなたがPayPal Developer Dashboardで削除するまで、当社のエンドポイントにWebhookを送り続けます：

1. https://developer.paypal.com/dashboard/applications/ を開きます
2. PayPal REST APIアプリをクリックしてください。
3. Webhooksセクションを開いてください。
4. https://api.zenovay.com/api/webhooks/paypal/{your-website-id}を指すWebhookを見つけて削除してください。

PayPal側で削除するまで、当社のエンドポイントは各配信に対して410 Goneを返します。PayPalは410の後にリトライを諦めるため、ほとんど見た目だけの問題ですが — 良い習慣であり、WebhookがPayPal自身のリトライログを汚すのを防ぎます。

制限事項

• 1つのZenovayサイトにつき1つのPayPalアカウント。 複数のPayPalアカウントで支払いを受け付ける場合は、それぞれ独自のZenovayサイトに設定してください。
• 接続は手動入力のみです。 「Log in with PayPal」スタイルのOAuthリダイレクトはありません — Client ID、Client Secret、Webhook IDを直接貼り付けます。

トラブルシューティング

実際のテストWebhookで「Verification failed」が発生する

最もよくある原因はSandbox/Liveの不一致です — sandbox.paypal.comから発火されたWebhookがLiveとしてマークされた認証情報に対して送信される（あるいはその逆）と、署名検証が失敗します。PayPalカードのトグルが、認証情報の環境と一致していることを確認してください。

PayPalのWebhooks Simulatorを使用された場合、それは既知の制限です — シミュレーターのイベントは仕様上、署名検証ができません（PayPalは署名を実際のWebhook IDではなくプレースホルダーのWEBHOOK_IDリテラルにバインドします）。常に実際のSandboxチェックアウトでテストしてください。

「NOT_AUTHORIZED」/ Saveでの403エラー

これはたいていPayPal REST APIアプリでWebhooks機能が有効化されていない場合を意味します。または、Personal Sandboxアカウントを使用しており、WebhooksではBusiness Sandboxアカウントが必要です。

修正：

1. https://developer.paypal.com/dashboard/applications を開き、アプリをクリックしてください。
2. 正しいタブ（SandboxまたはLive）にいることを確認してください — それぞれ別々の設定を持っています。
3. Featuresセクション（Client ID / Secretブロックの下）までスクロールしてください。
4. Webhooksのチェックボックスにチェックを入れてください。
5. ページ下部のSave Changesをクリックしてください。
6. Sandboxの場合は、Business Sandboxアカウントを使用していることを確認してください。Personal Sandboxアカウントではありません。

Client Secretを再生成する必要はありません。新しい権限は、新規に取得したOAuthトークンに即座に適用されます。

PayPalアプリの10 Webhookという上限に達した

PayPalは各REST APIアプリにつき最大10個のWebhookという上限を設けています。複数のZenovayサイトでZenovayを登録した場合に、この上限に達する可能性があります。https://developer.paypal.com/dashboard/applications で未使用のWebhookを削除するか、新しいWebhookを追加して、その関連するZenovayサイトにそのIDを貼り付けてください。

関連情報

• Stripe収益統合
• Webhook概要
• eコマース収益トラッキング
• トラッキングスクリプトのインストール