Skip to content

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.

raw is opt-in. The upstream payload is withheld unless an operator enables data_store.raw_payload.payments in 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.

  1. Create a REST API app at https://developer.paypal.com → Apps & Credentials.
  2. Open /platforms → Payments → PayPal → Configure.
  3. Submit:
    • environment — live or sandbox
    • clientId
    • clientSecret

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.REFUNDED
  • BILLING.SUBSCRIPTION.{ACTIVATED,CANCELLED,SUSPENDED}
  • INVOICING.INVOICE.PAID
  • CUSTOMER.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.

  • 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 listCustomers empty.
  • PaymentMethod stays raw. PayPal funding instruments (PayPal balance, card-on-file, BNPL) don’t have a stable canonical mapping; consume raw if you need them.
  • Subscriptions live under /v1/billing/subscriptions — fetch by ID; there’s no full enumeration without webhook-derived index.