Aparência
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, 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.
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étodo | Rota | O que faz |
|---|---|---|
POST | /banking/pix/transfers/lookup | Consulta a chave e abre a transferência (aguardando) |
POST | /banking/pix/transfers/key | Confirma a transferência por chave (PIN) |
POST | /banking/pix/transfers/bank-account | Transferência por dados bancários (PIN) |
GET | /banking/pix/transfers | Lista as transferências |
GET | /banking/pix/transfers/{id} | Detalhe de uma transferência |
GET | /banking/pix/recipients | Destinatários já usados (paginado) |
GET | /banking/pix/recipients/frequent | Destinatá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" }| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
keypix | string | Sim | CPF/CNPJ (com ou sem máscara), e-mail, celular (+55...) ou chave aleatória. Máx. 150 |
value | numeric | Não | ≥ 0. Se informado, já valida saldo, limite noturno e duplicidade |
message | string | Não | Má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(mesmointernal_id), em vez de criar outra. - 404
A chave Pix pesquisada não existe.: chave não encontrada no DICT. Um registro com statuserroé gravado. - 422: validação (
keypixausente; comvalue: 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" }| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
internal_id | integer | Sim | Transferência aguardando desta conta |
keypix | string | Sim | A mesma chave da consulta. Máx. 255 |
value | numeric | Sim | ≥ 0,01; saldo (menos a taxa) e limite noturno |
pin | string | Sim | PIN de 6 dígitos da conta |
message | string | Não | Má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).
| Status | Quando |
|---|---|
403 | PIN inválido. |
422 | internal_id de outra conta ou já processado; saldo; limite noturno; mesmo valor para o mesmo destinatário concluído na última hora |
500 | O 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"
}| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
bank_code | string | Sim | Código COMPE ou ISPB (ver GET /enums/banks) |
agency | string | Sim | Máx. 50 |
account | string | Sim | Com dígito. Máx. 50 |
beneficiary_name | string | Sim | Máx. 255 |
beneficiary_document | string | Sim | CPF/CNPJ. Máx. 20 |
amount | numeric | Sim | ≥ 0,01 |
pin | string | Sim | 6 dígitos |
message | string | Não | Má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.
| Status | Quando |
|---|---|
403 | PIN inválido. |
422 | Validação; mesmo valor para o mesmo documento concluído na última hora; limite noturno |
500 | Banco 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.
| Query | Descrição |
|---|---|
status | Um ou mais status separados por vírgula, ex.: concluido ou aguardando,erro. Sem o parâmetro, lista todos. Status desconhecido: 422 |
search | Nome, documento, chave, txid, endToEndId |
per_page | Itens por página (padrão 15) |
page | Pá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.
| Query | Descrição |
|---|---|
search | Chave, nome, banco, agência, conta ou documento |
per_page | Itens 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.