API de envío de transacciones: payload y modelo de datos

Envía transacciones a Didit mediante la API Create Transaction. Cada transacción incluye datos estructurados de las partes, del pago y del contexto, que el motor de reglas evalúa en tiempo real.

Cuando la transacción se origina en el dispositivo de un usuario final (un retiro de criptoactivos, un pago dentro de la app), considera el envío de transacciones desde el SDK: un token con alcance limitado sustituye a la clave de API, la información del dispositivo se recopila automáticamente y las acciones requeridas del usuario (prueba de propiedad de la wallet, verificación reforzada) se inician de inmediato.

Categorías de transacciones

Cada transacción tiene un transaction_category que determina cómo la tratan las reglas y la analítica:

Categoría	Descripción
`finance`	Transacción financiera estándar (depósito, retiro, transferencia)
`kyc`	Evento relacionado con la verificación de identidad
`travel_rule`	Transferencia de activos virtuales que requiere cumplir la Travel Rule
`user_event`	Evento personalizado de la plataforma (inicio de sesión, cambio de perfil, etc.)
`gambling_bet`	Apuesta o colocación de una apuesta
`gambling_limit_change`	Cambio en el límite de depósito, pérdida o apuesta de un jugador
`gambling_bonus_change`	Concesión, canje o pérdida de un bono
`audit_trail_event`	Evento de auditoría del sistema o de cumplimiento

Detalles de la transacción

El objeto transaction_details contiene los datos financieros:

Campo	Tipo	Descripción
`direction`	string	`inbound` o `outbound`
`amount`	string	Importe de la transacción como string decimal (p. ej., `"1500.50"`)
`currency`	string	Código de divisa ISO (p. ej., `USD`, `EUR`, `BTC`)
`currency_kind`	string	`fiat` o `crypto` (alias `currencyType`); determina si se activa el screening de criptomonedas
`action_type`	string	Etiqueta de acción definida por el proveedor (p. ej., `deposit`, `withdrawal`, `purchase`)
`payment_details`	string	Descripción en texto libre del pago (p. ej., `"Bank transfer from ABC Corp"`)
`payment_reference_id`	string	Identificador externo de referencia del pago. Para el screening de criptomonedas posterior a la transferencia, usa el hash de la transacción en la blockchain.

Sujeto y contraparte

Cada transacción tiene un sujeto (obligatorio) y una contraparte opcional. Ambos usan el mismo modelo de parte:

Campo	Tipo	Descripción
`entity_type`	string	`person` o `company`
`vendor_data`	string	Tu identificador para esta parte: vincula la transacción a un usuario o a un perfil de empresa
`full_name`	string	Nombre completo de la parte
`first_name`	string	Nombre de pila
`last_name`	string	Apellido
`date_of_birth`	string	Fecha ISO (p. ej., `1990-01-15`)
`country_code`	string	Código de país ISO 3166-1 alfa-2
`address`	objeto o string	Dirección estructurada con `street`, `city`, `state`, `country`, `postal_code`. También acepta un string simple, como la dirección de una wallet para una contraparte cripto: Didit lo guarda sin cambios en la parte.

Didit deriva el country_code de la parte a partir de address.country cuando address es un objeto. Cuando address es un string, country_code se devuelve como null en esa parte. Cuando vendor_data coincide con un usuario o una empresa existentes, Didit vincula automáticamente la transacción al perfil de esa entidad, lo que permite evaluar reglas entre sesiones y realizar comprobaciones de frecuencia. En la respuesta, ambas partes se devuelven en el array parties con los roles APPLICANT y COUNTERPARTY.

Métodos de pago

Adjunta un payment_method a cada parte para describir el instrumento de ese lado:

Campo	Tipo	Descripción
`method_type`	string	`bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` u `other` (alias `type`); se aceptan `ewallet`, `card` y `crypto` como alias, y un valor no reconocido se guarda como `other`
`account_id`	string	Número de cuenta, dirección de wallet o token de tarjeta
`issuing_country`	string	País que emitió el instrumento de pago

En las transacciones travelRule, un método de pago de la contraparte con method_type: "unhosted_wallet" (alias type) declara la wallet de la contraparte como wallet sin custodia. Cuando la Travel Rule está activada y el importe, en la divisa predeterminada de tu aplicación, no es inferior a threshold_amount, la transferencia pasa directamente a UNCONFIRMED_OWNERSHIP y al flujo de prueba de propiedad; consulta Wallets sin custodia declaradas. En las transacciones cripto, incluye las direcciones de wallet en account_id y establece currency_kind en crypto para que el análisis en la blockchain se ejecute automáticamente. El sentido de la transacción determina qué wallet se analiza: el análisis entrante previo a la transferencia usa la wallet del remitente en counterparty.payment_method.account_id; el análisis saliente usa la wallet de destino en counterparty.payment_method.account_id. Si envías un hash de la blockchain en transaction_details.payment_reference_id, el análisis de transacciones entrantes requiere la dirección de depósito de tu servicio en subject.payment_method.account_id, mientras que el análisis de transacciones salientes requiere la wallet de destino en counterparty.payment_method.account_id.

