> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Envía transacciones a Didit para monitorizarlas en tiempo real con partes, métodos de pago y dispositivo. 1,000 al mes gratis, luego $0.001 cada una.

Envía transacciones a Didit mediante la API [Create Transaction](https://docs.didit.me/es/management-api/transactions/create.md). Cada transacción incluye datos estructurados de las partes, del pago y del contexto, que el motor de reglas evalúa en tiempo real.

> [!TIP]
>
> 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](https://docs.didit.me/es/transaction-monitoring/sdk-transaction-submission.md): 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](https://docs.didit.me/es/management-api/users/list.md) o a un [perfil de empresa](https://docs.didit.me/es/business-verification/business-profiles.md) |
| `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](https://docs.didit.me/es/transaction-monitoring/travel-rule.md#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 |

> [!NOTE]
>
> `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.

```json theme={null}
"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](https://docs.didit.me/es/transaction-monitoring/rules.md#referenciar-propiedades-personalizadas) para más detalles.

## Ejemplo de solicitud

```bash theme={null}
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](https://docs.didit.me/es/management-api/transactions/create.md) para ver el esquema completo de la solicitud y la respuesta, y la [referencia del esquema de respuesta](https://docs.didit.me/es/transaction-monitoring/response-schema.md) 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.

```bash theme={null}
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](https://docs.didit.me/es/management-api/transactions/list.md) 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}/`](https://docs.didit.me/es/management-api/transactions/get) 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](https://docs.didit.me/es/transaction-monitoring/integration-guide.md#ingesta-del-historial).

## Próximos pasos

> [card] [Reglas y puntuación](https://docs.didit.me/es/transaction-monitoring/rules.md)
>
> Cómo se evalúan las transacciones enviadas en función de las reglas.

> [card] [Esquema de respuesta](https://docs.didit.me/es/transaction-monitoring/response-schema.md)
>
> Payload de respuesta completo y comentado.

> [card] [Análisis cripto](https://docs.didit.me/es/transaction-monitoring/aml-screening.md)
>
> Análisis automático de wallets y transacciones de criptomonedas.

> [card] [Travel Rule](https://docs.didit.me/es/transaction-monitoring/travel-rule.md)
>
> Adjunta datos de cumplimiento de la Travel Rule a las transferencias de activos virtuales.

> [card] [Enriquecimiento de IP](https://docs.didit.me/es/transaction-monitoring/ip-enrichment.md)
>
> Contexto derivado de la IP disponible para las reglas.

> [card] [Referencia de la API](https://docs.didit.me/es/management-api/transactions/create.md)
>
> Esquema completo de la solicitud para el endpoint Create Transaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.