Skip to content

Banking — Transferências Pix (enviar) ​

Envio de Pix a partir do saldo da conta, por chave Pix (em duas etapas) ou por dados bancários. Para pagar um código copia e cola, veja Pix copia e cola. Autenticação e headers: Banking — visão geral.

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.

Todo envio desconta o valor mais a taxa tax_pix_out da conta e respeita o saldo. O limite da conta (max_pix_out, e max_pix_out_night das 20h às 6h) é conferido só na janela noturna neste fluxo.

Os exemplos abaixo são respostas da API, com campos longos abreviados (...).

MétodoRotaO que faz
POST/banking/pix/transfers/lookupConsulta a chave e abre a transferência (aguardando)
POST/banking/pix/transfers/keyConfirma a transferência por chave (PIN)
POST/banking/pix/transfers/bank-accountTransferência por dados bancários (PIN)
GET/banking/pix/transfersLista as transferências
GET/banking/pix/transfers/{id}Detalhe de uma transferência
GET/banking/pix/recipientsDestinatários já usados (paginado)
GET/banking/pix/recipients/frequentDestinatários mais usados
GET/banking/pix/recipients/frequent/{id}Um destinatário frequente

POST /banking/pix/transfers/lookup ​

Etapa 1 do Pix por chave. Consulta o recebedor da chave no banco e abre uma transferência com status aguardando. Não movimenta dinheiro.

Body:

json
{ "keypix": "+5511999990001", "value": 50.00, "message": "opcional" }
CampoTipoObrigatórioRegras
keypixstringSimCPF/CNPJ (com ou sem máscara), e-mail, celular (+55...) ou chave aleatória. Máx. 150
valuenumericNão≥ 0. Se informado, já valida saldo, limite noturno e duplicidade
messagestringNãoMáx. 255

Response 200 (sem envelope code/success). Junta os dados da transferência aberta, o comprovante da consulta e internal_id:

json
{
    "data": {
        "id": 12,
        "internal_id": 12,
        "status": "aguardando",
        "name": "Ana Teste Oliveira",
        "document": "39053344705",
        "bank_code": "00000000",
        "branch": "0001",
        "account_number": "100004",
        "account_type": "POUPANCA",
        "key_pix": "+5511999990001",
        "value": 0,
        "txid": "TESTE24353d33-...",
        "endtoendid": "a83603fb-...",
        "endToEndId": "a83603fb-...",
        "valor": 0,
        "pagador": { "nome": "Sua Conta", "documento": "...", "conta": { "numero": "...", "agencia": "..." }, "banco": { "nome": "FIDUCIA SCMEPP LTDA", "codigo": "04307598" } },
        "recebedor": {
            "nome": "Ana Teste Oliveira",
            "documento": "39053344705",
            "conta": { "numero": "100004", "digito": "4", "tipo": "POUPANCA", "agencia": "0001" },
            "banco": { "nome": "FIDUCIA SCMEPP LTDA", "codigo": "04307598" }
        },
        "account_balance": 833.16,
        "scheduled_at": "2026-10-02T22:23:45.894582Z",
        "created_at": "2026-10-02T22:23:45.000000Z"
    }
}

Use data.internal_id na confirmação.

  • Reaproveitamento: a mesma chave CPF/CNPJ (ou de um favorecido já salvo) consultada de novo em até 1 hora, sem confirmação, devolve a mesma transferência aguardando (mesmo internal_id), em vez de criar outra.
  • 404 A chave Pix pesquisada não existe.: chave não encontrada no DICT. Um registro com status erro é gravado.
  • 422: validação (keypix ausente; com value: saldo, limite noturno ou consulta igual na última hora).

POST /banking/pix/transfers/key ​

Etapa 2 do Pix por chave. Executa a transferência aberta na etapa 1.

Exige o header Idempotency-Key (sem ele, 428), que evita executar a mesma operação duas vezes. Ver Idempotência.

Body:

