Integrating PayPal
Auth: OAuth 2.0 (client credentials) · Partner program: not required · Setup time: about 10 minutes · Last verified: 2026-05-15
PayPal Payments REST API — wallets, subscriptions, invoicing, payouts, disputes.
Auth model
Section titled “Auth model”
rawis opt-in. The upstream payload is withheld unless an operator enablesdata_store.raw_payload.paymentsin Admin → Settings → Data store. It is off by default because across the payments adapters it declares bank account numbers, IBANs and card numbers the canonical schema does not expose.
OAuth2 client credentials (oauth2_cc). Submit clientId + clientSecret from a REST API app in https://developer.paypal.com/dashboard/applications/sandbox. The adapter exchanges them for a 9-hour bearer at /v1/oauth2/token and refreshes on demand.
Configure in admin
Section titled “Configure in admin”- Create a REST API app at https://developer.paypal.com → Apps & Credentials.
- Open
/platforms→ Payments → PayPal → Configure. - Submit:
environment—liveorsandboxclientIdclientSecret
Webhooks
Section titled “Webhooks”Create a webhook in the same dashboard, point it at https://${PUBLIC_BASE_URL}/webhooks/paypal, and subscribe to the events you care about — typically:
PAYMENT.CAPTURE.COMPLETED,PAYMENT.CAPTURE.REFUNDEDBILLING.SUBSCRIPTION.{ACTIVATED,CANCELLED,SUSPENDED}INVOICING.INVOICE.PAIDCUSTOMER.DISPUTE.{CREATED,RESOLVED}
Signature verification uses the Webhook ID plus the Paypal-Transmission-Sig / Paypal-Cert-Url headers. PayPal’s Verify Webhook Signature endpoint must be reachable from the integration server.
Quirks
Section titled “Quirks”- Decimal money. PayPal returns decimal strings (
"10.50"USD). The adapter multiplies by 100 and rounds to minor units. Watch for exotic currencies (JPY, KRW) where minor units == whole units. - No global “list customers” endpoint. Customer records are derived from payer details on individual orders; the adapter leaves
listCustomersempty. - PaymentMethod stays raw. PayPal funding instruments (PayPal balance, card-on-file, BNPL) don’t have a stable canonical mapping; consume
rawif you need them. - Subscriptions live under
/v1/billing/subscriptions— fetch by ID; there’s no full enumeration without webhook-derived index.
References
Section titled “References”- Payments v2: https://developer.paypal.com/docs/api/payments/v2/
- Subscriptions: https://developer.paypal.com/docs/api/subscriptions/v1/
- Invoicing: https://developer.paypal.com/docs/api/invoicing/v2/
- Webhook signature verification: https://developer.paypal.com/api/rest/webhooks/rest/
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.