Sobrescribir el análisis cripto

Usa include_crypto_screening en el nivel superior de la solicitud para sobrescribir el valor predeterminado configurado en Transactions > Settings en la Console:

Valor	Descripción
`true`	Fuerza el análisis cripto para esta transacción
`false`	Omite el análisis cripto para esta transacción
omitido o `null`	Usa el valor predeterminado de la aplicación

Contexto del dispositivo

Incluye información del dispositivo del sujeto (y, opcionalmente, de la contraparte) para activar las reglas de inteligencia de dispositivos. El campo de la solicitud es device_context en cada parte; también se acepta el alias en camelCase device, que es el que usa el formato de transmisión del SDK. La respuesta lo devuelve como device en cada parte del array parties.

Campo	Tipo	Descripción
`device_context.fingerprint`	string	Huella digital única del dispositivo
`device_context.persistent_device_id`	string	Identificador estable del dispositivo entre sesiones (esquema de huella digital v2)
`device_context.user_agent`	string	Cadena de user agent del navegador o de la app
`device_context.browser_family`	string	Familia del navegador (p. ej., `Chrome`, `Firefox`, `Safari`). Debe enviarse explícitamente: no se deriva de `user_agent`. Activa reglas como `subject_browser_family`.
`device_context.browser_version`	string	Cadena de la versión del navegador (p. ej., `131.0`). Debe enviarse explícitamente.
`device_context.platform`	string	Identificador de la plataforma (`web`, `ios`, `android`, `macos`, `windows`, `linux`). Debe enviarse explícitamente: no se deriva de `user_agent`. Activa reglas como `subject_platform`.
`device_context.os_family`	string	Familia del sistema operativo (p. ej., `iOS`, `Android`, `Windows`)
`device_context.os_version`	string	Cadena de la versión del sistema operativo
`device_context.accept_language`	string	Valor del encabezado Accept-Language (p. ej., `en-US,en;q=0.9`). Con el SDK, se recopila automáticamente.
`device_context.session_id`	string	Identificador de la sesión actual del usuario. Se almacena en los metadatos. Alias en camelCase: `sessionId`.
`device_context.session_age_ms`	number	Antigüedad de la sesión del usuario en milisegundos en el momento de la transacción. Activa reglas como `subject_session_age_ms`.
`device_context.network_context.ip_address`	string	Dirección IP del cliente
`device_context.network_context.ip_country_code`	string	País de la IP obtenido por geolocalización (ISO 3166-1 alfa-3)
`device_context.network_context.latitude`	number	Latitud geográfica de la IP
`device_context.network_context.longitude`	number	Longitud geográfica de la IP

browser_family y platform no se derivan de user_agent. Deben enviarse como claves explícitas de primer nivel dentro de device_context para que se activen las reglas de inteligencia de dispositivos. Si usas el SDK de Didit, estos campos se recopilan automáticamente.

Se aceptan alias en camelCase para todos los campos: userAgent, browserFamily, browserVersion, osFamily, osVersion, acceptLang, sessionId, sessionAgeMs. El subobjeto network_context acepta los alias ip / countryCode3 / lat / lon, y un bloque ipInfo de primer nivel también se incorpora a network_context. El contexto del dispositivo permite reglas como la detección de multicuenta (la misma huella digital en sujetos distintos), la detección de la combinación de navegador nuevo e IP nueva, las transferencias de alto valor con una sesión de poca antigüedad y la puntuación de riesgo basada en la ubicación.

Propiedades personalizadas

Añade cualquier par clave-valor adicional en el objeto custom_properties. Las reglas pueden hacer referencia a estos campos en sus condiciones, lo que resulta útil para pasar contexto específico de tu negocio, como la categoría de producto, el ID del comercio o el canal.

"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}

En las condiciones de las reglas, haz referencia a cada clave con la ruta de campo custom_values.<key>: por ejemplo, el payload anterior coincide con custom_values.product_category eq "electronics". En el editor de reglas de la consola, las claves detectadas en las transacciones ingeridas recientemente aparecen en el selector de campos de la condición, en Custom Properties, y la opción Enter custom property del mismo grupo te permite escribir cualquier clave manualmente (distingue entre mayúsculas y minúsculas). Consulta Reglas y puntuación para más detalles.

Ejemplo de solicitud

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

Respuesta

La API devuelve la transacción creada con los resultados de su evaluación inicial:

