How do I integrate PayPal for revenue tracking?

Connecting PayPal lets Zenovay show revenue alongside your traffic data — which marketing source produced the paying customer, which page they converted on, which campaign closed the deal.

PayPal integration uses three credentials from your PayPal Developer account: a Client ID, a Client Secret, and a Webhook ID. We recommend setting up Sandbox first to verify everything works, then switching to Live.

Step 1: Create a PayPal REST API app

1. 1

   Sign in to PayPal Developer

   Go to developer.paypal.com and sign in with your PayPal business account. Free; takes about a minute.

2. 2

   Open Apps & Credentials

   In the dashboard, click Apps & Credentials. Toggle to Sandbox for testing, or Live for production.

3. 3

   Create a new app

   Click Create App. Name it something like "Zenovay Analytics". Pick Merchant as the app type. Click Create App.

4. 4

   Copy your Client ID and Secret

   PayPal shows your Client ID (long alphanumeric string) and Secret (click Show to reveal). Keep this tab open — you'll paste these into Zenovay in Step 3.

Step 2: Create a Webhook in PayPal

PayPal needs to know where to send payment notifications.

1. 1

   Open the Webhooks section

   Still inside your app's settings, scroll to Sandbox Webhooks (or Live Webhooks). Click Add Webhook.

2. 2

   Enter the Zenovay webhook URL

   Paste your Zenovay webhook endpoint:

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

   Replace YOUR_WEBSITE_ID with your Zenovay website ID (visible in Settings → Websites in app.zenovay.com).

3. 3

   Subscribe to the right events

   Check at minimum:

   • Payment capture completed
   • Payment capture refunded
   • Checkout order approved (optional; logged for observability)

   Click Save.

4. 4

   Copy the Webhook ID

   PayPal generates a Webhook ID (long alphanumeric string, different from the Client ID). Copy it.

Step 3: Connect in Zenovay

1. 1

   Open the Revenue Attribution settings

   In app.zenovay.com, go to Settings → Revenue Attribution. Click the PayPal card.

2. 2

   Paste your three credentials

   • Client ID — from Step 1
   • Client Secret (this is the API Key field) — from Step 1
   • Webhook ID — from Step 2
3. 3

   Choose Sandbox or Live

   Match the environment you set up in Step 1. Sandbox uses api-m.sandbox.paypal.com; Live uses api-m.paypal.com. Mixing modes will fail signature verification.

4. 4

   Click Save

   Zenovay validates your credentials by fetching an OAuth2 access token from PayPal. If anything is wrong, you'll see a clear error. Once valid, the card flips to Connected.

Step 4: Tag your orders with the visitor ID (recommended)

For payment-to-traffic-source attribution to work most accurately, set the visitor's anonymous Zenovay ID as custom_id when creating the PayPal order on your server:

// 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
    }],
  },
});

When the capture completes, Zenovay reads purchase_units[0].custom_id and joins the payment to the visitor's session — including the source, campaign, and pages they visited before paying.

If you don't set custom_id, attribution still works via the payer's email address, but it's less precise (only matches if the visitor previously identified themselves with the same email).

What attribution model is used

Zenovay supports two attribution windows:

• First-touch — credit goes to the source the visitor arrived from on their first session.
• Last-touch — credit goes to the source they arrived from on the session containing the payment.

Both are computed and shown side-by-side in the Revenue tab.

Sandbox testing

Once connected to Sandbox, you can simulate webhooks without making real payments:

1. PayPal Dashboard → your sandbox app → Webhooks Simulator.
2. Pick PAYMENT.CAPTURE.COMPLETED → choose your webhook → Send Test.
3. Within ~30 seconds, the test capture appears in your Zenovay Revenue tab.

If nothing appears, check the Verification status under the PayPal card in Zenovay's settings — a misconfigured Webhook ID is the most common cause of failed verification.

Switching from Sandbox to Live

When you're ready for production:

1. In PayPal Developer, create a Live REST API app and Live Webhook (Step 1 + Step 2 again, but on the Live tab).
2. In Zenovay, open the PayPal card, paste the Live credentials, switch the toggle to Live, click Save.

The same Zenovay webhook URL works for both Sandbox and Live; PayPal sends the events to whichever environment matches your registered Webhook ID.

Disconnecting

In Settings → Revenue Attribution, click the PayPal card, then Disconnect. Existing payment records stay in your Zenovay dashboard for the duration of your data retention window. PayPal will stop sending new events.

Limitations (V1)

• Subscriptions are not yet supported. Subscription events (BILLING.SUBSCRIPTION.PAYMENT.SUCCEEDED) are received and logged, but not yet rendered in the Revenue dashboard. Track this article's last_updated date for V2 support.
• One PayPal account per Zenovay website. If you accept payments through multiple PayPal accounts, configure each on its own Zenovay website.
• OAuth-redirect connect (Log-in-with-PayPal-style) is not supported. Manual credential entry only.

Related reading

• Stripe revenue integration
• Webhooks overview
• E-commerce revenue tracking
• Installing the tracking script