Primeiros passos
Do token à primeira cobrança Pix, com as respostas reais de cada etapa.
Execute este roteiro a partir do seu backend. Em seis passos você vai das credenciais até uma cobrança Pix confirmada:
| Passo | Você faz | Recebe |
|---|---|---|
| 1 | Guarda clientId e clientSecret no servidor | — |
| 2 | POST /resource/auth/token | accessToken, válido por expiresIn segundos |
| 3 | Envia Authorization: Bearer <seu-token> | Acesso às demais operações |
| 4 | GET /resource/wallets | walletId e saldo disponível |
| 5 | POST /payment/pix/qrcode | Pix copia e cola, transação em awaiting_payment |
| 6 | GET /resource/transactions/external-id/{externalId} | completed quando o pagador pagar |
Os passos 1 a 4 e o 6 só leem dados. O passo 5 cria uma cobrança real, que só movimenta dinheiro se alguém pagar.
1. Guarde suas credenciais
Use o clientId e o clientSecret da credencial de integração da sua organização. Guarde ambos no servidor, nunca no navegador ou no aplicativo.
2. Emita o token
Use data.accessToken nas próximas chamadas e emita outro token antes de expiresIn segundos. Não registre o segredo nem o token em logs.
3. Autorize as chamadas
4. Encontre a sua carteira
Guarde o id da carteira (walletId). Para conferir o saldo:
data.balances[].available é o valor disponível, em reais.
5. Gere a primeira cobrança
amounté em reais:10.5cobra R$ 10,50. Os dados do pagador vão eminfo.
A carteira precisa ter uma conta de recebimento ativa vinculada. Sem conta vinculada, a resposta é
422comtypeterminado em/wallet-without-receiving-account; com a conta inativa ou bloqueada,403comdetail"This account is inactive or blocked". Veja Fluxo Pix.
A resposta 202 traz o Pix copia e cola em data.payload.qrCode e a transação em awaiting_payment.
6. Confirme pelo externalId
Quando o pagador pagar, data.status passa a completed. Em produção, receba essa mudança por webhook em vez de consultar em laço.