Integrate PayPal Payments and Subscriptions

This guide covers PayPal one-time checkout, recurring subscriptions, notification processing, and refund or dispute handling. It distinguishes browser interaction from backend payment authority. The JavaScript SDK creates an order through an authenticated application endpoint and sends approval information to a backend capture endpoint. Do not combine browser capture with a second backend capture or pass Orders v2 identifiers to a legacy Payments v1 SDK.

The backend must bind the order to an owned cart, derive amount, currency, and payee from trusted data, and verify capture state before atomic fulfilment. Browser approval is not payment evidence. Each supported mutation needs a persisted, operation-specific PayPal-Request-Id that remains unchanged on retry. A timeout leaves an uncertain outcome: reconcile the existing operation instead of creating a second charge.

Use the guide to plan and test PayPal flows with explicit sandbox or live configuration. Its Python fragments demonstrate OAuth token retrieval, order creation, capture, and order lookup using bounded requests without redirects. Money must use Decimal or string amounts with currency-specific precision, not binary floating-point values. Protect backend credentials and implement authentication, CSRF or origin controls, token refresh, and validated opaque resource IDs.

These are sandbox fragments, not a complete payment system. Referenced checkout, IPN, refund, billing, and Python support files are external prerequisites absent from this catalog copy. Obtain and inspect the original material before dependent steps; do not fabricate it or infer production readiness from its filename. Refunds and recurring charges require authorization for the exact operation.

Inputs include environment-specific credentials, trusted cart or subscription data, merchant identity, resource identifiers, and durable operation records. Outputs include provider order or subscription records and verified internal payment state. Creating a plan requires an existing product; subscription setup must handle the customer's approval flow. Application route handlers, durable storage, and fulfilment adapters are integration work rather than bundled components.

Look up the existing order through the Orders v2 resource:

        url = f"{self.base_url}/v2/checkout/orders/{order_id}"

IPN is a legacy protocol distinct from REST Webhooks. IPN verification echoes the original encoded body; current REST integrations need signature verification with the correct webhook ID and environment. Verified origin alone is insufficient: validate receiver, currency, amount, owned order or invoice, and transaction status. Bound request sizes, deduplicate atomically through unique event or transaction records, process reversals against original records, and acknowledge after durable recording. A check-then-act helper can race.

Testing uses sandbox buyer and seller accounts and must include approval and verified capture, not merely a returned order ID. Keep logs to minimal identifiers and statuses, redact sensitive provider details, handle duplicate notifications and all relevant payment states, and keep sandbox credentials and endpoints separate from live ones.