Transferência PIX

Visão Geral

O endpoint POST /dict/pix inicia uma transferência PIX para a chave informada. A chave pode ser CPF, CNPJ, e-mail, telefone ou EVP (chave aleatória).

Este endpoint segue a especificação do Banco Central para transferências PIX via DICT (Diretório de Identificadores de Contas Transacionais).

Endpoint

POST /dict/pix

Autenticação

string

obrigatório

Token Bearer obtido via /oauth/token.

string

obrigatório

Identificador único da requisição para suporte a idempotência. Deve ser um UUID v4.Exemplo: 550e8400-e29b-41d4-a716-446655440000

Request Body

string

obrigatório

Chave PIX de destino. Pode ser:

CPF: 11 dígitos numéricos
CNPJ: 14 dígitos numéricos
E-mail: endereço de e-mail válido
Telefone: +55DDDNUMERO (ex: +5511999999999)
EVP: Chave aleatória (UUID)

string

Documento do credor (CPF ou CNPJ). Obrigatório quando priority = HIGH para validação instantânea.

string

padrão:"NORM"

Prioridade do processamento:

HIGH: Processado instantaneamente (requer creditorDocument)
NORM: Processamento normal na fila

string

Mensagem que acompanha a transferência PIX. Será exibida para o destinatário.

string

Fluxo de pagamento (opcional). Utilizado para categorização interna.

number

padrão:600

Tempo máximo em segundos que a operação pode permanecer na fila antes de ser cancelada.

Mínimo: 1 segundo
Máximo: 10800 segundos (3 horas)
Padrão: 600 segundos (10 minutos)

object

obrigatório

Dados do pagamento.

Mostrar Propriedades

string

padrão:"BRL"

Moeda da transação. Atualmente apenas BRL é suportado.

number

obrigatório

Valor da transferência. Número com até 2 casas decimais.Exemplo: 100.50

Diferente do endpoint /cob, aqui o valor é number, não string.

array

Lista de códigos ISPB para os quais pagamentos não serão permitidos. Útil para bloquear transferências para instituições específicas.Exemplo: ["12345678", "87654321"]

Request

curl -X POST https://api.public.firebanking.com.br/dict/pix \
  -H "Authorization: Bearer <token>" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "12345678909",
    "creditorDocument": "12345678909",
    "priority": "NORM",
    "description": "Pagamento referente a NF 12345",
    "expiration": 600,
    "payment": {
      "currency": "BRL",
      "amount": 100.50
    }
  }'

const response = await fetch('https://api.public.firebanking.com.br/dict/pix', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'x-idempotency-key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pixKey: '12345678909',
    creditorDocument: '12345678909',
    priority: 'NORM',
    description: 'Pagamento referente a NF 12345',
    expiration: 600,
    payment: {
      currency: 'BRL',
      amount: 100.50,
    },
  }),
});

const transfer = await response.json();

import requests
import uuid

response = requests.post(
    'https://api.public.firebanking.com.br/dict/pix',
    headers={
        'Authorization': f'Bearer {token}',
        'x-idempotency-key': str(uuid.uuid4()),
        'Content-Type': 'application/json',
    },
    json={
        'pixKey': '12345678909',
        'creditorDocument': '12345678909',
        'priority': 'NORM',
        'description': 'Pagamento referente a NF 12345',
        'expiration': 600,
        'payment': {
            'currency': 'BRL',
            'amount': 100.50,
        },
    }
)

transfer = response.json()

Response

200 OK
400 Bad Request
422 Unprocessable Entity

{
  "endToEndId": "550e8400-e29b-41d4-a716-446655440000",
  "eventDate": "2024-01-15T10:30:00.000Z",
  "id": 12345,
  "payment": {
    "amount": 100.50
  },
  "type": "PENDING"
}

{
  "statusCode": 400,
  "message": "Chave PIX inválida",
  "error": "Bad Request"
}

{
  "statusCode": 422,
  "message": "Chave PIX não encontrada no DICT",
  "error": "Unprocessable Entity"
}

Campos da Resposta

string

Identificador único da transação PIX. O valor real do E2E será enviado no webhook quando a transação for liquidada.

string

