Disponibilidade de Material de Apoio

Os seguintes são pré-requisitos externos, não arquivos incluídos: <support-root>/references/express-checkout.md, <support-root>/references/ipn-handling.md, <support-root>/references/refund-workflows.md, <support-root>/references/billing-agreements.md, <support-root>/assets/paypal-client.py, <support-root>/assets/ipn-processor.py, <support-root>/assets/recurring-billing.py. Obtenha-os da fonte original ou de uma instalação existente e inspecione-os antes de usar. Não execute ou declare a conclusão de uma etapa dependente até que seu arquivo necessário exista; reporte etapas indisponíveis. O fluxo de trabalho inline totalmente documentado permanece utilizável dentro do escopo autorizado.

Integração com PayPal

Domine a integração de pagamentos com PayPal, incluindo Express Checkout, tratamento de IPN, faturamento recorrente e fluxos de reembolso.

Não use esta habilidade quando

• A tarefa não estiver relacionada à integração com PayPal
• Você precisar de um domínio ou ferramenta diferente fora deste escopo

Instruções

• Clarifique objetivos, restrições e entradas necessárias.
• Aplique as melhores práticas relevantes e valide os resultados.
• Forneça etapas acionáveis e verificação.

Use esta habilidade quando

• Integrar o PayPal como opção de pagamento
• Implementar fluxos de checkout expresso
• Configurar faturamento recorrente com PayPal
• Processar reembolsos e disputas de pagamento
• Lidar com webhooks do PayPal (IPN)
• Apoiar 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 com conta PayPal

Assinaturas PayPal

• Faturamento recorrente
• 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
• UI 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
        }

Implementação do Express Checkout

Criação de Pedido no Lado do Servidor

import requests
import json

class PayPalClient:
    def __init__(self, client_id, client_secret, mode='sandbox'):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = 'https://api-m.sandbox.paypal.com' if mode == 'sandbox' else 'https://api-m.paypal.com'
        self.access_token = self.get_access_token()

    def get_access_token(self):
        """Obtém o token de acesso OAuth."""
        url = f"{self.base_url}/v1/oauth2/token"
        headers = {"Accept": "application/json", "Accept-Language": "pt_BR"}


…