Skip to content

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, com credentials.fiducia_password e, 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.

StatusQuando
422Código malformado ou com CRC inválido (Pix copia e cola inválido: ...), ou banco sem suporte
404Có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.

CampoObrigatórioRegra
payloadsimCódigo copia e cola
valuesó quando o código não tem valorSe o código tem valor fixo, value pode ser omitido; se enviado, precisa ser igual ao do código
pinsimPIN de 6 dígitos da conta
messagenãoMensagem 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_withdraws com status concluido e os dados do recebedor (key_pix = chave do código);
  • uma transaction do tipo pix-out com o valor negativo;
  • uma transaction do tipo taxa, se a conta tiver tax_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}).

StatusQuando
422PIN 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
404Chave Pix do código não existe no DICT do banco
500Banco 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.