Começo rápido
Gere um Pix de teste, simule o pagamento e receba o webhook, sem dinheiro real.
Em 5 minutos você faz o caminho completo de um pagamento no modo teste. Nada aqui movimenta dinheiro, e o modo teste não precisa de verificação da conta.
Usando um agente de IA?
Copie as instruções e cole no seu agente (Claude Code, Cursor, Codex…). Ele integra a WysePay do jeito recomendado: lendo esta documentação, com a chave no servidor e o webhook validado.
Crie uma chave de teste
- Entre no painel e ligue Modo teste, no topo da tela.
- Vá em Desenvolvedores → Chaves de API e clique em Criar chave.
- Copie a chave. Ela começa com
wyp_test_e só aparece uma vez.
Gere um Pix
Troque wyp_test_sua_chave pela chave que você copiou.
curl -X POST https://api.wysepay.com.br/api/v1/charges/pix \
-H "x-api-key: wyp_test_sua_chave" \
-H "Content-Type: application/json" \
-H "idempotency-key: pedido-1042" \
-d '{
"amountCents": 8990,
"description": "Pedido #1042",
"customer": {
"name": "Ana Souza",
"email": "[email protected]",
"phone": "11912345678",
"documentType": "CPF",
"document": "12345678909"
},
"metadata": { "orderId": "1042" }
}'A resposta é a cobrança criada, com o código Pix para mostrar ao cliente:
{
"id": "txn_01k6g8m2v4x7z9b3c5d7f9h0j2",
"status": "WAITING_PAYMENT",
"amountCents": 8990,
"feeCents": 90,
"netAmountCents": 8900,
"description": "Pedido #1042",
"pix": { "copyPaste": "…", "qrCode": "…" },
"customer": { "id": "cus_…", "name": "Ana Souza", "documentType": "CPF", "document": "12345678909", "…": "…" },
"metadata": { "orderId": "1042" },
"livemode": false,
"expiresAt": "2026-10-04T16:00:00.000Z",
"paidAt": null,
"…": "…"
}O CPF precisa ser válido
A API confere os dígitos do CPF ou CNPJ, inclusive no modo teste. Use um CPF válido, como o 123.456.789-09 dos exemplos.
Cadastre um webhook
No painel, ainda no modo teste, vá em Desenvolvedores → Webhooks, cadastre a URL do seu servidor e marque o evento transaction.paid.
Ainda não tem um servidor no ar? Use um serviço como o webhook.site para ver os eventos chegando.
Simule o pagamento
No modo teste ninguém paga de verdade: você simula. Use o id da cobrança:
curl -X POST https://api.wysepay.com.br/api/v1/sandbox/transactions/txn_01k6g8m2v4x7z9b3c5d7f9h0j2/pay \
-H "x-api-key: wyp_test_sua_chave"A cobrança passa para PAID e o webhook transaction.paid chega na sua URL, igual a um pagamento real.
Vá para produção
- Complete o perfil e a verificação da conta no painel (veja Criar conta e liberar produção).
- Desligue o modo teste e crie uma chave de produção. Ela começa com
wyp_. - Cadastre o webhook de produção. Endpoints de teste e de produção são separados.
- Troque a chave no seu servidor. O código é o mesmo.
Próximos passos
- Validar a assinatura dos webhooks, antes de confiar num evento.
- Evitar cobranças duplicadas com a
idempotency-key. - Links de pagamento, se você não quer montar a tela de pagamento.