Guia para desenvolvedores

API Pix para desenvolvedores: do token ao primeiro Pix em três passos

A integração mais comum cabe em três passos: pegar uma chave, trocar por um token e chamar poucas rotas. O desenho segue o das APIs de Pix mais usadas, então quem já integrou antes reconhece o caminho.

Abrir conta Falar com o time

Passo 1: crie a chave de API

No painel, abra API, toque em Nova chave e escolha Sandbox para testar ou Produção para operar. O atalho Integração completa marca saldo, extrato, consultas, cobrar por Pix, enviar Pix e transferir. O painel mostra o Client ID, o Client Secret (que aparece uma vez, guarde) e a URL base.

Passo 2: troque a chave por um token

Faça POST /oauth/token com o Client ID e o Client Secret. A resposta traz um token de 1 hora, que você manda no cabeçalho Authorization: Bearer. Peça outro quando faltar pouco ou ao receber 401. O que o token pode fazer é definido pelas permissões da chave.

Passo 3: chame as rotas que você precisa

Cobrar por Pix
PUT /cob/{txid} com valor e validade. A resposta traz o pixCopiaECola. Libere o pedido só quando a cobrança estiver CONCLUIDA.
Consultar a cobrança
GET /cob/{txid} devolve o status: ATIVA (aguardando), CONCLUIDA (paga) ou REMOVIDA_PELO_PSP (vencida).
Enviar Pix
POST /pix/payments/dict (chave) ou /pix/payments/qrc (copia e cola), sempre com x-idempotency-key. A resposta é 202 com PROCESSING; o desfecho chega por webhook.
Saldo e extrato
GET /accounts/balances e GET /accounts/transactions.
Webhooks
POST /webhooks/{tipo} com receive, transfer ou cashout. Cada entrega vem com o cabeçalho x-webhook-signature, o HMAC-SHA256 de timestamp.corpo com o segredo do destino.

Antes de ir para produção

Teste no sandbox: pague a cobrança por comando, force uma falha de Pix e confira o aviso. Trate idempotência em todo pagamento e valide a assinatura dos webhooks. Quando tudo funcionar, crie a chave de Produção e troque o Client ID e o Client Secret: o código não muda. Detalhes na documentação.

Perguntas frequentes

Como é a autenticação da API?

POST /oauth/token troca o Client ID e o Client Secret por um token de 1 hora, enviado em Authorization: Bearer. As permissões da chave definem o que o token pode fazer.

Como evito pagar duas vezes?

Mande x-idempotency-key (1 a 50 letras e números) em todo pagamento. Repetir a mesma chave devolve o mesmo pagamento, sem novo envio.

Como sei que o cliente pagou?

Pelo webhook receive ou consultando GET /cob/{txid} até CONCLUIDA. Prefira o webhook.

A API usa certificado de cliente (mTLS)?

É opcional por padrão. Se a conta tiver a trava ligada, a chamada precisa do certificado, e sem ele a resposta é 403 certificate_required.

O sandbox tem a mesma URL?

Sim. O sandbox usa a mesma URL base e as mesmas rotas, mas com uma chave de teste e dinheiro de mentira.