Saltar al contenido principal
Esta página documenta el payload completo que devuelven POST /v3/transactions/ y GET /v3/transactions/{transaction_id}/. Ambos endpoints devuelven el mismo objeto TransactionDetail; la referencia de la API contiene el esquema campo por campo y esta página lo recorre paso a paso.

​
Estructura de nivel superior

Dos identificadores describen la misma transacción. uuid es el identificador estable de Didit y es el que GET /v3/transactions/{transaction_id}/ espera en su path; txn_id es el transaction_id que proporcionaste al crearla. transaction_number es el número secuencial, propio de cada aplicación, que muestra la consola. El sujeto y la contraparte que enviaste no se devuelven como claves de nivel superior. Son las entradas del array parties, que se distinguen por su role, y vendor_data en el nivel superior es una copia de conveniencia del vendor_data del solicitante.

​
Campos principales

​
Campos financieros

  • amount / currency — importe de la transacción tal como se envió. amount es una cadena decimal sin ceros finales ("1500", "0.5"), con hasta 18 decimales.
  • currency_type — fiat o crypto, tal como se envió en currency_kind; null si se omitió.
  • amount_in_default_currency / default_currency_code — el importe ya convertido que indicaste en la solicitud, devuelto tal cual; null si no lo enviaste.
  • preferred_currency_amount / preferred_currency_code — amount convertido a la moneda preferida de tu aplicación. null si no hay tipo de cambio disponible para currency y no indicaste amount_in_default_currency.
  • payment_details / payment_txn_id — la referencia de pago en texto libre y la referencia de pago externa (por ejemplo, el hash de una transacción en blockchain) de la solicitud.

​
Campos de estado

  • status — APPROVED, IN_REVIEW, DECLINED, AWAITING_USER. Las transacciones se crean como APPROVED; las reglas pueden cambiarlo de forma síncrona.
  • score — puntuación de riesgo entera acumulada por las reglas. Cuanto más alta, mayor es el riesgo.
  • severity — UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL, o null hasta que una regla o un proveedor la establece.
  • decision_reason_code / decision_reason_label — motivo del estado actual, en forma estructurada y legible.
  • environment - live o sandbox, según la aplicación a la que pertenece la transacción. Una transacción de sandbox se almacena pero nunca se evalúa, por lo que un rule_runs vacío significa “no evaluada” y no “no hubo coincidencias”. Consulta Monitorización de transacciones en sandbox.
  • source - LIVE para transacciones enviadas mediante la API o el SDK, IMPORTED para transacciones cargadas mediante la importación CSV de la consola.

​
Partes

Cada parte de la transacción es una entrada en parties. El endpoint de creación registra al sujeto como APPLICANT y a la contraparte opcional como COUNTERPARTY; el enum role también incluye REMITTER y BENEFICIARY. Todas las entradas comparten la misma estructura.
  • role — APPLICANT, COUNTERPARTY, REMITTER, BENEFICIARY. Filtra por este campo para encontrar al sujeto.
  • entity_type — individual, company, external, unhostedWallet, tal como se envió.
  • kind — USER o BUSINESS cuando la parte está vinculada a un usuario o una empresa de Didit mediante vendor_data; EXTERNAL en caso contrario.
  • country_code / dob — a partir de los valores enviados en address.country y date_of_birth.
  • address / institution_info — los objetos tal como se enviaron; {} si se omitieron.
  • external_party_snapshot — copia inmutable de los datos de la parte para las partes EXTERNAL; null mientras la parte esté vinculada a un usuario o una empresa de Didit.

​
device

device es el device_context que enviaste para esa parte, normalizado a snake_case, más el enriquecimiento de IP realizado en el servidor. Es {} cuando la solicitud no incluía contexto de dispositivo, así que trata siempre todas las claves como opcionales. No existe un objeto de enriquecimiento independiente. Cuando la parte incluía un network_context.ip_address público, Didit lo resuelve en línea y escribe los campos enriquecidos en el mismo objeto network_context, rellenando solo las claves que no indicaste. Las claves que el resolvedor devolvió vacías se omiten, por lo que un network_context totalmente enriquecido contiene las cuatro claves enviadas (ip_address, ip_country_code, latitude, longitude) más las que se hayan resuelto de entre ip_country, ip_state, ip_city, isp, organization, is_vpn_or_tor, is_data_center, time_zone, time_zone_offset, asn_number, asn_organization, connection_type, carrier y proxy_type. is_vpn_or_tor y is_data_center están siempre presentes tras una resolución correcta. El enriquecimiento se omite, y network_context se devuelve exactamente como se envió, cuando la IP falta o no es enrutable, cuando la aplicación está en sandbox o cuando la resolución falló. ip_country_code es un código ISO 3166-1 alfa-2 cuando Didit lo resolvió y, en caso contrario, el valor que hayas enviado; las condiciones de las reglas normalizan ambas formas antes de comparar.

