/paypal-best-practices

name: paypal-best-practices
description: >-
  PayPal integration guidance, code examples, and best practices.
  Use for checkout, card fields, BNPL, Pay Later, Venmo, subscriptions,
  invoicing, disputes, payouts, webhooks, APMs, JS SDK v5, JS SDK v6,
  createInstance, payment sessions, web components, Fastlane, payment links,
  donations, 3D Secure, vaulting, iDEAL, bank redirects, agentic commerce,
  or any PayPal architecture decision or code generation question.
when_to_use: >-
  "how do I integrate PayPal", "PayPal checkout example", "PayPal best
  practices", "PayPal subscriptions guide", "PayPal webhook setup",
  "PayPal error handling", "PayPal SDK code", "add Pay Later", "add Venmo",
  "PayPal card fields", "PayPal disputes", "PayPal invoices",
  "PayPal docs link", or any PayPal code generation request.
allowed-tools: Read, WebFetch, WebSearch
metadata:
  version: "1.2.0"
  category: payments-integration
  tags: checkout bnpl venmo subscriptions disputes apm fastlane webhooks

PayPal Best Practices

Before answering, read the relevant reference file from the table below. The reference files contain current documentation URLs, country availability, and verified code examples.

Integration Routing

| Developer intent | Reference file | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Accept payments, add PayPal button, checkout flow, Orders API, payment link, payment links, pay link, React PayPal, @paypal/react-paypal-js, authorize vs capture, deferred capture, donate button, donations | [references/checkout.md](references/checkout.md) (v5) or [references/js-sdk-v6.md](references/js-sdk-v6.md) (v6) | | Advanced Card Fields, Apple Pay, Google Pay, APMs, Expanded Checkout, bank redirect, iDEAL, Bancontact, BLIK, Przelewy24, Pay upon Invoice, Ratepay, domain association, regional payment methods | [references/expanded-checkout.md](references/expanded-checkout.md) (v5) or [references/js-sdk-v6.md](references/js-sdk-v6.md) (v6) | | Add Venmo, Venmo button, Venmo eligibility, isEligible, eligibility check, Venmo app | [references/venmo.md](references/venmo.md) (v5) or [references/js-sdk-v6.md](references/js-sdk-v6.md) (v6) | | Pay Later, installments, BNPL messaging, Pay in 4, financing, BNPL banner, Pay Later banner, Pay Later eligibility | [references/bnpl.md](references/bnpl.md) (v5) or [references/js-sdk-v6.md](references/js-sdk-v6.md) (v6) | | Recurring billing, subscriptions, plan management, free trial, trial period, upgrade plan, downgrade plan, plan revision | [references/subscriptions.md](references/subscriptions.md) (v5) or [references/js-sdk-v6.md](references/js-sdk-v6.md) (v6)