Integração de pagamentos com Claude Code: Stripe + Sepay de A a Z (2026)

Por que usar o Claude Code para integrar pagamentos?

A integração de pagamentos é aquele tipo de trabalho repetitivo, mas fácil de errar: criar uma rota de checkout, lidar com o redirecionamento, escrever um webhook, verificar assinaturas, salvar pedidos e cobrir cada caso de teste. Fazer isso à mão a partir da documentação consome uma tarde inteira, e perder um único detalhe (digamos, um webhook que não é idempotente) pode cobrar o cliente duas vezes.

A força do Claude Code aqui é que ele age como um construtor, não apenas como quem sugere código. Em uma única sessão, ele lê a estrutura do seu repositório, descobre se você está no App Router ou no Express, então gera a rota de API certa, produz um handler de webhook que corresponde ao payload do gateway e roda os comandos de teste direto do seu terminal. Passar de "algumas horas cavando na documentação" para "alguns minutos revisando um diff" é uma diferença de verdade, especialmente quando você precisa conectar o Stripe e o Sepay de uma vez. Se você ainda não deixou o Claude Code escrever uma API, leia primeiro o nosso guia sobre construir uma API de backend com o Claude Code para aprender a orientá-lo bem.

Mas deixo isso claro logo de início: pagamentos envolvem dinheiro de verdade, então uma pessoa ainda precisa revisar cada linha. O Claude Code pode verificar a unidade de moeda errada, pular um caso extremo ou sugerir uma API descontinuada. Trate-o como um dev júnior rápido — quem assina embaixo ainda é você. O princípio que atravessa este artigo inteiro: a IA constrói, você verifica.

Escolhendo um gateway: Stripe vs Sepay vs Polar

Escolha o seu gateway antes de digitar um prompt, porque cada um tem o seu próprio fluxo e payload. Três opções populares para quem desenvolve atendendo clientes vietnamitas e globais:

A recomendação curta: para clientes vietnamitas, use o Sepay (VietQR/NAPAS, o cliente escaneia um código para transferir e o dinheiro cai na sua conta bancária); para clientes internacionais que pagam com cartão, use o Stripe; para vender SaaS globalmente quando você prefere não lidar com impostos, use o Polar, já que ele age como Merchant of Record e cuida do VAT por você. Muitos apps rodam Stripe e Sepay lado a lado: clientes do exterior passam pelo Stripe, clientes domésticos passam pelo VietQR. Este artigo se aprofunda nesses dois gateways; o fluxo do Polar é parecido com o do Stripe (ele tem o próprio adaptador para Next.js).

O que preparar antes de começar

Um checklist antes de você abrir o Claude Code (dê uma passada rápida e preencha o que estiver faltando):

• Um app Next.js ou Node/Express que já roda localmente.
• Uma conta Stripe em modo de teste, ou uma conta Sepay em sandbox (as chaves têm a cara de SP-TEST-*).
• Chaves secretas guardadas no .env e nunca commitadas — adicione o .env ao .gitignore primeiro.
• Claude Code instalado e um CLAUDE.md no repositório descrevendo a sua stack e convenções (usamos ele abaixo).
• Um endpoint público para o gateway chamar o webhook — localmente, use o Stripe CLI ou um túnel; em produção, use HTTPS de verdade.

Lidar com chaves secretas é a parte mais frágil da segurança de pagamentos, então leia também sobre gerenciar as permissões do Claude Code com segurança para não deixar o agente ler ou imprimir um segredo nos logs sem querer.

Como orientar o Claude Code no trabalho de pagamentos

A qualidade da saída depende quase inteiramente de como você orienta. Para pagamentos, as duas coisas que mais importam são contexto no CLAUDE.md e um prompt específico.

Adicione algumas linhas de contexto assim ao CLAUDE.md para o Claude Code não ter que adivinhar:

# Payment context
- Stack: Next.js 15 App Router, TypeScript, Prisma + PostgreSQL
- Gateways: Stripe (international) + Sepay/VietQR (VN customers)
- Env: all secrets live in .env, NEVER commit, NEVER print to logs
- Convention: use Stripe Checkout Sessions only, NO legacy Charges/Card Element
- Safety: NEVER run production commands, NEVER refund; test mode/sandbox only

Depois, o prompt. Compare um vago "integre o Stripe pra mim" com um específico:

