Quickstart

Da conta criada ao webhook de pagamento confirmado. Quatro passos, menos de 5 minutos.

Menos de 5 minutos

1. Criar a conta#

Crie sua conta gratuita na Pitra e conclua o cadastro da loja. Não há mensalidade: você paga por transação recebida.

2. Gerar a API Key#

No painel, abra a Central da API e gere uma chave. Use sk_test_* em desenvolvimento e sk_live_* em produção. A chave secreta aparece uma única vez.

Variável de ambiente

PITRA_API_KEY=sk_test_...

A chave secreta nunca deve ir para o frontend. Todas as chamadas partem do seu servidor.

3. Primeira cobrança Pix#

A resposta traz o Pix Copia e Cola e o QR Code dinâmico prontos para exibir ao pagador.

curl -X POST https://pitra.com.br/api/public/v1/payments/pix \
  -H "Authorization: Bearer $PITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{"amount":49.9,"description":"Pedido 1042","external_id":"pedido-1042","expires_in":1800,"customer":{"email":"cliente@exemplo.com","whatsapp":"11999998888","document":"12345678909"}}'

4. Receber o webhook#

Registre o endpoint que receberá pix.paid e pix.expired:

curl -X POST https://pitra.com.br/api/public/v1/webhooks \
  -H "Authorization: Bearer $PITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{"url":"https://seu-sistema.com/webhooks/pitra","events":["pix.paid","pix.expired"]}'

Valide a assinatura Pitra-Signature com o corpo bruto antes de processar:

TypeScript

import { verifyWebhook } from "@pitra/sdk";

// rawBody é o corpo bruto, lido antes de qualquer parser JSON.
const evento = await verifyWebhook({ headers, rawBody, secret: process.env.PITRA_WEBHOOK_SECRET! });

if (evento.type === "pix.paid") {
  // libere o pedido — deduplique pelo evento.id
}

Próximos passos#

Playground — gere o exemplo na sua linguagem.
SDK oficial — Express, Fastify, NestJS, Next.js, Bun, Workers e Vercel.
Instructions para agentes — deixe a IA gerar a integração correta.