Skip to main content
Este guia vai até o fim: chave, cobrança, pagamento simulado e webhook recebido. Tudo em sandbox, então nada aqui movimenta dinheiro.

Gere uma chave de sandbox

Entre no painel, abra API e Desenvolvedores e gere uma chave de sandbox. Ela começa com ps_test_.A chave inteira aparece uma única vez, na hora da criação. Se perder, revogue e gere outra. Cada conta pode manter até 10 chaves ativas.
Chave de API é credencial de servidor. Ela nunca deve aparecer em JavaScript de navegador, app mobile, repositório público ou print de tela.

Crie a cobrança

O endpoint mais direto é POST /v1/charges: valor livre, sem precisar cadastrar produto antes.
A resposta vem assim:
Resposta 201
Guarde o paymentId junto do seu pedido. É por ele que você vai reconciliar tudo depois.
Quer amarrar a cobrança ao seu banco de dados sem tabela auxiliar? Use metadata. Ele volta intacto no webhook e na consulta, então dá pra guardar ali o id do pedido.

Mostre o PIX pro cliente

São dois caminhos, e você normalmente oferece os dois na mesma tela:Se preferir gerar o QR você mesmo, use qualquer biblioteca de QR Code passando o brCode como conteúdo. O resultado é o mesmo.
Cobrança PIX expira em 30 minutos (expiresAt). Depois disso o código para de funcionar e o status vira expired. Se o cliente sumiu e voltou, crie outra.
Você está em sandbox, então esse brCode é falso: vem como SANDBOX_PIX_... e nenhum banco reconhece. Serve pra você montar a tela; quem confirma o pagamento é o passo seguinte.

Simule o pagamento

Em sandbox ninguém vai pagar de verdade, então você marca como pago na mão:
Isso muda o status para paid e dispara o webhook na sua callbackUrl, igualzinho ao que acontece em produção. Não passa por aprovação de ninguém: é essa chamada e pronto.
Para pagamentos criados em POST /v1/payments o endpoint é /v1/sandbox/payments/{paymentId}/simulate-paid. A diferença é só o recurso.

Receba o webhook

A gente faz POST na sua URL com o corpo do evento e o header X-Webhook-Signature:
Antes de liberar qualquer coisa pro cliente, valide a assinatura. A sua URL é pública, então qualquer pessoa consegue mandar um JSON dizendo "status": "paid".Sem servidor exposto ainda? Use um túnel local (ngrok http 3000, cloudflared tunnel) ou um coletor tipo webhook.site só pra ver o payload chegando.

Confirme pela API

Webhook é notificação, não fonte da verdade. Antes de entregar o produto, confirme:
Se o status vier paid e o amountCents bater com o que você cobrou, pode liberar.

Passando pra produção

Troque ps_test_ por ps_live_. Só isso. Nenhuma URL muda, nenhum parâmetro muda. Antes de virar a chave, dá uma passada em Antes de ir pra produção.

Vender produto cadastrado

Cadastre o preço uma vez e cobre por productId.

Entregar automaticamente

Chave, conta ou link liberado no instante do pagamento.