​
Métodos de pago

  • role — SOURCE, DESTINATION, FUNDING, BENEFICIARY. El endpoint de creación asigna SOURCE / DESTINATION a partir de direction: en una transacción saliente, el método del sujeto es el SOURCE y el de la contraparte, el DESTINATION; en una entrante es al revés.
  • payment_method_type — bank_card, bank_account, e_wallet, crypto_wallet, unhosted_wallet, other.
  • fingerprint — SHA-256 de type:account_id:issuing_country, estable entre transacciones para que puedas detectar la reutilización del mismo instrumento. null cuando no se envió ningún account_id.
  • owner_kind / vendor_data / owner_name — quién es el titular del instrumento, con la misma convención USER / BUSINESS / EXTERNAL que las partes.
  • details — el objeto payment_method sin procesar, tal como se envió.

​
Ejecuciones de reglas

  • rule — UUID de la regla que se ejecutó; rule_title, rule_description y rule_category se copian de ella.
  • matched — una ejecución solo se registra cuando las condiciones de la regla coincidieron, por lo que las evaluaciones en producción siempre llevan matched: true. Las reglas que se evaluaron sin coincidir no dejan ninguna entrada. Los datos de demostración pueden incluir filas con matched: false.
  • is_test / mode — true y TEST cuando la regla se ejecutó en modo de prueba; una ejecución de prueba se registra, pero no afecta a status, score ni severity.
  • score_delta / status_target / severity — lo que aportó esta ejecución. status_target se establece cuando se ejecutó una acción change_status o cuando la puntuación añadida superó un umbral.
  • action_summary — un resumen en forma de cadena de las acciones que ejecutó la regla, unidas con ; (score +30, change_status:IN_REVIEW, add_tag:<name>, add_note, add_to_list, open_case); null cuando la regla no ejecutó ninguna acción.
  • metadata — el detalle de la evaluación: scope_match, además de conditions[] y aggregations[]. Las dos listas usan claves de valor distintas:
    • conditions[] — una entrada por condición con field, operator, expected_value, el current_value que se leyó de la transacción, matched, group_index y group_logic. field_source es siempre null en las ejecuciones de reglas de transacciones; solo se clasifica para los eventos de monitorización.
    • aggregations[] — una entrada por agregación de velocidad, recuento o suma con metric, field, operator, expected_value, el computed_value resultante de la agregación, window, filters, matched y sample_references. Las agregaciones que solo pudieron calcularse de forma asíncrona llevan computed_value: null y deferred: true.

​
Alertas

alerts siempre es un array vacío por ahora. Una alerta abierta es una transacción retenida, así que consulta status (IN_REVIEW o AWAITING_USER). Consulta Alertas.

​
Actividades

El registro de actividad de la transacción: creación, notas, revisiones manuales y cambios de estado.
Las notas de los analistas aparecen aquí como entradas TRANSACTION_NOTE_ADDED; no existe un array notes independiente.

​
Documentos

Archivos adjuntados a la transacción desde la consola. [] cuando no hay ninguno.
file_url es una URL firmada de corta duración; obtenla cuando la necesites en lugar de almacenarla.

​
Resultados de proveedores

Resultados de proveedores externos (análisis de hash de transacción, análisis de wallets, monitorización fiat, análisis de sanciones).
result_type: FIAT_MONITORING, WALLET_SCREENING, TRANSACTION_SCREENING, TRAVEL_RULE, NETWORK_GRAPH, CUSTOM. payload.risk_factors es la explicación ordenada de score: qué produjo el veredicto, primero los factores de alto riesgo y después por valor movido. Un score alto sin ninguna entrada is_high_risk significa que el proveedor calificó la entidad con su propio modelo de exposición sin informar de una coincidencia con sanciones ni con una entidad atribuida; summary lo indica explícitamente. Referencia campo por campo: Factores de riesgo. Los resultados analizados antes de que existiera este campo no incluyen la clave. En el análisis de hash de transacciones cripto, transaction_flows se rellena cuando el enriquecimiento on-chain está disponible. Normaliza la actividad de la cadena para que la consola pueda mostrar tanto el resumen de la transacción como el grafo de visualización a partir del mismo payload de respuesta. Fuentes de enriquecimiento compatibles:
  • Las cadenas EVM usan Blockscout para normalizar la transacción principal, las llamadas internas y las transferencias de tokens.
  • Bitcoin usa mempool.space para normalizar las entradas y salidas de la transacción.
  • Solana usa Helius para normalizar las transferencias nativas de SOL, las transferencias de tokens SPL y el contexto de eventos NFT disponible.
