Integração com Stripe

Implemente e verifique checkout, assinaturas, webhooks e reembolsos com Stripe, com autorização explícita do lado do servidor e limites de tentativas.

Não use esta habilidade quando

• A tarefa não estiver relacionada à integração com Stripe
• 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.
• Inspecione o SDK do Stripe instalado e a versão da API/webhook fixada. Esta habilidade de arquivo único não possui um playbook agrupado ou wrapper de produção.

Use esta habilidade quando

• Implementando processamento de pagamentos em aplicações web/mobile
• Configurando sistemas de cobrança por assinatura
• Lidando com pagamentos únicos e cobranças recorrentes
• Processando reembolsos e disputas
• Gerenciando métodos de pagamento de clientes
• Implementando SCA (Autenticação Forte do Cliente) para pagamentos europeus
• Construindo fluxos de pagamento de marketplace com Stripe Connect

Conceitos Principais

1. Fluxos de Pagamento

Sessão de Checkout (Hospedada)

• Página de pagamento hospedada pelo Stripe
• Reduz o manuseio direto de dados de cartão
• Implementação mais rápida
• Suporta pagamentos únicos e recorrentes

Intenções de Pagamento (UI Personalizada)

• Controle total sobre a UI de pagamento
• Usa Stripe.js/Elements para evitar o manuseio direto de dados brutos de cartão
• Implementação mais complexa
• Melhores opções de personalização

Intenções de Configuração (Salvar Métodos de Pagamento)

• Coleta o 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

Entradas e Limite de Segurança

Use uma conta de teste/sandbox do Stripe explicitamente autorizada, registros de pedidos e clientes de propriedade do servidor, a versão instalada do SDK/API e os tipos de webhook esperados. Valores de montante, moedas, IDs de preço/cliente e permissões de reembolso devem vir da política do servidor autenticada, não de parâmetros arbitrários do cliente. Checkout/Elements podem reduzir a exposição de dados de cartão; eles não estabelecem conformidade com PCI por si só.

Os trechos são esboços de integração. Chaves secretas de teste e segredos de assinatura de webhook são diferentes; carregue-os do mecanismo de segredos do projeto e nunca os imprima. Nenhum pagamento, reembolso, atualização de cliente ou configuração de conta ao vivo é autorizado meramente pela leitura desta habilidade.

Início Rápido

import os
import stripe

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

# Create a checkout session
session = stripe.checkout.Session.create(
    payment_method_types=['card'],
    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 de Implementação de Pagamento

Padrão 1: Pagamento Único (Checkout Hospedado)

def create_checkout_session(amount, order_attempt_id, currency='usd'):
    """Cria uma sessão de checkout para pagamento único."""
    try:
        session = stripe.checkout.Session.create(
            payment_method_types=['card'],
            line_items=[{
                'price_data': {
                    'currency': currency,
                    'product_data': {
                        'name': 'Compra',
                        'images': ['https://example.com/product.jpg'],
                    },
                    'unit_amount': amount,  # Valor em centavos
                },
                'quantity': 1,
            }],
            mode='payment',

…