Integração com Stripe

Domine a integração de processamento de pagamentos com Stripe para fluxos de pagamento robustos e compatíveis com PCI, incluindo checkout, assinaturas, webhooks e reembolsos.

Quando Usar Esta Habilidade

• Implementar processamento de pagamentos em aplicações web/mobile
• Configurar sistemas de cobrança por assinatura
• Lidar com pagamentos únicos e cobranças recorrentes
• Processar reembolsos e disputas
• Gerenciar métodos de pagamento de clientes
• Implementar SCA (Autenticação Forte do Cliente) para pagamentos europeus
• Construir fluxos de pagamento de marketplace com Stripe Connect

Conceitos Principais

1. Fluxos de Pagamento

Sessões de Checkout

• Recomendado para a maioria das integrações
• Suporta todos os caminhos de UI:
  • Página de checkout hospedada pela Stripe
  • Formulário de checkout incorporado
  • UI personalizada com Elements (Payment Element, Express Checkout Element) usando ui_mode='custom'
• Oferece funcionalidades de checkout integradas (itens de linha, descontos, impostos, frete, coleta de endereço, métodos de pagamento salvos e eventos do ciclo de vida do checkout)
• Menor carga de integração e manutenção do que Payment Intents

Payment Intents (Controle Personalizado)

• Você calcula o valor final com impostos, descontos, assinaturas e conversão de moeda por conta própria.
• Implementação mais complexa e carga de manutenção a longo prazo
• Requer Stripe.js para conformidade com PCI

Setup Intents (Salvar Métodos de Pagamento)

• Coletar método de pagamento sem cobrar
• Usado para assinaturas e pagamentos futuros
• Requer confirmação do cliente

2. Webhooks

Eventos Críticos:

• payment_intent.succeeded: Pagamento concluído
• payment_intent.payment_failed: Pagamento falhou
• customer.subscription.updated: Assinatura alterada
• customer.subscription.deleted: Assinatura cancelada
• charge.refunded: Reembolso processado
• invoice.payment_succeeded: Pagamento de assinatura bem-sucedido

3. Assinaturas

Componentes:

• Produto: O que você está vendendo
• Preço: Quanto e com que frequência
• Assinatura: Pagamento recorrente do cliente
• Fatura: Gerada para cada ciclo de faturamento

4. Gerenciamento de Clientes

• Criar e gerenciar registros de clientes
• Armazenar múltiplos métodos de pagamento
• Rastrear metadados do cliente
• Gerenciar detalhes de faturamento

Início Rápido

import stripe

stripe.api_key = "sk_test_..."

# Create a checkout session
session = stripe.checkout.Session.create(
    line_items=[{
        'price_data': {
            'currency': 'usd',
            'product_data': {
                'name': 'Premium Subscription',
            },
            'unit_amount': 2000,  # $20.00
            'recurring': {
                'interval': 'month',
            },
        },
        'quantity': 1,
    }],
    mode='subscription',
    success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url='https://yourdomain.com/cancel'
)

# Redirect user to session.url
print(session.url)

Padrões Detalhados e Exemplos Práticos

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

Testes

# Use test mode keys
stripe.api_key = "sk_test_..."

# Test card numbers
TEST_CARDS = {
    'success': '4242424242424242',
    'declined': '4000000000000002',
    '3d_secure': '4000002500003155',
    'insufficient_funds': '4000000000009995'
}

def test_payment_flow():
    """Test complete payment flow."""
    # Create test customer
    customer = stripe.Customer.create(
        email="test@example.com"
    )

    # Create payment intent
    intent = stripe.PaymentIntent.create(
        amount=1000,
        automatic_payment_methods={
            'enabled': True
        },
        currency='usd',
        customer=customer.id
    )

    # Confirm with test card
    confirmed = stripe.PaymentIntent.confirm(
        intent.id,
        payment_method='pm_card_visa'  # Test payment method
    )

    assert confirmed.status == 'succeeded'