Aparência
Banking — Pix copia e cola
Pagamento de Pix copia e cola (BR Code): prévia do código e pagamento com PIN. Para testar sem dinheiro real, use uma conta na homologação da Fidúcia (sandbox).
Autenticação na Fidúcia: estas rotas chamam a API de Contas com o login da própria conta (
POST /login, comcredentials.fiducia_passworde, para PJ,fiducia_operator_code). Sem esse login configurado, contas da Fidúcia recebem erro. Ver Fidúcia — autenticação por endpoint.
Estes endpoints exigem autenticação padrão da plataforma e conta ativa (Authorization: Bearer {token} + account: {account_id}).
Disponibilidade: o pagamento de copia e cola só funciona em contas cujo banco tem suporte a ele no driver. Hoje isso vale só para o banco Teste. Nos demais bancos, os dois endpoints abaixo retornam
422(Pagamento de Pix copia e cola não está disponível para o banco desta conta.).
Decodificar copia e cola (prévia)
POST /banking/pix/transfers/copy-paste/decode
Valida o código (estrutura EMV + CRC16) e devolve os dados do pagamento sem pagar. Use antes de pedir o PIN, para mostrar ao usuário quem vai receber e quanto.
json
{ "payload": "00020126540014br.gov.bcb.pix0132pagamentos@teste..." }200:
json
{
"code": 200,
"success": true,
"data": {
"pix_key": "pagamentos@teste.fastgivr.com.br",
"amount": 25.5,
"txid": "TESTEVALORFIXO0001",
"merchant_name": "JOAO TESTE PEREIRA",
"merchant_city": "SAO PAULO",
"description": null,
"receiver": {
"name": "Joao Teste Pereira",
"document": "11144477735",
"bank_name": "FIDUCIA SCMEPP LTDA",
"bank_code": "00000000",
"agency": "0001",
"account": "100003",
"account_digit": "3",
"account_type": "CORRENTE"
}
},
"message": "Pix copia e cola decodificado com sucesso."
}amount: null significa que o código não tem valor definido: quem paga escolhe o valor.
| Status | Quando |
|---|---|
422 | Código malformado ou com CRC inválido (Pix copia e cola inválido: ...), ou banco sem suporte |
404 | Código válido, mas a chave Pix não existe no DICT do banco |
Pagar copia e cola
POST /banking/pix/transfers/copy-paste
json
{
"payload": "00020126540014br.gov.bcb.pix0132pagamentos@teste...",
"value": 12.34,
"pin": "123456",
"message": "opcional, até 140 caracteres"
}Exige o header
Idempotency-Key(sem ele,428), que evita executar a mesma operação duas vezes. Ver Idempotência.
| Campo | Obrigatório | Regra |
|---|---|---|
payload | sim | Código copia e cola |
value | só quando o código não tem valor | Se o código tem valor fixo, value pode ser omitido; se enviado, precisa ser igual ao do código |
pin | sim | PIN de 6 dígitos da conta |
message | não | Mensagem para o recebedor |
Antes de pagar, a API valida o saldo disponível (saldo menos tax_pix_out) e o limite de envio Pix da conta (max_pix_out, e max_pix_out_night na janela noturna), com as mesmas regras do envio por chave.
Ao concluir, registra:
- um
pix_withdrawscom statusconcluidoe os dados do recebedor (key_pix= chave do código); - uma
transactiondo tipopix-outcom o valor negativo; - uma
transactiondo tipotaxa, se a conta tivertax_pix_out.
Response 201:
json
{
"code": 201,
"success": true,
"message": "Pix copia e cola pago com sucesso.",
"data": {
"txid": "6309daab-...",
"data": "2026-10-02 19:23:46",
"endToEndId": "72f8379a-...",
"valor": 4.5,
"pagador": { "nome": "Sua Conta", "documento": "...", "conta": { "...": "..." }, "banco": { "nome": "FIDUCIA SCMEPP LTDA", "codigo": "04307598" } },
"recebedor": {
"nome": "Loja Teste Comercio",
"documento": "11444777000161",
"conta": { "numero": "100005", "digito": "5", "tipo": "CORRENTE", "agencia": "0001" },
"banco": { "nome": "FIDUCIA SCMEPP LTDA", "codigo": "04307598" }
},
"internal_id": 14,
"pix_key": "5f2c1a7e-3b4d-4c8e-9a1f-7d6e5c4b3a21"
}
}internal_id é o id da transferência (consultável em GET /banking/pix/transfers/{id}).
| Status | Quando |
|---|---|
422 | PIN inválido, valor ausente em código sem valor, valor diferente do fixo, saldo insuficiente, acima do limite, código inválido ou banco sem suporte |
404 | Chave Pix do código não existe no DICT do banco |
500 | Banco recusou a transferência (nada é gravado) |
Testando sem dinheiro real
Use uma conta na homologação da Fidúcia (sandbox): os códigos copia e cola gerados nela não movimentam dinheiro real.