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/pixAutenticação
Token Bearer obtido via /oauth/token.
Identificador único da requisição para suporte a idempotência. Deve ser um UUID v4.
Exemplo: 550e8400-e29b-41d4-a716-446655440000
Request Body
Chave PIX de destino. Pode ser:
- CPF: 11 dígitos numéricos
- CNPJ: 14 dígitos numéricos
- E-mail: endereco de e-mail válido
- Telefone: +55DDDNUMERO (ex: +5511999999999)
- EVP: Chave aleatória (UUID)
Documento do credor (CPF ou CNPJ). Obrigatório quando priority = HIGH para validação instantânea.
Prioridade do processamento:
HIGH: Processado instantaneamente (requercreditorDocument)NORM: Processamento normal na fila
Mensagem que acompanha a transferência PIX. Sera exibida para o destinatário.
Fluxo de pagamento (opcional). Utilizado para categorização interna.
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)
Dados do pagamento.
Lista de códigos ISPB para os quais pagamentos não serão permitidos. Util 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
{
"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
endToEndIdstringIdentificador único da transação PIX. O valor real do E2E será enviado no webhook quando a transação for liquidada.
eventDatestringData e hora do evento (ISO 8601).
idnumberIdentificador único da transação.
paymentobjecttypestringTipo/status da transação:
PENDING: Transferência em processamentoCOMPLETED: Transferência concluidaERROR: 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 |
| email válido | joao@email.com | |
| Telefone | +55DDDNUMERO | +5511999999999 |
| EVP | UUID | 7d9f0335-8dcc-4054-9bf9-0dbd61d36906 |
Prioridade de Processamento
Bloqueio de ISPBs
Use ispbDeny para bloquear transferências para instituições específicas:
{
"pixKey": "joao@email.com",
"payment": { "amount": 100.00 },
"ispbDeny": [
"12345678",
"87654321"
]
}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 |