Saltar al contenido principal
DICT (Diretório de Identificadores de Contas Transacionais) es el directorio de BACEN que mapea claves Pix a cuentas transaccionales. El Plugin Pix Indirecto (BTG) actúa como intermediario hacia DICT a través de BTG, permitiéndote registrar y resolver claves, transferir claves entre instituciones mediante reclamos, mantener tus datos locales reconciliados con BACEN y gestionar marcadores de fraude MED. El módulo DICT está organizado en seis dominios: Entries, Keys, Claims, Infraction Reports, Refund Requests y Statistics. Esta guía se centra en el ciclo de vida de las claves, los reclamos y la reconciliación. Las operaciones con alcance de cuenta requieren el header X-Account-Id.

​
Entradas y claves

Una entrada es una clave Pix registrada en una de tus cuentas. El plugin resuelve la cuenta subyacente y los datos del titular desde CRM, por lo que creas entradas por tipo de clave en lugar de proporcionar los detalles de la cuenta directamente. Tipos de clave admitidos:
TipoOrigen del valor
CPFDerivado automáticamente del documento del titular en CRM (no envíes key)
CNPJDerivado automáticamente del documento del titular en CRM (no envíes key)
EMAILProporcionado en la solicitud (email válido, ≤ 77 caracteres)
PHONEProporcionado en la solicitud (^\+[1-9]\d{1,14}$)
EVPUUID aleatorio generado por el sistema (no envíes key)
POST /v1/dict/entries
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "keyType": "EMAIL", "key": "john.doe@example.com" }
Gestiona las entradas con create / list / retrieve / update / delete (/v1/dict/entries). La creación/eliminación de entradas valida contra los reclamos activos y la consistencia entre la clave y el documento del titular (por ejemplo, una clave CPF debe coincidir con el CPF del titular).
El plugin no valida las claves con la Receita Federal ni realiza verificaciones de titularidad MFA: asume que el cliente las completó antes de la llamada. Consulta la guía de integración para conocer los requisitos previos.
Las consultas de clave (GET /v1/dict/keys/{key}) resuelven una clave con fines de pago, devolviendo el propietario actual y la cuenta para que puedas iniciar un pago. Usa el header opcional X-EndToEnd-Id para el seguimiento del pago, y POST /v1/dict/keys/check para verificar la existencia de forma masiva. El plugin devuelve los datos tal como los recibe de BTG; enmascarar los campos sensibles antes de mostrarlos es responsabilidad del cliente. Referencia: Create entry · List · Retrieve · Update · Delete · Retrieve a key · Check keys

​
Reclamos: portabilidad y titularidad

Un reclamo transfiere una clave Pix entre instituciones. Hay dos tipos:
  • PORTABILITY — mueve una clave a otro banco para el mismo titular. Permitido para CPF, CNPJ, PHONE y EMAIL.
  • OWNERSHIP — reclama una clave de una persona diferente. Permitido solo para PHONE.
Las dos partes son el donante (el participante que actualmente posee la clave) y el reclamante (el participante que la solicita). Los datos de la cuenta del reclamante se obtienen desde CRM mediante X-Account-Id; claimerParticipant y donorParticipant los establece BTG automáticamente.

​
Ciclo de vida del reclamo

EstadoSignificado
OPENReclamo creado; a la espera del reconocimiento del donante
WAITING_RESOLUTIONEl donante reconoció; periodo de resolución en curso (D+7)
CONFIRMEDEl donante confirmó; la clave queda bloqueada hasta su finalización
COMPLETEDTransferencia de clave finalizada
CANCELLEDCancelado por el donante o el reclamante
Mientras un reclamo está activo (OPEN, WAITING_RESOLUTION o CONFIRMED), la clave queda bloqueada: se impiden nuevas entradas y eliminaciones. Durante OPEN/WAITING_RESOLUTION el donante todavía puede actualizar los datos de la cuenta y las consultas de clave devuelven los datos del donante; una vez en CONFIRMED, las consultas devuelven “key not found” hasta que el reclamo pase a COMPLETED o CANCELLED.
  • PORTABILITY puede completarse inmediatamente después de la confirmación.
  • OWNERSHIP tiene una ventana de finalización: resolutionPeriodEnd es D+7 y completionPeriodEnd es D+30.