json
{ "internal_id": 12, "keypix": "+5511999990001", "value": 3.21, "pin": "123456", "message": "Exemplo" }
CampoTipoObrigatórioRegras
internal_idintegerSimTransferência aguardando desta conta
keypixstringSimA mesma chave da consulta. Máx. 255
valuenumericSim≥ 0,01; saldo (menos a taxa) e limite noturno
pinstringSimPIN de 6 dígitos da conta
messagestringNãoMáx. 140

Response 201:

json
{
    "code": 201,
    "success": true,
    "message": "Transferência Pix realizada com sucesso",
    "data": {
        "txid": "TESTE24353d33-...",
        "data": "2026-10-02 19:23:45",
        "endToEndId": "a83603fb-...",
        "valor": 3.21,
        "pagador": { "nome": "Sua Conta", "documento": "...", "conta": { "...": "..." }, "banco": { "nome": "FIDUCIA SCMEPP LTDA", "codigo": "04307598" } },
        "recebedor": {
            "nome": "Ana Teste Oliveira",
            "documento": "39053344705",
            "conta": { "numero": "100004", "digito": "4", "tipo": "POUPANCA", "agencia": "0001" },
            "banco": { "nome": "FIDUCIA SCMEPP LTDA", "codigo": "04307598" }
        }
    }
}

A transferência passa para concluido, e são lançados no extrato o pix-out e a taxa (se houver).

StatusQuando
403PIN inválido.
422internal_id de outra conta ou já processado; saldo; limite noturno; mesmo valor para o mesmo destinatário concluído na última hora
500O banco recusou a transferência. Nada é debitado

POST /banking/pix/transfers/bank-account ​

Pix por dados bancários, em uma etapa (sem consulta prévia do titular).

Exige o header Idempotency-Key (sem ele, 428), que evita executar a mesma operação duas vezes. Ver Idempotência.

Body:

json
{
    "bank_code": "341",
    "agency": "1234",
    "account": "56789-0",
    "beneficiary_name": "Carlos Destino",
    "beneficiary_document": "11144477735",
    "amount": 7.65,
    "pin": "123456",
    "message": "opcional"
}
CampoTipoObrigatórioRegras
bank_codestringSimCódigo COMPE ou ISPB (ver GET /enums/banks)
agencystringSimMáx. 50
accountstringSimCom dígito. Máx. 50
beneficiary_namestringSimMáx. 255
beneficiary_documentstringSimCPF/CNPJ. Máx. 20
amountnumericSim≥ 0,01
pinstringSim6 dígitos
messagestringNãoMáx. 255

Response 200 (sem envelope code/success):

json
{
    "data": {
        "id": 13,
        "name": "Carlos Destino",
        "document": "11144477735",
        "bank_code": "60701190",
        "branch": "1234",
        "account_number": "56789-0",
        "account_type": "CORRENTE",
        "status": { "value": "concluido", "title": "Pago", "description": "O saque foi processado e pago com sucesso." },
        "key_pix": null,
        "value": 7.65,
        "txid": "50afbaa9-...",
        "endtoendid": "02b217b2-...",
        "scheduled_at": "2026-10-02T22:23:45.972431Z",
        "message": null
    },
    "transaction": {
        "id": 18,
        "txid": "50afbaa9-...",
        "endtoendid": "02b217b2-...",
        "value": -7.65,
        "status": 1,
        "type": { "id": 2, "slug": "pix-out", "name": "Pix Out" },
        "...": "..."
    }
}

transaction é o lançamento pix-out deste Pix no extrato. A taxa, quando houver, é lançada à parte.

StatusQuando
403PIN inválido.
422Validação; mesmo valor para o mesmo documento concluído na última hora; limite noturno
500Banco não encontrado em bank_code, ou recusa do banco

GET /banking/pix/transfers ​

Lista paginada das transferências da conta, das mais recentes para as mais antigas.

QueryDescrição
statusUm ou mais status separados por vírgula, ex.: concluido ou aguardando,erro. Sem o parâmetro, lista todos. Status desconhecido: 422
searchNome, documento, chave, txid, endToEndId
per_pageItens por página (padrão 15)
pagePágina

