PayPal

You are integrating PayPal as a payment gateway into a [Django / Next.js / etc.] application.

## Setup
1. Create a PayPal Developer account at developer.paypal.com and create a REST API app
2. Store your API credentials in environment variables — NEVER hardcode them:
   - `PAYPAL_CLIENT_ID` (starts with `A` for live, sandbox IDs vary)
   - `PAYPAL_CLIENT_SECRET` (keep server-side only)
   - `PAYPAL_WEBHOOK_ID` (from the webhook configuration in Developer Dashboard)
   - `PAYPAL_MODE` (set to `sandbox` or `live`)
3. Base URLs:
   - Sandbox: `https://api-m.sandbox.paypal.com`
   - Live: `https://api-m.paypal.com`

## Authentication
PayPal REST APIs use OAuth 2.0. Get an access token before making API calls:

```python
import requests
import base64

def get_paypal_token():
    auth = base64.b64encode(
        f"{settings.PAYPAL_CLIENT_ID}:{settings.PAYPAL_CLIENT_SECRET}".encode()
    ).decode()
    response = requests.post(
        f"{PAYPAL_BASE_URL}/v1/oauth2/token",
        headers={"Authorization": f"Basic {auth}"},
        data={"grant_type": "client_credentials"},
    )
    return response.json()["access_token"]
```

## Recommended Integration: PayPal JavaScript SDK + Orders API v2
For most use cases, use PayPal's Smart Payment Buttons with the Orders API:

### Client-side (JavaScript):
```html
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD"></script>
<div id="paypal-button-container"></div>
<script>
  paypal.Buttons({
    createOrder: function() {
      return fetch('/api/paypal/create-order/', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ amount: '20.00' })
      }).then(res => res.json()).then(data => data.id);
    },
    onApprove: function(data) {
      return fetch(`/api/paypal/capture-order/${data.orderID}/`, {
        method: 'POST'
      }).then(res => res.json()).then(details => {
        // Show success message to buyer
      });
    },
    onError: function(err) {
      // Handle errors (show message to buyer, log for debugging)
    }
  }).render('#paypal-button-container');
</script>
```

### Server-side (Create Order):
```python
def create_order(request):
    token = get_paypal_token()
    order_data = {
        "intent": "CAPTURE",
        "purchase_units": [{
            "amount": {
                "currency_code": "USD",
                "value": "20.00"
            },
            "description": "Product Name",
            "custom_id": "your_internal_order_id"
        }]
    }
    response = requests.post(
        f"{PAYPAL_BASE_URL}/v2/checkout/orders",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        },
        json=order_data,
    )
    return JsonResponse(response.json())
```

### Server-side (Capture Order):
```python
def capture_order(request, order_id):
    token = get_paypal_token()
    response = requests.post(
        f"{PAYPAL_BASE_URL}/v2/checkout/orders/{order_id}/capture",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        },
    )
    result = response.json()
    if result["status"] == "COMPLETED":
        # Fulfill the order using result["purchase_units"][0]["payments"]["captures"][0]
        pass
    return JsonResponse(result)
```

## Webhook Handling (Critical)
Never rely solely on the client-side onApprove callback — always confirm payment via webhooks:

1. Register your webhook endpoint in the PayPal Developer Dashboard
2. Subscribe to events: `CHECKOUT.ORDER.APPROVED`, `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.DENIED`
3. ALWAYS verify the webhook signature (RSA-SHA256):

```python
import hashlib
import base64
from OpenSSL import crypto
import requests as http_requests

def verify_webhook(request):
    # Option 1: Postback verification (simpler but adds latency)
    token = get_paypal_token()
    verification_data = {
        "auth_algo": request.META.get("HTTP_PAYPAL_AUTH_ALGO"),
        "cert_url": request.META.get("HTTP_PAYPAL_CERT_URL"),
        "transmission_id": request.META.get("HTTP_PAYPAL_TRANSMISSION_ID"),
        "transmission_sig": request.META.get("HTTP_PAYPAL_TRANSMISSION_SIG"),
        "transmission_time": request.META.get("HTTP_PAYPAL_TRANSMISSION_TIME"),
        "webhook_id": settings.PAYPAL_WEBHOOK_ID,
        "webhook_event": json.loads(request.body),
    }
    response = http_requests.post(
        f"{PAYPAL_BASE_URL}/v1/notifications/verify-webhook-signature",
        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
        json=verification_data,
    )
    return response.json().get("verification_status") == "SUCCESS"
```

4. Implement idempotency: track processed event IDs to prevent duplicate fulfillment
5. Return 200 quickly, then process asynchronously
6. IMPORTANT: Use the raw request body for verification — do not re-serialize parsed JSON

## Security Best Practices
- Never expose your Client Secret on the client side
- Always verify webhook signatures before processing events
- Use HTTPS for all endpoints — PayPal rejects HTTP webhook URLs
- Store tokens securely and refresh them (tokens expire after ~9 hours)
- Use `custom_id` in purchase_units to link PayPal orders to your internal records
- Enable 3D Secure for card payments via the advanced checkout integration

## Testing
- Use sandbox mode with sandbox API credentials
- PayPal provides sandbox accounts: a personal (buyer) and business (seller) account
- Sandbox URL: https://www.sandbox.paypal.com
- Test various scenarios: successful payment, declined card, pending payment, disputes
- Use the IPN/Webhook Simulator in the Developer Dashboard for webhook testing

## Common Gotchas
- Use the REST v2 Orders API only — ignore Classic NVP/SOAP API references
- Amounts must be strings, not numbers (e.g., "20.00" not 20.00)
- Currency amounts must have exactly 2 decimal places for most currencies
- International payments add 1.5% + potential 3% currency conversion on top of base rate
- PayPal may hold funds for new sellers for up to 21 days — plan for cash flow impact
- Webhook events can arrive out of order — design idempotent handlers
- The `custom_id` field does NOT auto-propagate to all related objects — pass it explicitly
- PayPal retries webhook delivery up to 25 times over 3 days for non-2xx responses