​
Operaciones de reclamo

OperaciónRolEndpoint
CreateReclamantePOST /v1/dict/claims
AcknowledgeDonantePOST /v1/dict/claims/{id}/acknowledge
ConfirmDonantePOST /v1/dict/claims/{id}/confirm
CompleteReclamantePOST /v1/dict/claims/{id}/complete
CancelDonante o reclamantePOST /v1/dict/claims/{id}/cancel
Los cambios de estado de los reclamos se entregan a tu sistema mediante webhooks salientes CLAIM. Consulta la guía de Webhooks. Referencia: Create a claim · List · Retrieve · Acknowledge · Confirm · Complete · Cancel

​
Reconciliación (VSync)

La reconciliación mantiene tus datos locales de DICT consistentes con los registros autoritativos de BACEN. Se basa en dos conceptos:
  • CID (Content Identifier) — un hash HMAC-SHA256 de 256 bits de los atributos de una entrada (tipo de clave, clave, propietario, participante, agencia, cuenta, etc.).
  • VSync — un único checksum formado mediante XOR de cada CID de un tipo de clave. Como XOR es conmutativo, comparar tu VSync con el de BTG/BACEN revela si tu conjunto de entradas está sincronizado sin intercambiar cada registro.
Hay dos caminos:
  • API manual / administrativa — los operadores activan verificaciones bajo demanda, descargan archivos CID e investigan inconsistencias. Usa Start full reconciliation y List reconciliation jobs.
  • VSync worker — un proceso automatizado en segundo plano que compara periódicamente las entradas internas con DICT y reconcilia las divergencias sin intervención del usuario.
Configura la ventana de tiempo del worker de reconciliación y la ventana de bloqueo de escritura de DICT en la guía de integración.
Durante la ventana de bloqueo de escritura, la base de datos bloquea temporalmente las escrituras para evitar inconsistencias con BACEN. Ancla la ventana a America/Sao_Paulo y prográmala durante periodos de bajo tráfico.

​
Estadísticas

El dominio Estadísticas expone los agregados de riesgo y uso de Pix de BACEN, permitiéndote evaluar a una contraparte antes de liquidar un pago. Ambos endpoints consultan al proveedor directamente y no almacenan datos localmente, así que trata cada llamada como una consulta nueva en tiempo real. Están etiquetados bajo la API MED y requieren autenticación bearer.
EndpointAlcanceÚsalo para
GET /v1/dict/statistics/persons/{tax_id}Una persona (CPF o CNPJ)Evaluar a un pagador/beneficiario en todas sus claves y cuentas
GET /v1/dict/statistics/keys/{key}Una única clave PixEvaluar una clave específica, junto con su titular actual

​
Estadísticas de persona

Pasa el tax ID (CPF o CNPJ) en la ruta. La respuesta agrega datos de liquidación, marcadores de fraude, infraction reports e información de entradas a lo largo de tres ventanas móviles: d90 (últimos 90 días), m12 (últimos 12 meses) y m60 (últimos 60 meses). 
GET /v1/dict/statistics/persons/12345678901
→ 200 OK
{
  "taxId": "12345678901",
  "statistics": {
    "settlements": { "d90": 42, "m12": 310, "m60": 1580 },
    "fraudMarkers": { "d90": 0, "m12": 1 },
    "infractionReports": { "d90": 0, "m12": 2 }
  }
}

​
Estadísticas de clave

