---
name: integracion-paypal
description: Guía de referencia para integrar PayPal como pasarela de pago en proyectos web, cubriendo checkout exprés, suscripciones recurrentes, payouts y gestión de reembolsos mediante SDK JavaScript y API REST.
license: MIT
metadata:
  id: 5d3617f2
  slug: integracion-paypal
  titulo: "Integración PayPal"
  servicio: Web
  categoria_recurso: Web-Desarrollo
  tipo: referencia
  nivel: intermedio
  idioma: es
  idioma_original: en
  acceso: gratis
  precio_eur: 0
  plataformas: [PayPal, JavaScript, Python, REST API]
  dependencias: [paypalrestsdk, PayPal JS SDK]
  licencia: { spdx: MIT, redistribuible: true, uso_comercial: true }
  fuente:
    repo: wshobson/agents
    url: https://github.com/wshobson/agents/tree/main/plugins/payment-processing/skills/paypal-integration
    commit: cc37bfd
    autor: wshobson
    nombre_original: paypal-integration
    duplicados_en: []
  seguridad: { veredicto: seguro, riesgo: bajo, escaneado: "2026-06-14", motor: "grep-estatico+auditor-llm" }
  ficha:
    que_hace: "Documenta cómo implementar pagos con PayPal (checkout, suscripciones, reembolsos e IPN) en aplicaciones web."
    como_lo_hace: "Proporciona patrones de código en JavaScript (Smart Buttons) y Python (REST SDK) con ejemplos de flujo completo y pruebas en sandbox."
  content_hash: "5d3617f2bde0cd0b2f08c34452423cf03dffbe3a006c8b8d9b2ec08fdf6215c9"
  version: 1.0.0
---

# PayPal Integration

Master PayPal payment integration including Express Checkout, IPN handling, recurring billing, and refund workflows.

## 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

```javascript
// 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>
```

```python
# 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 lives in `references/details.md`. Read that file when the navigation tier above is insufficient.

## Testing

```python
# 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'
```