PayPal

When to Use

User needs to integrate PayPal REST API for payments, subscriptions, or payouts. Agent handles checkout flows, webhook verification, OAuth token management, and dispute workflows.

Quick Reference

| Topic | File | |-------|------| | Code patterns | patterns.md | | Webhook events | webhooks.md |

Core Rules

1. Environment URLs are Different

• Sandbox: api.sandbox.paypal.com
• Production: api.paypal.com
• Ask which environment BEFORE generating code
• Credentials are environment-specific — never mix

2. OAuth Token Management

// Token expires ~8 hours — handle refresh
const getToken = async () => {
  const res = await fetch('https://api.paypal.com/v1/oauth2/token', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${Buffer.from(`${clientId}:${secret}`).toString('base64')}`,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'grant_type=client_credentials'
  });
  return res.json(); // { access_token, expires_in }
};

Never hardcode tokens. Implement refresh logic.

3. Webhook Verification is Mandatory

PayPal webhooks MUST be verified via API call — not simple HMAC:

// POST /v1/notifications/verify-webhook-signature
const verification = await fetch('https://api.paypal.com/v1/notifications/verify-webhook-signature', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    auth_algo: headers['paypal-auth-algo'],
    cert_url: headers['paypal-cert-url'],
    transmission_id: headers['paypal-transmission-id'],
    transmission_sig: headers['paypal-transmission-sig'],
    transmission_time: headers['paypal-transmission-time'],
    webhook_id: WEBHOOK_ID,
    webhook_event: body
  })
});
// verification_status === 'SUCCESS'

4. CAPTURE vs AUTHORIZE — Ask First

| Intent | Behavior | |--------|----------| | CAPTURE | Charges immediately on approval | | AUTHORIZE | Reserves funds, capture later (up to 29 days) |

Changing intent after integration breaks the entire flow.

5. Server-Side Validation — Never Trust Client

// After client approves, VERIFY on server before fulfillment
const order = await fetch(`https://api.paypal.com/v2/checkout/orders/${orderId}`, {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// Validate ALL of these:
if (order.status !== 'APPROVED') throw new Error('Not approved');
if (order.purchase_units[0].amount.value !== expectedAmount) throw new Error('Amount mismatch');
if (order.purchase_units[0].amount.currency_code !== expectedCurrency) throw new Error('Currency mismatch');
if (order.purchase_units[0].payee.merchant_id !== YOUR_MERCHANT_ID) throw new Error('Wrong merchant');

6. Idempotency in Webhooks

PayPal may send the same webhook multiple times:

const processed = await db.webhooks.findOne({ eventId: body.id });
if (processed) return res.status(200).send('Already processed');
await db.webhooks.insert({ eventId: body.id, processedAt: new Date() });
// Now process the event

7. Currency Decimal Rules

Some currencies have NO decimal places: | Currency | Decimals | Example | |----------|----------|---------| | USD, EUR | 2 | "10.50" | | JPY, TWD | 0 | "1050" (NOT "1050.00") |

Sending "10.50" for JPY = API error.

Common Traps

• IPN vs Webhooks — IPN is legacy. Use Webhooks for new integrations. Never mix.
• Order states — CREATED → APPROVED → COMPLETED (or VOIDED). Handle ALL states, not just happy path.
• Decimal confusion — PayPal uses strings for amounts ("10.50"), not floats. Some currencies forbid decimals.
• Sandbox rate limits — Lower than production. Don't assume prod will fail the same way.
• Payout vs Payment — Payouts API is separate. Don't confuse sending money (Payouts) with receiving (Orders).