Campo	Tipo	Descripción
`uuid`	string	Identificador único de la transacción en Didit
`txn_id`	string	El ID de transacción que proporcionaste
`status`	string	`APPROVED`, `IN_REVIEW`, `DECLINED` o `AWAITING_USER`
`score`	number	Puntuación de riesgo acumulada de todas las reglas que coinciden
`severity`	string	Gravedad más alta de las reglas que coinciden (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`decision_reason_code`	string	Motivo de la decisión sobre el estado, legible por máquina
`decision_reason_label`	string	Descripción de la decisión, legible por personas

Consulta la referencia de la API para ver el esquema completo de la solicitud y la respuesta, y la referencia del esquema de respuesta para una guía comentada del payload.

Asignar una transacción a un revisor

Asigna una transacción retenida a un miembro de tu aplicación, o retira la asignación, con una clave de API que tenga el privilegio write:transactions. Cada cambio queda registrado en la línea de tiempo de la transacción como TRANSACTION_ASSIGNED.

Llamada	Uso
`POST /v3/transactions/{transaction_uuid}/assign/`	Asignar una transacción.
`POST /v3/transactions/assign/`	Asignar hasta 500 transacciones a un miembro.

Ambas llamadas reciben assignee_email, el correo electrónico de un miembro de la aplicación que haya iniciado sesión en Didit. Envía null o una cadena vacía para retirar la asignación. La llamada masiva también recibe transaction_ids, una lista de entre 1 y 500 UUID de transacciones.

curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'

La llamada individual devuelve uuid, transaction_number, assignee y changed (false cuando la transacción ya tenía ese responsable asignado), o 404 cuando la transacción no existe en la aplicación. La llamada masiva devuelve transactions (una entrada como la anterior por transacción), updated_count y not_found_transaction_ids. Filtra la lista de transacciones con assignee, una lista separada por comas en la que basta con que coincida cualquier valor: me, unassigned, rules (transacciones decididas solo por las reglas, sin intervención de un revisor) o el correo electrónico de un miembro.

Idempotencia

txn_id (el transaction_id que envías) es único por aplicación. Si vuelves a enviar un transaction_id que ya existe, recibes un 400 con A transaction with this transaction_id already exists. en el campo transaction_id, y si dos solicitudes idénticas compiten entre sí, la segunda recibe un 409. Ninguna de las dos respuestas devuelve la transacción existente. Para reintentar de forma segura, trata un 400 o un 409 por un transaction_id duplicado como una indicación de que la transacción ya se creó y consulta la transacción existente en lugar de volver a enviarla: léela con GET /v3/transactions/{uuid}/ usando el uuid de la primera respuesta, o usa el transaction_id (el uuid de Didit) que el webhook transaction.created incluye junto a tu txn_id. Genera siempre el txn_id en tu sistema (por ejemplo, el ID de la transacción en tu propia base de datos, un UUID o un hash determinista).

Carga de datos históricos

Envía un txn_date con una fecha pasada para ingerir transacciones históricas. Las reglas se siguen evaluando de forma predeterminada; usa la importación CSV de la consola con el modo de ingesta de prueba (dry-ingest) si quieres omitir la evaluación de reglas durante cargas masivas de datos históricos. Consulta la guía de integración.

Próximos pasos

Reglas y puntuación

Cómo se evalúan las transacciones enviadas en función de las reglas.

Esquema de respuesta

Payload de respuesta completo y comentado.

Análisis cripto

Análisis automático de wallets y transacciones de criptomonedas.

Travel Rule

Adjunta datos de cumplimiento de la Travel Rule a las transferencias de activos virtuales.

Enriquecimiento de IP

Contexto derivado de la IP disponible para las reglas.

Referencia de la API

Esquema completo de la solicitud para el endpoint Create Transaction.

Primeros pasos

Funciones

Referencia

Consola

API de envío de transacciones: payload y modelo de datos

Categorías de transacciones

Detalles de la transacción

Sujeto y contraparte

Métodos de pago

Sobrescribir el análisis cripto

Contexto del dispositivo

Propiedades personalizadas

Ejemplo de solicitud

Respuesta

Asignar una transacción a un revisor

Idempotencia

Carga de datos históricos

Próximos pasos

Reglas y puntuación

Esquema de respuesta

Análisis cripto

Travel Rule

Enriquecimiento de IP

Referencia de la API

​Categorías de transacciones

​Detalles de la transacción

​Sujeto y contraparte

​Métodos de pago

​Sobrescribir el análisis cripto

​Contexto del dispositivo

​Propiedades personalizadas

​Ejemplo de solicitud

​Respuesta

​Asignar una transacción a un revisor

​Idempotencia

​Carga de datos históricos

​Próximos pasos

Reglas y puntuación

Esquema de respuesta

Análisis cripto

Travel Rule

Enriquecimiento de IP

Referencia de la API

Categorías de transacciones

Detalles de la transacción

Sujeto y contraparte

Métodos de pago

Sobrescribir el análisis cripto

Contexto del dispositivo

Propiedades personalizadas

Ejemplo de solicitud

Respuesta

Asignar una transacción a un revisor

Idempotencia

Carga de datos históricos

Próximos pasos