Read app/ and prisma/schema.prisma. Create a POST route app/api/checkout/route.ts
that creates a Stripe Checkout Session (mode payment) from the priceId in the body
and returns session.url. Use the existing env vars. Do not touch other files.
Then document a Stripe CLI test in the README; do not run any live commands.

Um prompt específico mantém as mudanças do Claude Code no escopo, usa o seu esquema de banco de dados real e impede que ele "invente" arquivos extras. Você também pode apontá-lo para a documentação do gateway via fetch/MCP (documentação do Stripe, developer.sepay.vn) para que ele siga a API mais recente em vez da memória desatualizada.

O fluxo do Stripe com o Claude Code (clientes internacionais)

O fluxo moderno do Stripe cabe em quatro passos. Prefira Checkout Sessions (hospedadas pelo Stripe) e evite os antigos Charges/Card Element, já que são ultrapassados e aumentam a sua carga de PCI.

1. Rota para criar uma Checkout Session. Oriente o Claude Code a gerar uma rota que recebe um priceId, cria a sessão e retorna session.url para o cliente redirecionar.
2. Redirecionamento de sucesso/cancelamento. Passe success_url e cancel_url; não marque um pedido como "pago" na página de sucesso — espere o webhook.
3. Webhook checkout.session.completed. Verifique a assinatura com constructEvent antes de tratar qualquer lógica de negócio.
4. Teste com o Stripe CLI direto na sua máquina local, sem precisar de deploy.

