Integração com PayPal

Domine a integração de pagamentos com PayPal, incluindo Checkout Expresso, tratamento de IPN, cobranças recorrentes e fluxos de reembolso.

Quando Usar Esta Habilidade

• Integrar o PayPal como opção de pagamento
• Implementar fluxos de checkout expresso
• Configurar cobranças recorrentes com o PayPal
• Processar reembolsos e disputas de pagamento
• Lidar com webhooks do PayPal (IPN)
• Suportar pagamentos internacionais
• Implementar assinaturas do PayPal

Conceitos Principais

1. Produtos de Pagamento

PayPal Checkout

• Pagamentos únicos
• Experiência de checkout expresso
• Pagamentos de convidados e de contas PayPal

Assinaturas PayPal

• Cobranças recorrentes
• Planos de assinatura
• Renovações automáticas

Pagamentos PayPal (Payouts)

• Enviar dinheiro para múltiplos destinatários
• Pagamentos de marketplace e plataforma

2. Métodos de Integração

Lado do Cliente (SDK JavaScript)

• Botões de Pagamento Inteligente
• Fluxo de pagamento hospedado
• Código de backend mínimo

Lado do Servidor (API REST)

• Controle total sobre o fluxo de pagamento
• Interface de usuário de checkout personalizada
• Recursos avançados

3. IPN (Notificação Instantânea de Pagamento)

• Notificações de pagamento semelhantes a webhooks
• Atualizações de pagamento assíncronas
• Verificação necessária

Início Rápido

// 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
        }

Padrões Detalhados e Exemplos Práticos

A documentação detalhada dos padrões está em references/details.md. Leia este arquivo quando o nível de navegação acima for insuficiente.

Testes

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