Primeira cobrança em 5 passos
Tudo aqui acontece no ambiente de teste: nenhum dinheiro de verdade se move, e os webhooks chegam ao seu servidor como chegariam em produção.
Os passos
- Crie a contaO cadastro é público, no painel. Enquanto a empresa está em cadastro ou em análise, o ambiente de teste já funciona; produção libera depois da aprovação.
- Gere uma chave de testeNo painel, em Desenvolvedores › Chaves de API, crie uma chave
sk_test_comchargesemwrite. Criar a chave pede o código do app autenticador, e ela aparece uma única vez: guarde numa variável de ambiente do servidor. Mais em Chaves de API e escopos. - Crie a cobrança
POST /v1/chargescomamount,currencye umaIdempotency-Key. A resposta traz ocheckoutUrle, emattempt.instructions.emv, o PIX copia e cola. Detalhes em Criar cobrança. - Pague no testeAbra o
checkoutUrle use "Simular pagamento" (o mesmo simulador fica no painel, em Desenvolvedores › Ambiente de teste). O código PIX de teste não é aceito por nenhum banco. Veja Ambiente de teste. - Confirme pelo webhook e pela APICadastre um endpoint de teste em Desenvolvedores › Webhooks, confira o
X-Signaturee trate ocharge.paid. Na dúvida,GET /v1/charges/:idmostra o status de agora. Veja Configurar endpoint.
Depois do teste
- Com o cadastro aprovado, gere uma chave
sk_live_. Antes disso, o painel não cria chave de produção, e uma chavesk_live_de empresa que não está ativa volta403 MERCHANT_NOT_ACTIVE. - Endpoints de webhook são por ambiente: cadastre de novo o de produção, com o segredo novo.
- Em produção, mande nome e CPF/CNPJ de quem paga: há provedores de PIX que exigem.
- Libere o pedido pelo webhook ou pela consulta, nunca pelo retorno do cliente ao seu site.
Antes de ir ao ar, vale ler Idempotency-Key e Tentativas e cabeçalhos.