Cada elemento de transaction_flows[] incluye campos normalizados estables (flow_type, from_address, to_address, amount, amount_usd, currency, token_name, token_address, transaction_hash, block_timestamp, index, success) además de metadata específico del proveedor. Ejemplos habituales de metadata:
metadata es aditivo y específico de cada proveedor. No construyas integraciones críticas que requieran que todas las claves estén presentes en todas las cadenas.

​
Travel Rule

null cuando la transacción no tiene ninguna transferencia ni comprobación de Travel Rule. Se rellena cuando envías travel_rule_details, y también cuando Travel Rule está habilitada para la aplicación y la transacción se creó con transaction_category: "travelRule": en ese caso, Didit inicia el intercambio por su cuenta, con o sin travel_rule_details, e informa aquí de su status. Consulta este campo en lugar de la solicitud que enviaste. En una transferencia entrante, los originator_data y beneficiary_data de la contraparte permanecen enmascarados (data_masked: true) hasta que se confirma la propiedad de la wallet (consulta Datos enmascarados de la contraparte).
direction, rail, counterparty_vasp, delivery, discovery, reason y next_actions tienen la misma estructura que en el endpoint de transferencias. reason y next_actions indican por qué una transferencia COUNTERPARTY_VASP_NOT_FOUND o COUNTERPARTY_VASP_NOT_REACHABLE está bloqueada y qué la hace avanzar, y son "" y [] para cualquier otro estado: consulta Por qué una transferencia está bloqueada. Cada fila de GET /v3/transactions/ incluye el mismo bloque. Consulta Travel Rule.

​
Instantánea de red

El grafo almacenado en sí, no una referencia a él. Procede de cualquiera de estas fuentes:
  • un network_snapshot que enviaste con la transacción, o
  • el grafo que Didit construye cuando el análisis AML de wallets se completa correctamente para una transacción cripto, aunque la solicitud no incluyera network_snapshot. Un grafo construido por el análisis sustituye al enviado, y un nuevo análisis asíncrono lo actualiza.
null cuando no existe ninguno de los dos:
La página de detalle de la transacción en la consola muestra el mismo grafo.

​
Etiquetas, metadatos, props

  • tags[]: etiquetas adjuntas (mediante una acción de regla o por un analista): { "uuid", "name", "color", "description", "source" }, donde source es didit para una etiqueta predefinida y custom para una de las tuyas.
  • metadata: una instantánea de los payloads subject y counterparty exactamente como los enviaste al crear la transacción, bajo esas dos claves.
  • props: las custom_properties que proporcionaste al crear la transacción. Cada clave se puede referenciar en las condiciones de las reglas como custom_values.<key>.

​
Remediación

Cuando una regla dispara AWAITING_USER, Didit crea la sesión de verificación vinculada y la devuelve en dos campos:
  • remediation: la sesión vinculada: { "session_id", "session_token", "url", "status" }. Permanece rellenado durante toda la vida de la transacción, para que siempre puedas ver cómo terminó la acción del usuario.
  • action_required: la acción que el usuario debe realizar en este momento, o null cuando no queda nada pendiente: { "type": "verification_session", "url", "session_id", "session_token", "status" }. Redirige al usuario a url o pasa session_token a un SDK de Didit. Las acciones de propiedad de wallet de Travel Rule usan { "type": "wallet_ownership", "url", "widget_session_id", "expires_at" } y tienen prioridad cuando ambas podrían aplicarse. Cuando hay una acción de propiedad de wallet pendiente y no se pudo encontrar la contraparte de la transferencia, el mismo bloque incluye también reason y next_actions (consulta descubrimiento de la contraparte).
Los mismos dos campos viajan en los payloads de los webhooks transaction.created y transaction.status.updated (action_required); consulta webhooks.

​
Desglose de costos

null hasta que se ejecuta una función facturable para la transacción. En caso contrario, { "total_price", "items": [ { "usage_type", "price", "details" } ] }, con un elemento por cada función medida (análisis, enriquecimiento, etc.).

​
Conversión de divisas

preferred_currency_amount es amount convertido a la divisa preferida de tu aplicación según el tipo de cambio medio del mercado, salvo que hayas proporcionado amount_in_default_currency, en cuyo caso se usa tal cual ese valor ya convertido. Las condiciones de reglas sobre amount comparan el importe en su divisa original; usa preferred_currency_amount en las condiciones cuando necesites un único umbral para todas las divisas.

​
Próximos pasos

Enviar transacciones

Esquema completo de la solicitud.

Estados

Qué significa cada estado.

Puntuación de riesgo

Cómo se calcula la puntuación.
Última modificación el 1 de noviembre de 2026