Data e hora do evento (ISO 8601).

number

Identificador único da transação.

object

Mostrar Propriedades

number

Valor da transferência.

string

Tipo/status da transação:

PENDING: Transferência em processamento
COMPLETED: Transferência concluída
ERROR: Falha na transferência

Idempotência

O header x-idempotency-key garante que a mesma requisição não seja processada mais de uma vez:

// Mesma idempotency key = mesma resposta
const key = '550e8400-e29b-41d4-a716-446655440000';

// Primeira chamada - cria a transferência
const res1 = await createTransfer(key, { amount: 100 });
// { id: 123, type: 'PENDING' }

// Segunda chamada com mesma key - retorna a mesma transferência
const res2 = await createTransfer(key, { amount: 100 });
// { id: 123, type: 'PENDING' } (não cria nova)

O x-idempotency-key é obrigatório. Requisições sem este header serão rejeitadas.

Webhook de Transferência

Quando a transferência for processada, você receberá um webhook V2 do tipo TRANSFER:

{
  "type": "TRANSFER",
  "data": {
    "id": 12345,
    "txId": null,
    "pixKey": "12345678909",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "100.50",
      "currency": "BRL"
    },
    "endToEndId": "E12345678901234567890123456789012",
    "creditDebitType": "DEBIT",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "creditorAccount": {
      "name": "João Silva",
      "document": "123.xxx.xxx-xx",
      "ispb": "18236120"
    },
    "remittanceInformation": "Pagamento referente a NF 12345"
  }
}

Webhooks TRANSFER

Veja a documentação completa do webhook TRANSFER

Tipos de Chave PIX

Tipo	Formato	Exemplo
CPF	11 dígitos	`12345678909`
CNPJ	14 dígitos	`12345678000195`
E-mail	email válido	`joao@email.com`
Telefone	+55DDDNUMERO	`+5511999999999`
EVP	UUID	`7d9f0335-8dcc-4054-9bf9-0dbd61d36906`

Prioridade de Processamento

NORM (Normal)

Processamento padrão na fila
Menor custo
Tempo de processamento variável
creditorDocument opcional

HIGH (Alta)

Processamento instantâneo
Validação imediata do destinatário
creditorDocument obrigatório
Ideal para pagamentos críticos

Bloqueio de ISPBs

Use ispbDeny para bloquear transferências para instituições específicas:

{
  "pixKey": "joao@email.com",
  "payment": { "amount": 100.00 },
  "ispbDeny": [
    "12345678",  // Bloquear banco X
    "87654321"   // Bloquear banco Y
  ]
}

Se a chave PIX pertencer a uma instituição bloqueada, a transferência será rejeitada.

Erros Comuns

Código	Erro	Solução
400	Chave PIX inválida	Verifique o formato da chave
400	Valor inválido	Use número com até 2 casas decimais
400	Idempotency key faltando	Inclua header `x-idempotency-key`
401	Token inválido	Renove o token de acesso
422	Chave não encontrada	A chave não existe no DICT
422	Saldo insuficiente	Verifique o saldo disponível
422	ISPB bloqueado	A instituição está na lista `ispbDeny`

Introdução

Endpoints

Webhooks V2

Visão Geral

Endpoint

Autenticação

Request Body

Request

Response

Campos da Resposta

Idempotência

Webhook de Transferência

Webhooks TRANSFER

Tipos de Chave PIX

Prioridade de Processamento

Bloqueio de ISPBs

Erros Comuns

Próximos Passos

Consultar Saldo

Webhook TRANSFER

​Visão Geral

​Endpoint

​Autenticação

​Request Body

​Request

​Response

​Campos da Resposta

​Idempotência

​Webhook de Transferência

Webhooks TRANSFER

​Tipos de Chave PIX

​Prioridade de Processamento

​Bloqueio de ISPBs

​Erros Comuns

​Próximos Passos

Consultar Saldo

Webhook TRANSFER

Visão Geral

Endpoint

Autenticação

Request Body

Request

Response

Campos da Resposta

Idempotência

Webhook de Transferência

Tipos de Chave PIX

Prioridade de Processamento

Bloqueio de ISPBs

Erros Comuns

Próximos Passos