Sem filtro, a lista inclui mais do que os Pix enviados:

  • aguardando: a chave foi consultada, mas a transferência não foi confirmada;
  • erro: a consulta falhou (ex.: chave inexistente);
  • concluido: o Pix foi enviado.

Para mostrar só os envios, use ?status=concluido (registros antigos podem ter paid ou 1).

Response 200 (GET /banking/pix/transfers?status=concluido&per_page=2):

json
{
    "data": [
        {
            "id": 12,
            "name": "Ana Teste Oliveira",
            "document": "39053344705",
            "bank_code": "00000000",
            "branch": "0001",
            "account_number": "100004",
            "account_type": "POUPANCA",
            "status": { "value": "concluido", "title": "Pago", "description": "O saque foi processado e pago com sucesso." },
            "key_pix": "+5511999990001",
            "value": 3.21,
            "txid": "TESTE24353d33-...",
            "endtoendid": "a83603fb-...",
            "scheduled_at": "2026-10-02 19:23:45",
            "message": "Exemplo"
        }
    ],
    "meta": { "total": 9, "page": 1, "limit": 2, "total_pages": 5, "has_next_page": true, "has_prev_page": false }
}

GET /banking/pix/transfers/{id} ​

Uma transferência da conta ({id} numérico) e o lançamento correspondente no extrato (transaction, ou null).

Response 200:

json
{
    "data": { "id": 12, "name": "Ana Teste Oliveira", "status": { "value": "concluido", "title": "Pago" }, "value": 3.21, "...": "mesmos campos da listagem" },
    "transaction": {
        "id": 16,
        "datetime": "2026-10-02 19:23:45",
        "txid": "TESTE24353d33-...",
        "endtoendid": "a83603fb-...",
        "value": -3.21,
        "status": 1,
        "balance": 829.95,
        "type": { "id": 2, "slug": "pix-out", "name": "Pix Out" }
    }
}

404: transferência inexistente ou de outra conta.


GET /banking/pix/recipients ​

Destinatários que já receberam Pix da conta (pix_recipients), do mais usado para o menos usado (count, depois last_used_at). Paginação padrão do Laravel (sem envelope). Desde 14/10/2026 não agrupa mais por cliente: cada item é um destinatário.

QueryDescrição
searchChave, nome, banco, agência, conta ou documento
per_pageItens por página (padrão 15)

Response 200 (?per_page=1):

json
{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "account_id": 3,
            "pix_key": "",
            "name": "Carlos Destino",
            "document": "11144477735",
            "bank_name": "FIDUCIA SCMEPP LTDA",
            "bank_code": "60701190",
            "branch": "1234",
            "account": "56789-0",
            "account_type": "CORRENTE",
            "count": 2,
            "last_used_at": "2026-10-02T22:23:45.000000Z"
        }
    ],
    "per_page": 1,
    "total": 2,
    "last_page": 2,
    "next_page_url": "https://.../banking/pix/recipients?page=2"
}

GET /banking/pix/recipients/frequent ​

Até 10 destinatários mais usados (count decrescente). São gravados a cada Pix por chave ou por dados bancários concluído; o copia e cola não entra na lista. Query: search (chave, nome ou documento).

Response 200:

json
{
    "code": 200,
    "success": true,
    "message": "Destinatários frequentes recuperados com sucesso.",
    "data": [
        {
            "id": 2,
            "pix_key": "+5511999990001",
            "name": "Ana Teste Oliveira",
            "document": "39053344705",
            "bank_name": "FIDUCIA SCMEPP LTDA",
            "bank_code": "00000000",
            "branch": "0001",
            "account": "100004-4",
            "account_type": "POUPANCA",
            "count": 3,
            "last_used_at": "2026-10-02T22:23:45.000000Z"
        }
    ]
}

Destinatário por dados bancários: pix_key vem vazio, e bank_code, branch e account vêm preenchidos.


GET /banking/pix/recipients/frequent/{id} ​

Um destinatário frequente da conta, no mesmo formato de cada item acima, dentro do envelope code/success/data. 404: inexistente ou de outra conta.