Pix pela API (/banking/pix)
Todas as operações de Pix que acontecem diretamente no banco da conta ficam agrupadas no prefixo /banking/pix: chaves, QR Code estático, pagamento de copia e cola e transferências (enviar).
Para receber um valor por Pix (copia e cola com valor), crie uma cobrança em POST /billing/charges com "payment_method": "PIX". Cliente e vencimento são opcionais. Boletos também são emitidos e cancelados por /billing/charges.
A referência técnica completa, com os campos de cada rota, está na documentação da API, seção Banking (Pix).
Autenticação
Todas as rotas exigem token e conta ativa:
Authorization: Bearer {token}
Content-Type: application/json
account: {account_id}O usuário do token precisa ter acesso à conta informada em account. Se não tiver, a resposta é 403.
Rotas
| Método | Rota | Para quê |
|---|---|---|
GET POST | /banking/pix/keys | Listar e incluir chaves Pix da conta (e-mail e celular exigem o código abaixo) |
POST | /banking/pix/keys/verification | Enviar o código de posse ao e-mail ou celular da conta |
GET DELETE | /banking/pix/keys/{chave} | Consultar e remover uma chave |
GET | /banking/pix/static-qrcode | Copia e cola estático da conta (sem valor) |
GET | /banking/pix/transfers | Listar transferências (filtro ?status=, ex.: concluido) |
POST | /banking/pix/transfers/lookup | Consultar a chave de destino |
POST | /banking/pix/transfers/key | Confirmar a transferência por chave (PIN) |
POST | /banking/pix/transfers/bank-account | Transferência por dados bancários (PIN) |
POST | /banking/pix/transfers/copy-paste/decode | Ler um copia e cola antes de pagar (recebedor, chave, valor) |
POST | /banking/pix/transfers/copy-paste | Pagar um copia e cola (PIN) |
GET | /banking/pix/transfers/{id} | Detalhe de uma transferência |
GET | /banking/pix/recipients | Destinatários já usados |
GET | /banking/pix/recipients/frequent | Destinatários frequentes |
Chaves Pix: código de posse e limite
Regras do Banco Central para as chaves da conta:
- Limite: até 5 chaves por conta de pessoa física e 20 de pessoa jurídica. Acima disso,
POST /banking/pix/keysresponde422.GET /banking/pix/keysinformameta.key_limitemeta.keys_count. - E-mail (
key_type: 2) e celular (key_type: 3): confirme a posse antes de incluir.POST /banking/pix/keys/verificationcom{ "key_type": 2 }envia um código de 6 dígitos ao e-mail (ou, por SMS, ao celular) cadastrado na conta. A resposta trazdata.ide o destino mascarado. O código vale 10 minutos.POST /banking/pix/keyscom{ "key_type": 2, "verification_id": "<data.id>", "code": "123456" }.
Código ausente, errado ou expirado → 422 (data.code). CPF/CNPJ (1) e aleatória (4) não precisam de código.
Evitar operação duplicada (Idempotency-Key)
As rotas que enviam Pix (transfers/key, transfers/bank-account e transfers/copy-paste) e as que criam cobrança (POST /billing/charges e POST /billing/charges/with-plan) aceitam o header opcional Idempotency-Key:
Idempotency-Key: 6f1c2e0a-3b8d-4c1e-9a77-0d5f2b9e4c11Gere um código novo (de preferência um UUID) para cada operação e repita o mesmo código se precisar tentar de novo (por exemplo, depois de um timeout). Assim, a operação é feita uma vez só:
- Mesmo código e mesmos dados: a API devolve a resposta da primeira vez (com o header
Idempotent-Replayed: true) e não envia outro Pix nem cria outra cobrança. - Mesmo código com dados diferentes:
422. - Mesmo código enquanto a primeira ainda está em andamento:
409. Se o409continuar, confira a transferência emGET /banking/pix/transfersantes de tentar com um código novo. - A primeira tentativa deu erro: o código fica livre para uma nova tentativa.
- Validade: o código vale por 30 dias, separado por conta e por rota.
Sem o header, nada muda.
Migração das rotas antigas
Mudança que quebra integrações (30/09/2026)
As rotas antigas de Pix foram removidas e agora respondem 404. Se a sua integração usa alguma delas, troque o caminho. O corpo e a resposta de cada rota não mudaram, só o endereço.
| Rota antiga | Rota nova |
|---|---|
/pix-keys e /pix-keys/{chave} | /banking/pix/keys e /banking/pix/keys/{chave} |
POST /quickpay/pix/create, /quickpay/pix/qrcode, /quickpay/pix/qrcode-fixo | POST /billing/charges (payment_method: PIX) |
GET /quickpay/pix/list | GET /billing/charges?payment_method=PIX |
GET /quickpay/pix/{txid} | GET /billing/charges/{id} |
GET /quickpay/pix/image | GET /banking/pix/static-qrcode |
POST /pix/qrcode/decode | POST /banking/pix/transfers/copy-paste/decode |
POST /pix/qrcode/pay | POST /banking/pix/transfers/copy-paste |
GET / POST /quickpay/withdraws | GET /banking/pix/transfers / POST /banking/pix/transfers/lookup |
POST /quickpay/withdraws/confirm | POST /banking/pix/transfers/key |
POST /quickpay/withdraws/bank | POST /banking/pix/transfers/bank-account |
GET /quickpay/withdraws/{id} | GET /banking/pix/transfers/{id} |
GET /quickpay/withdraws/recipients (e /frequent, /frequent/{id}) | GET /banking/pix/recipients (e /frequent, /frequent/{id}) |
Removidas sem substituto (rotas antigas específicas da Sicredi): /quickpay/saida-sicred, /quickpay/pix-out/dataBank, /quickpay/boleto-saida-sicred, /quickpay/pix/lookup, /quickpay/pixout/pix-key e /quickpay/pixout/pix-databank. Use as rotas de /banking/pix/transfers.
O pagamento de boletos de terceiros fica em /banking/boleto/payments.
Cobranças Pix e boletos em /billing/charges (02/10/2026)
Mudança que quebra integrações (02/10/2026)
As rotas /banking/pix/charges e o cadastro de boletos em /quickpay/boletos e /quickpay/boleto/* (criar, listar, consultar, PDF, cancelar, excluir) foram removidos e respondem 404. Tudo isso passou para /billing/charges.
| Rota removida | Use |
|---|---|
POST /banking/pix/charges | POST /billing/charges com "payment_method": "PIX" |
GET /banking/pix/charges | GET /billing/charges?payment_method=PIX |
GET /banking/pix/charges/{txid} | GET /billing/charges/{id} |
POST /quickpay/boletos | POST /billing/charges com BOLETO ou BOLEPIX (due_date no lugar de expiration_date) |
GET /quickpay/boletos | GET /billing/charges?payment_method=BOLETO,BOLEPIX |
GET /quickpay/boletos/{txid} | GET /billing/charges/{id} |
POST /quickpay/boletos/{txid}/pdf | GET /billing/charges/{id}/download-pdf |
POST /quickpay/boletos/cancel, DELETE /quickpay/boletos/{txid} | DELETE /billing/charges/{id} (dá baixa no boleto pendente no banco) |
A chave passa a ser o id da cobrança, e a resposta é a da cobrança (data.pix, data.boleto). Detalhes na documentação da API, página Cobranças Pix e boleto.
Pagamento de boletos em /banking/boleto/payments (03/10/2026)
Mudança que quebra integrações (03/10/2026)
O pagamento de boletos de terceiros saiu de /quickpay/boleto/*. As rotas antigas respondem 404.
| Rota antiga | Rota nova |
|---|---|
POST /quickpay/boleto/info-barcode | POST /banking/boleto/payments/decode |
POST /quickpay/boleto/payment-barcode | POST /banking/boleto/payments/pay (PIN) |
GET /quickpay/boleto/payments | GET /banking/boleto/payments |
GET /quickpay/boleto/payments/{id} | GET /banking/boleto/payments/{id} |
As respostas passam a vir no envelope padrão (data). O decode aceita a linha digitável com pontos e espaços. PIN inválido, saldo insuficiente e boleto já pago respondem 422. Disponível hoje só no banco Teste (Fidúcia ainda não implementa). Detalhes na documentação da API, página Banking — Pagamento de boletos.
Rotas de Pix (enviar) renomeadas (04/10/2026)
Mudança que quebra integrações (04/10/2026)
As rotas de envio de Pix foram reorganizadas em /banking/pix/transfers, e os destinatários foram para /banking/pix/recipients. As rotas antigas foram removidas. O corpo e a resposta de cada rota não mudaram, só o endereço.
| Rota antiga | Rota nova |
|---|---|
POST /banking/pix/transfers | POST /banking/pix/transfers/lookup |
POST /banking/pix/transfers/confirm | POST /banking/pix/transfers/key |
POST /banking/pix/transfers/bank-data | POST /banking/pix/transfers/bank-account |
POST /banking/pix/copy-paste/decode | POST /banking/pix/transfers/copy-paste/decode |
POST /banking/pix/copy-paste/pay | POST /banking/pix/transfers/copy-paste |
GET /banking/pix/transfers/recipients (e /frequent, /frequent/{id}) | GET /banking/pix/recipients (e /frequent, /frequent/{id}) |
GET /banking/pix/transfers e GET /banking/pix/transfers/{id} não mudaram. Junto com a mudança veio o header Idempotency-Key.
Ambiente de teste
Para testar sem movimentar dinheiro real, use uma conta na homologação da Fidúcia (sandbox). As rotas são as mesmas da produção; peça ao suporte uma conta de homologação.
Pix, chaves Pix, copia e cola, TED e pagamento de boletos funcionam para contas da Fidúcia, que é a única integração bancária.