Pasa la clave Pix en la ruta. La respuesta devuelve tanto las estadísticas a nivel de clave (datos ligados a la clave como entidad, independientes de su titular actual) como las estadísticas a nivel de titular (equivalentes a las estadísticas de persona del titular actual de la clave) en una sola llamada. 
GET /v1/dict/statistics/keys/john.doe@example.com
→ 200 OK
{
  "keyStatistics": { "settlements": { "d90": 12 }, "ownershipChanges": { "m12": 1 } },
  "ownerStatistics": { "fraudMarkers": { "d90": 0 }, "infractionReports": { "m12": 0 } }
}
Usa las estadísticas de clave cuando estés a punto de pagar una clave específica, y las estadísticas de persona para una visión más amplia del riesgo de la contraparte. Como ninguna se persiste, cachea de forma responsable en tu lado si necesitas reutilizar el resultado dentro de un flujo de solicitud.
Referencia: Retrieve person statistics · Retrieve key statistics

​
Marcadores de fraude y MED 1.0

DICT también expone las herramientas de prevención de fraude MED (Mecanismo Especial de Devolução) de BACEN. Los marcadores de fraude señalan una clave o cuenta como asociada con fraude; puedes crearlos y cancelarlos (tipos de fraude: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER). Los infraction reports y refund requests relacionados impulsan el flujo de disputa de MED 1.0. Referencia: Create a fraud marker · Cancel a fraud marker · List fraud markers

​
Infraction reports

Un infraction report notifica al PSP de la contraparte que una transacción está en disputa por fraude. Solo puede abrirse dentro de los 90 días posteriores a la fecha de la transacción, y sigue un ciclo de vida create → acknowledge → close/cancel:
PasoRolEndpoint
CreateReportante (PSP del pagador)POST /v1/dict/infraction-reports
AcknowledgePSP de la contrapartePOST /v1/dict/infraction-reports/{id}/acknowledge
ClosePSP del beneficiario/pagadorPOST /v1/dict/infraction-reports/{id}/close
CancelReportantePOST /v1/dict/infraction-reports/{id}/cancel
  • Create — abre el reporte contra el end-to-end ID en disputa, p. ej. reason: REFUND_REQUEST, situationType: SCAM.
  • Acknowledge — el PSP receptor confirma que recibió el reporte.
  • Close — el PSP que responde envía su resultado de análisis (por ejemplo TOTALLY_ACCEPTED) dentro de 7 días. Las infracciones REFUND_REQUEST las cierra el PSP del beneficiario; las infracciones REFUND_CANCELLED, el PSP del pagador. Una vez cerrado, el reporte es inmutable.
  • Cancel — el reportante retira un reporte que abrió.
POST /v1/dict/infraction-reports
{
  "transactionId": "E12345678202411241430ABCDEFGHIJK",
  "reason": "REFUND_REQUEST",
  "situationType": "SCAM",
  "reportDetails": "Customer reported receiving a call from a fake bank employee"
}

​
Refund requests

Un refund request es el mecanismo de MED 1.0 para pedir al PSP de la contraparte que devuelva los fondos en disputa. Refleja el mismo ciclo de vida create → acknowledge → close/cancel:
PasoEndpoint
CreatePOST /v1/dict/refund-requests
Retrieve / ListGET /v1/dict/refund-requests/{id} · GET /v1/dict/refund-requests
ClosePOST /v1/dict/refund-requests/{id}/close
CancelPOST /v1/dict/refund-requests/{id}/cancel
Close registra el resultado del análisis y finaliza la solicitud; cancel retira una solicitud pendiente. Los cambios de estado tanto de los infraction reports como de los refund requests se entregan mediante webhooks salientes — consulta la guía de Webhooks. Referencia: Create an infraction report · Acknowledge · Close · Cancel · Create a refund request Para los flujos de recuperación de fondos, consulta Operaciones de reembolso y MED 2.0 — Recuperación de fondos.

​
Próximos pasos

  • Códigos QR — Generación de códigos QR en claves registradas
  • Webhooks — Notificaciones de reclamos, infracciones y reembolsos
  • Integración — Reconciliación de DICT y configuración del worker