PayPal Integration Guide

/paypal-integration

Master PayPal payment integration including Express Checkout, IPN handling, recurring billing, and refund workflows. Ask the user for their stack, existing checkout code, and whether they are in sandbox or live mode; deliver frontend button code, backend handlers, and webhook processors as chat artifacts. For Stripe work, use stripe-integration instead.

When to Use This Skill

• Integrating PayPal as a payment option
• Implementing express checkout flows
• Setting up recurring billing with PayPal
• Processing refunds and payment disputes
• Handling PayPal webhooks (IPN)
• Supporting international payments
• Implementing PayPal subscriptions

Core Concepts

1. Payment Products

PayPal Checkout

• One-time payments
• Express checkout experience
• Guest and PayPal account payments

PayPal Subscriptions

• Recurring billing
• Subscription plans
• Automatic renewals

PayPal Payouts

• Send money to multiple recipients
• Marketplace and platform payments

2. Integration Methods

Client-Side (JavaScript SDK)

• Smart Payment Buttons
• Hosted payment flow
• Minimal backend code

Server-Side (REST API)

• Full control over payment flow
• Custom checkout UI
• Advanced features

3. IPN (Instant Payment Notification)

• Webhook-like payment notifications
• Asynchronous payment updates
• Verification required

Quick Start

// Frontend - PayPal Smart Buttons
<div id="paypal-button-container"></div>

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD"></script>
<script>
  paypal.Buttons({
    createOrder: function(data, actions) {
      return actions.order.create({
        purchase_units: [{
          amount: {
            value: '25.00'
          }
        }]
      });
    },
    onApprove: function(data, actions) {
      return actions.order.capture().then(function(details) {
        // Payment successful
        console.log('Transaction completed by ' + details.payer.name.given_name);

        // Send to backend for verification
        fetch('/api/paypal/capture', {
          method: 'POST',
          headers: {'Content-Type': 'application/json'},
          body: JSON.stringify({orderID: data.orderID})
        });
      });
    }
  }).render('#paypal-button-container');
</script>

# Backend - Verify and capture order
from paypalrestsdk import Payment
import paypalrestsdk

paypalrestsdk.configure({
    "mode": "sandbox",  # or "live"
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
})

def capture_paypal_order(order_id):
    """Capture a PayPal order."""
    payment = Payment.find(order_id)

    if payment.execute({"payer_id": payment.payer.payer_info.payer_id}):
        # Payment successful
        return {
            'status': 'success',
            'transaction_id': payment.id,
            'amount': payment.transactions[0].amount.total
        }
    else:
        # Payment failed
        return {
            'status': 'failed',
            'error': payment.error
        }

Detailed patterns and worked examples

Detailed pattern documentation (server-side order creation client, IPN verification and processing, subscription plan creation, refund workflows, error handling wrappers) lives in references/details.md in this skill's directory. Read that file when the navigation tier above is insufficient.

Testing

# Use sandbox credentials
SANDBOX_CLIENT_ID = "..."
SANDBOX_SECRET = "..."

# Test accounts
# Create test buyer and seller accounts at developer.paypal.com

def test_payment_flow():
    """Test complete payment flow."""
    client = PayPalClient(SANDBOX_CLIENT_ID, SANDBOX_SECRET, mode='sandbox')

    # Create order
    order = client.create_order(10.00)
    assert 'id' in order

    # Get approval URL
    approval_url = next((link['href'] for link in order['links'] if link['rel'] == 'approve'), None)
    assert approval_url is not None

    # After approval (manual step with test account)
    # Capture order
    # captured = client.capture_order(order['id'])
    # assert captured['status'] == 'COMPLETED'

Usage

When the user asks for PayPal integration, establish their stack and mode (sandbox vs live), then deliver working code artifacts: Smart Button markup for the frontend, order create/capture handlers for the backend, and verified IPN processors for asynchronous updates. Always verify captures server-side, verify IPN messages back with PayPal before trusting them, guard against duplicate transaction processing, and keep credentials in environment configuration. Pull the full worked examples from references/details.md for subscriptions, refunds, and error handling. If the user's payment provider is Stripe, hand off to stripe-integration.

/paypal-integration $ARGUMENTS