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:

http

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/keys responde 422. GET /banking/pix/keys informa meta.key_limit e meta.keys_count.
E-mail (key_type: 2) e celular (key_type: 3): confirme a posse antes de incluir.
1. POST /banking/pix/keys/verification com { "key_type": 2 } envia um código de 6 dígitos ao e-mail (ou, por SMS, ao celular) cadastrado na conta. A resposta traz data.id e o destino mascarado. O código vale 10 minutos.
2. POST /banking/pix/keys com { "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:

http

Idempotency-Key: 6f1c2e0a-3b8d-4c1e-9a77-0d5f2b9e4c11

Gere 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 o 409 continuar, confira a transferência em GET /banking/pix/transfers antes 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.

Não mudaram: links de pagamento e o pagamento de boletos de terceiros continuam em /quickpay.

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 (banco Teste)

Contas do banco Teste simulam o Pix sem movimentar dinheiro real. Só as chaves abaixo existem; qualquer outra responde 404 (chave não encontrada).

Tipo	Chave	Recebedor
CPF	`52998224725`	Maria Teste da Silva
CNPJ	`11222333000181`	Empresa Teste LTDA
E-mail	`pagamentos@teste.fastgivr.com.br`	Joao Teste Pereira
Celular	`+5511999990001`	Ana Teste Oliveira
Aleatória	`5f2c1a7e-3b4d-4c8e-9a1f-7d6e5c4b3a21`	Loja Teste Comercio
Recusa	`recusado@teste.fastgivr.com.br`	é encontrada na consulta, mas a transferência é recusada (para testar a tela de erro)

Copia e colas de teste:

Valor fixo (R$ 25,50):

00020126540014br.gov.bcb.pix0132pagamentos@teste.fastgivr.com.br520400005303986540525.505802BR5918JOAO TESTE PEREIRA6009SAO PAULO62220518TESTEVALORFIXO00016304C12D

Sem valor (quem paga informa):

00020126580014br.gov.bcb.pix01365f2c1a7e-3b4d-4c8e-9a1f-7d6e5c4b3a215204000053039865802BR5919LOJA TESTE COMERCIO6009SAO PAULO62070503***630431D6

Recusado (R$ 10,00):

00020126520014br.gov.bcb.pix0130recusado@teste.fastgivr.com.br520400005303986540510.005802BR5918RECEBEDOR RECUSADO6009SAO PAULO62210517TESTERECUSADO000163042597

O pagamento de copia e cola está disponível hoje apenas no banco Teste. Nos demais bancos, copy-paste/decode e copy-paste/pay respondem 422 ("não disponível para o banco desta conta").

Pix pela API (/banking/pix) ​

Autenticação ​

Rotas ​

Chaves Pix: código de posse e limite ​

Evitar operação duplicada (Idempotency-Key) ​

Migração das rotas antigas ​

Cobranças Pix e boletos em /billing/charges (02/10/2026) ​

Pagamento de boletos em /banking/boleto/payments (03/10/2026) ​

Rotas de Pix (enviar) renomeadas (04/10/2026) ​

Ambiente de teste (banco Teste) ​