Integrate PayPal Payments and Subscriptions

Provides comprehensive PayPal payment integration patterns - Express Checkout, IPN (Instant Payment Notification) handling, recurring billing/subscriptions, and refund workflows.

Use this skill when integrating PayPal as a payment option, implementing express checkout flows, setting up recurring billing, processing refunds and payment disputes, handling PayPal IPN webhooks, supporting international payments, or implementing PayPal subscriptions. Not a fit for other payment processors or for tasks unrelated to PayPal integration.

Covers three PayPal payment products (Checkout for one-time payments, Subscriptions for recurring billing, Payouts for sending money to multiple recipients) and two integration methods: client-side JavaScript SDK (Smart Payment Buttons, hosted flow, minimal backend) versus server-side REST API (full control, custom checkout UI).

Provides a complete Smart Buttons quick-start example (frontend createOrder/onApprove handlers posting the order ID to a backend capture endpoint) alongside a Python backend example using paypalrestsdk to find and execute a payment. A full PayPalClient class implements OAuth token acquisition, order creation (v2/checkout/orders), order capture, and order detail retrieval against sandbox or live base URLs.

IPN handling shows a Flask webhook route parsing IPN form data, verifying authenticity by posting the data back to PayPal with a cmd=_notify-validate parameter and checking for a VERIFIED response, then dispatching on payment_status to handlers for completed payments (with duplicate-transaction prevention via txn_id), refunds, and chargebacks/reversals.

Subscription/recurring billing shows creating a billing plan (v1/billing/plans) with a billing cycle frequency, fixed pricing, and payment preferences (auto-bill outstanding, setup fee, failure threshold), then creating a subscription for a specific subscriber and extracting the approval URL from the response's links array. Refund workflows show creating a full or partial refund against a capture ID with an optional payer note, and retrieving refund details.

Error handling wraps API calls in a custom PayPalError exception distinguishing network errors from other API errors. Testing guidance uses sandbox credentials and test buyer/seller accounts from the PayPal developer portal, with an example test asserting order creation and approval URL presence.

Best practices: always verify IPN before trusting it, process notifications idempotently to handle duplicates, implement robust error handling and logging for all transactions, test extensively in sandbox, don't rely solely on client-side callbacks, and always specify currency explicitly. Common pitfalls include skipping IPN verification, missing duplicate-transaction checks, mixing sandbox and production credentials/URLs, not handling all payment states, and hardcoding environment-specific values.

Integrates PayPal's JavaScript SDK (Smart Payment Buttons), REST API (Checkout Orders v2, Billing Plans/Subscriptions v1, Payments/Refunds v2), and the legacy IPN webhook mechanism, with a Flask example for webhook handling.

Developers integrating PayPal payments who need concrete Express Checkout, IPN verification, subscription billing, and refund implementation patterns rather than assembling them from PayPal's scattered documentation.

def verify_ipn(ipn_data):
    verify_data = ipn_data.copy()
    verify_data['cmd'] = '_notify-validate'
    response = requests.post(paypal_url, data=verify_data)
    return response.text == 'VERIFIED'