Skip to main content

​
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

​
Authorization
string
required
Token Bearer obtido via /oauth/token.
​
x-idempotency-key
string
required
Identificador único da requisição para suporte a idempotência. Deve ser um UUID v4.Exemplo: 550e8400-e29b-41d4-a716-446655440000

​
Request Body

​
pixKey
string
required
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)
​
creditorDocument
string
Documento do credor (CPF ou CNPJ). Obrigatório quando priority = HIGH para validação instantânea.
​
priority
string
default:"NORM"
Prioridade do processamento:
  • HIGH: Processado instantaneamente (requer creditorDocument)
  • NORM: Processamento normal na fila
​
description
string
Mensagem que acompanha a transferência PIX. Será exibida para o destinatário.
​
paymentFlow
string
Fluxo de pagamento (opcional). Utilizado para categorização interna.
​
expiration
number
default: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)
​
payment
object
required
Dados do pagamento.
​
ispbDeny
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.avista.global/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
    }
  }'

​
Response

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

​
Campos da Resposta

​
endToEndId
string
Identificador único da transação PIX. O valor real do E2E será enviado no webhook quando a transação for liquidada.
​
eventDate
string
Data e hora do evento (ISO 8601).
​
id
number
Identificador único da transação.
​
payment
object
​
type
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

TipoFormatoExemplo
CPF11 dígitos12345678909
CNPJ14 dígitos12345678000195
E-mailemail válido[email protected]
Telefone+55DDDNUMERO+5511999999999
EVPUUID7d9f0335-8dcc-4054-9bf9-0dbd61d36906

​
Prioridade de Processamento

  • Processamento padrão na fila
  • Menor custo
  • Tempo de processamento variável
  • creditorDocument opcional
  • 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": "[email protected]",
  "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ódigoErroSolução
400Chave PIX inválidaVerifique o formato da chave
400Valor inválidoUse número com até 2 casas decimais
400Idempotency key faltandoInclua header x-idempotency-key
401Token inválidoRenove o token de acesso
422Chave não encontradaA chave não existe no DICT
422Saldo insuficienteVerifique o saldo disponível
422ISPB bloqueadoA instituição está na lista ispbDeny

​
Próximos Passos

Consultar Saldo

Verifique o saldo disponível

Webhook TRANSFER

Processe notificações de transferência