// app/api/checkout/route.ts
import { NextResponse } from "next/server";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
 const { priceId } = await req.json();
 const session = await stripe.checkout.sessions.create({
 mode: "payment",
 line_items: [{ price: priceId, quantity: 1 }],
 success_url: `${process.env.APP_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
 cancel_url: `${process.env.APP_URL}/cancel`,
 });
 return NextResponse.json({ url: session.url });
}

// app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
 const body = await req.text(); // raw body is required to verify
 const sig = req.headers.get("stripe-signature")!;
 let event: Stripe.Event;
 try {
 event = stripe.webhooks.constructEvent(
 body, sig, process.env.STRIPE_WEBHOOK_SECRET!
 );
 } catch {
 return new Response("Invalid signature", { status: 400 });
 }
 if (event.type === "checkout.session.completed") {
 // idempotent: check whether event.id was already processed before writing the order
 }
 return new Response("ok", { status: 200 });
}

Teste localmente com dois comandos, a custo zero:

stripe listen --forward-to localhost:3000/api/webhooks/stripe
stripe trigger checkout.session.completed

Para o fluxo completo de entrada em produção e o checklist oficial, veja a documentação do Stripe (docs.stripe.com, acesso em 08/2026) — confirme a versão da API em produção antes de publicar, já que o Stripe a atualiza com frequência.

O fluxo do Sepay/VietQR com o Claude Code (clientes do Vietnã)

O Sepay combina bem com clientes vietnamitas: você gera um código VietQR ou uma conta virtual, o cliente escaneia e transfere, e o Sepay dispara um webhook confirmando que o dinheiro chegou. O fluxo em quatro passos:

1. Crie o pedido e gere o VietQR (ou conta virtual) para aquele pedido, com uma memo de transferência que você consiga conciliar depois.
2. O cliente escaneia o QR e transfere pelo aplicativo do banco dele.
3. O webhook do Sepay reporta a transação com transferType: "in", junto de transferAmount, content e referenceCode.
4. Verifique, remova duplicatas e retorne {"success": true} em menos de 5 segundos para o Sepay não tentar de novo.

// app/api/webhooks/sepay/route.ts
import { db } from "@/lib/db";

export async function POST(req: Request) {
 const auth = req.headers.get("authorization");
 if (auth !== `Apikey ${process.env.SEPAY_API_KEY}`) {
 return new Response("Unauthorized", { status: 401 });
 }
 const data = await req.json();
 // data: { id, transferType, transferAmount, content, referenceCode }
 if (data.transferType !== "in") {
 return Response.json({ success: true }); // ignore outgoing transactions
 }
 const existed = await db.transaction.findUnique({
 where: { sepayId: data.id },
 });
 if (existed) return Response.json({ success: true }); // dedupe by id
 await db.transaction.create({
 data: {
 sepayId: data.id,
 amount: data.transferAmount,
 content: data.content,
 ref: data.referenceCode,
 },
 });
 // TODO: reconcile content with the order, then update its status to "paid"
 return Response.json({ success: true });
}

Salvar transações e conciliá-las com os pedidos deve ficar organizado na camada de dados — veja como armazenar pedidos e transações com um banco de dados para desenhar tabelas de pedidos/transações arrumadas. O Sepay tem o próprio sandbox e um limite de 2 req/s, então é só deixar o Claude Code ler a documentação oficial (developer.sepay.vn, acesso em 08/2026) para manter o endpoint e o payload corretos.

Webhooks e idempotência — a parte mais fácil de errar

É aqui que os tutoriais manuais pulam etapas, e também onde o estrago é pior. Os gateways de pagamento não garantem que um webhook seja entregue exatamente uma vez: redes instáveis, timeouts e retentativas fazem o mesmo evento chegar várias vezes. Se o seu handler não for idempotente, você grava pedidos duplicados, credita um saldo duas vezes ou envia um item duas vezes.

A regra: remova duplicatas pelo identificador do evento. Para o Sepay, é o id da transação; para o Stripe, é o event.id. Guarde o id processado (um índice único no banco) e pule se já tiver visto antes. Para casos mais complexos, use uma chave composta (por exemplo, orderId mais o tipo de evento).

Restrições de tempo e retentativa para lembrar:

• Sepay: o handler precisa retornar 2xx em menos de 5 segundos; caso contrário, o Sepay tenta de novo automaticamente até 7 vezes ao longo de aproximadamente 5 horas em um cronograma de Fibonacci. Isso significa que a mesma transação pode chegar 7 vezes — remover duplicatas é obrigatório.
• Stripe: tenta de novo no próprio cronograma quando não recebe um 2xx; você ainda precisa remover duplicatas pelo event.id.

Uma dica prática: salve o evento primeiro, processe a lógica de negócio depois. Grave o registro do evento (de forma idempotente), então rode a lógica pesada em uma etapa separada, para que, se a lógica falhar, uma retentativa ainda seja segura. Este é um bom momento para pedir ao Claude Code que escreva um teste para o caso do "webhook que chega duas vezes" — ele costuma esquecer a menos que você lembre.

Testes e segurança antes de entrar no ar

Antes de ligar o dinheiro de verdade, passe por este checklist (é também o que os tutoriais manuais mais deixam de fora):

Testes:

• Stripe: use o Stripe CLI (stripe listen/stripe trigger) e cartões de teste; nenhum dinheiro real envolvido.
• Sepay: use o sandbox com chaves SP-TEST-*; simule uma transação de entrada e verifique o webhook.
• Teste os casos de falha: assinatura inválida, webhook chegando duas vezes, valor que não bate com o pedido.

Segurança:

• Nunca exponha a sua chave secreta — só no servidor, nunca no bundle do cliente, nunca impressa nos logs.
• Verifique cada webhook: o Stripe pela assinatura HMAC (constructEvent), o Sepay pelo header de API Key Authorization: Apikey ....
• Exija HTTPS em produção; considere colocar o endpoint do webhook em uma allowlist de IP.
• Use apenas Checkout Sessions / PaymentIntents / SetupIntents; evite os antigos Sources/Tokens/Charges para reduzir o seu escopo de PCI. Se você tocar em um PAN cru, cai no balde complexo de conformidade com PCI — não faça isso.

Entrada em produção: o Stripe tem o próprio checklist de go-live (trocar para chaves live, configurar webhooks de produção). O Sepay exige aprovação de NAPAS QR/cartão, normalmente de 3 a 7 dias — reserve tempo para isso. Antes de publicar, faça mais uma passada de uma revisão de segurança e auditoria com o Claude Code para pegar vazamentos de chave e falhas de verificação.

Envie muito mais rápido com uma skill pronta (AgentKit)

Se você prefere não escrever cada handler à mão, existe um caminho mais rápido: a skill ak-payment-integration do AgentKit Engineer Kit. Essa skill já empacota os três gateways — SePay, Polar e Stripe — cobrindo checkout, verificação de webhook (com scripts prontos), QR, assinaturas e pedidos com múltiplos provedores, então o Claude Code só ativa e constrói em minutos, em vez de cavar na documentação de cada gateway.

Uma linha para evitar confusão: o AgentKit aqui é o kit para o Claude Code em agentkit.best (20% de desconto pelo link) (o CLI ak), não o AgentKit da OpenAI. O Engineer Kit custa $99 (o site não lista nenhuma cobrança recorrente). Se você quer ver o que essa skill realmente resolve, leia a análise detalhada do Engineer Kit e o que é o AgentKit antes de decidir — não compre por uma skill só se você precisa de um único fluxo.

Limites e cuidados quando você deixa a IA mexer com dinheiro

Pagamentos ficam perto de YMYL, então esta seção importa tanto quanto o código. Alguns limites firmes quando você deixa o Claude Code lidar com pagamentos:

• Sempre revise o código relacionado a dinheiro. Leia com atenção os cálculos de valores, as conversões de unidade e as condições que atualizam o status de um pedido.
• Não deixe o agente rodar comandos de produção ou reembolsos por conta própria. Mantenha o Claude Code em modo de teste/sandbox; você mesma aperta os comandos live depois de revisar.
• Verifique valores e unidades. O Stripe conta na menor unidade (centavos); o VND não tem casas decimais — é aqui que a IA costuma escorregar nas conversões.
• Teste bem os casos extremos do webhook (chegando duas vezes, assinatura errada, valor divergente) e guarde os logs para conciliação quando surgir uma disputa.

Resumo: a IA ajuda você a andar rápido, mas a responsabilidade pelo dinheiro ainda é sua. Velocidade não substitui uma revisão feita com a cabeça no lugar.

Perguntas frequentes (FAQ)

O Claude Code vai integrar os pagamentos completamente para mim?

Ele constrói a maior parte: lê o repositório, gera a rota de checkout, escreve o handler do webhook e escreve testes. Mas você ainda precisa revisar o código, se cadastrar no gateway, configurar as chaves de produção e apertar o comando de go-live. Como há dinheiro envolvido, a pessoa é quem dá a aprovação final.

Para clientes vietnamitas, devo escolher Stripe ou Sepay?

Para clientes do Vietnã pagando em VND, o Sepay combina melhor, graças ao VietQR/NAPAS, às transferências entre mais de 44 bancos e ao dinheiro caindo direto na sua conta bancária. O Stripe combina quando você vende internacionalmente e aceita cartão de crédito. Muitos apps rodam os dois em paralelo.

O que eu faço se o webhook nunca recebe uma transação?

Confira se o endpoint é público e HTTPS, se a verificação de assinatura/API Key está correta e se o handler retorna 2xx em menos de 5 segundos. O Sepay tenta de novo automaticamente até 7 vezes ao longo de aproximadamente 5 horas, então, se o seu handler for idempotente, uma retentativa mais tarde ainda registra tudo certo.

Como testo o fluxo de pagamento sem gastar dinheiro de verdade?

Use o modo de teste: o Stripe tem o Stripe CLI (stripe listen/stripe trigger) e cartões de teste; o Sepay tem um sandbox com chaves SP-TEST-*. Os dois deixam você simular transações e webhooks sem tocar em dinheiro real.

Consigo seguir este artigo se não sou boa de programação?

Você precisa de conhecimento básico de programação para ler e revisar os diffs que o Claude Code produz — como tem dinheiro em jogo, você não deveria dar merge em código que não entende. O Claude Code corta a quantidade de digitação manual, mas a capacidade de ler e entender o código continua essencial.

Como a skill ak-payment-integration é diferente de escrever à mão?

Escrever à mão te dá controle sobre cada linha, mas custa tempo cavando na documentação de três gateways. A skill ak-payment-integration empacota checkout, verificação de webhook, QR e assinaturas para SePay/Polar/Stripe, o que constrói mais rápido; em troca, você ainda deve revisar a saída, já que cada app tem a sua própria lógica de negócio.

Conclusão e próximos passos

Recapitulando os cinco passos: escolher um gateway (Stripe para internacional / Sepay para clientes do Vietnã), orientar o Claude Code com um CLAUDE.md, criar o checkout, escrever um webhook idempotente e, então, testar e reforçar antes de entrar no ar. Os pontos que decidem tudo são webhooks idempotentes e uma revisão humana, porque isto é dinheiro de verdade. Daqui, você pode seguir para construir uma API de backend completa ou apertar uma auditoria de segurança antes do lançamento.