API per enviar transaccions: payload i model de dades

Envia transaccions a Didit mitjançant l’API Crear transacció. Cada transacció inclou dades estructurades de les parts, del pagament i del context, que el motor de regles avalua en temps real.

Quan la transacció s’origina al dispositiu de l’usuari final (una retirada de criptoactius, un pagament dins de l’aplicació), considera l’enviament de transaccions amb el SDK: un token amb abast limitat substitueix la clau d’API, la intel·ligència del dispositiu es recull automàticament i les accions que l’usuari ha de fer (prova de titularitat de la cartera, verificació addicional) s’activen en el moment.

Categories de transacció

Cada transacció té un transaction_category que determina com la tracten les regles i les analítiques:

Categoria	Descripció
`finance`	Transacció financera estàndard (dipòsit, retirada, transferència)
`kyc`	Esdeveniment relacionat amb la verificació d’identitat
`travel_rule`	Transferència d’actius virtuals que requereix compliment de la Travel Rule
`user_event`	Esdeveniment personalitzat de la plataforma (inici de sessió, canvi de perfil, etc.)
`gambling_bet`	Aposta o realització d’una aposta
`gambling_limit_change`	Canvi en el límit de dipòsit, de pèrdues o d’apostes d’un jugador
`gambling_bonus_change`	Concessió, bescanvi o pèrdua d’un bonus
`audit_trail_event`	Esdeveniment d’auditoria del sistema o de compliment

Detalls de la transacció

L’objecte transaction_details conté les dades financeres:

Camp	Tipus	Descripció
`direction`	string	`inbound` o `outbound`
`amount`	string	Valor de la transacció com a cadena decimal (p. ex., `"1500.50"`)
`currency`	string	Codi de moneda ISO (p. ex., `USD`, `EUR`, `BTC`)
`currency_kind`	string	`fiat` o `crypto` (àlies `currencyType`); determina si s’activa el cribratge de criptoactius
`action_type`	string	Etiqueta d’acció definida pel proveïdor (p. ex., `deposit`, `withdrawal`, `purchase`)
`payment_details`	string	Descripció en text lliure del pagament (p. ex., `"Bank transfer from ABC Corp"`)
`payment_reference_id`	string	Identificador extern de referència del pagament. Per al cribratge de criptoactius posterior a la transferència, utilitza el hash de la transacció a la blockchain.

Subjecte i contrapart

Cada transacció té un subjecte (obligatori) i una contrapart (opcional). Tots dos fan servir el mateix model de part:

Camp	Tipus	Descripció
`entity_type`	string	`person` o `company`
`vendor_data`	string	El teu identificador d’aquesta part: vincula la transacció a un usuari o a un perfil d’empresa
`full_name`	string	Nom complet de la part
`first_name`	string	Nom de pila
`last_name`	string	Cognoms
`date_of_birth`	string	Data ISO (p. ex., `1990-01-15`)
`country_code`	string	Codi de país ISO 3166-1 alpha-2
`address`	object o string	Adreça estructurada amb `street`, `city`, `state`, `country`, `postal_code`. També accepta una cadena de text simple, com una adreça per a una contrapart de criptoactius: Didit l’emmagatzema sense canvis a la part.

Didit deriva el country_code de la part a partir de address.country quan address és un objecte. Quan address és una cadena, country_code es retorna com a null per a aquesta part. Quan vendor_data coincideix amb un usuari o una empresa existents, Didit vincula automàticament la transacció al perfil d’aquesta entitat, cosa que permet avaluar regles entre sessions i fer comprovacions de freqüència de les transaccions. A la resposta, totes dues parts es retornen a la matriu parties amb els rols APPLICANT i COUNTERPARTY.

Mètodes de pagament

Adjunta un payment_method a cada part per descriure l’instrument d’aquesta part:

Camp	Tipus	Descripció
`method_type`	string	`bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` o `other` (àlies `type`); `ewallet`, `card` i `crypto` s’accepten com a àlies, i un valor no reconegut s’emmagatzema com a `other`
`account_id`	string	Número de compte, adreça o token de targeta
`issuing_country`	string	País emissor de l’instrument de pagament

En les transaccions travelRule, un mètode de pagament de la contrapart amb method_type: "unhosted_wallet" (àlies type) declara la cartera de la contrapart com a autoallotjada. Quan la Travel Rule està activada i l’import, en la moneda per defecte de la teva aplicació, no és inferior a threshold_amount, la transferència passa directament a UNCONFIRMED_OWNERSHIP i al flux de prova de titularitat: consulta Carteres autoallotjades declarades. Per a les transaccions de criptoactius, inclou les adreces de cartera a account_id i defineix currency_kind com a crypto perquè el cribratge de blockchain s’executi automàticament. La direcció controla quina cartera es cribra: el cribratge previ a la transferència d’entrada fa servir la cartera de l’emissor a counterparty.payment_method.account_id; el cribratge de sortida fa servir la cartera de destinació a counterparty.payment_method.account_id. Si envies un hash de blockchain a transaction_details.payment_reference_id, el cribratge de transaccions d’entrada requereix l’adreça de dipòsit del teu servei a subject.payment_method.account_id, mentre que el cribratge de transaccions de sortida requereix la cartera de destinació a counterparty.payment_method.account_id.

Sobreescriptura del cribratge de criptoactius

Fes servir include_crypto_screening al nivell superior de la sol·licitud per sobreescriure el valor per defecte configurat a Transaccions > Configuració de la consola:

Valor	Descripció
`true`	Força el cribratge de criptoactius per a aquesta transacció
`false`	Omet el cribratge de criptoactius per a aquesta transacció
omès o `null`	Utilitza el valor per defecte de l’aplicació

Context del dispositiu

Inclou la informació del dispositiu del subjecte (i, opcionalment, de la contrapart) per activar les regles d’intel·ligència de dispositius. El camp de la sol·licitud és device_context a cada part. L’àlies en camelCase device també s’accepta, i és el que utilitza el format de transmissió de l’SDK. La resposta el retorna com a device a cada part de la matriu parties.

Camp	Tipus	Descripció
`device_context.fingerprint`	string	Empremta digital única del dispositiu
`device_context.persistent_device_id`	string	Identificador estable del dispositiu entre sessions (esquema d’empremta v2)
`device_context.user_agent`	string	Cadena d’agent d’usuari del navegador o de l’aplicació
`device_context.browser_family`	string	Família del navegador (p. ex. `Chrome`, `Firefox`, `Safari`). Cal enviar-la explícitament: no es deriva de `user_agent`. Fa funcionar regles com `subject_browser_family`.
`device_context.browser_version`	string	Versió del navegador (p. ex. `131.0`). Cal enviar-la explícitament.
`device_context.platform`	string	Identificador de la plataforma (`web`, `ios`, `android`, `macos`, `windows`, `linux`). Cal enviar-lo explícitament: no es deriva de `user_agent`. Fa funcionar regles com `subject_platform`.
`device_context.os_family`	string	Família del sistema operatiu (p. ex. `iOS`, `Android`, `Windows`)
`device_context.os_version`	string	Versió del sistema operatiu
`device_context.accept_language`	string	Valor de la capçalera Accept-Language (p. ex. `en-US,en;q=0.9`). En el camí de l’SDK, es recull automàticament.
`device_context.session_id`	string	Identificador de la sessió actual de l’usuari. S’emmagatzema a les metadades. Àlies en CamelCase: `sessionId`.
`device_context.session_age_ms`	number	Antiguitat de la sessió de l’usuari, en mil·lisegons, en el moment de la transacció. Fa funcionar regles com `subject_session_age_ms`.
`device_context.network_context.ip_address`	string	Adreça IP del client
`device_context.network_context.ip_country_code`	string	País de la IP resolt geogràficament (ISO 3166-1 alpha-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 i platform no es deriven de user_agent. Cal enviar-los com a claus de primer nivell dins de device_context perquè les regles d’intel·ligència de dispositius s’activin. Si fas servir l’SDK de Didit, aquests camps es recullen automàticament.

Tots els camps accepten àlies en CamelCase: userAgent, browserFamily, browserVersion, osFamily, osVersion, acceptLang, sessionId, sessionAgeMs. L’objecte network_context accepta els àlies ip / countryCode3 / lat / lon, i un bloc ipInfo de primer nivell també es fusiona dins de network_context. El context del dispositiu permet regles com la detecció de multicomptes (la mateixa empremta entre subjectes diferents), la combinació de navegador nou i IP nova, una transferència d’alt valor amb una sessió de poca antiguitat, i la puntuació de risc basada en la ubicació.

Propietats personalitzades

Afegeix qualsevol parell clau-valor addicional a l’objecte custom_properties. Les regles poden fer referència a aquests camps a les seves condicions. Això és útil per passar context específic del negoci, com ara la categoria del producte, l’identificador del comerciant o el canal.

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

A les condicions de les regles, fes referència a cada clau amb la ruta de camp custom_values.<key>. Per exemple, el payload anterior coincideix amb custom_values.product_category eq "electronics". Al constructor de regles de la Console, les claus que han aparegut en transaccions rebudes recentment apareixen al selector de camps de condició, sota Propietats personalitzades. Dins del mateix grup, Introdueix una propietat personalitzada permet escriure manualment qualsevol clau (distingeix entre majúscules i minúscules). Consulta Regles i puntuació per a més detalls.

Exemple de sol·licitud

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"
    }
  }'

Resposta

L’API retorna la transacció creada amb els resultats de l’avaluació inicial:

Camp	Tipus	Descripció
`uuid`	string	Identificador únic de la transacció de Didit
`txn_id`	string	L’identificador de transacció que has proporcionat
`status`	string	`APPROVED`, `IN_REVIEW`, `DECLINED` o `AWAITING_USER`
`score`	number	Puntuació de risc acumulada de totes les regles coincidents
`severity`	string	Severitat més alta de les regles coincidents (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`decision_reason_code`	string	Codi llegible per una màquina del motiu de la decisió d’estat
`decision_reason_label`	string	Descripció de la decisió comprensible per a les persones

Consulta la referència de l’API per a l’esquema complet de la sol·licitud i la resposta, i la referència de l’esquema de resposta per a un recorregut anotat de la resposta.

Assignar una transacció a un revisor

Assigna una transacció retinguda a un membre de la teva aplicació, o desassigna-la, amb una clau d’API que tingui el privilegi write:transactions. Cada canvi queda registrat a la línia de temps de la transacció com a TRANSACTION_ASSIGNED.

Crida	Ús
`POST /v3/transactions/{transaction_uuid}/assign/`	Assigna una transacció.
`POST /v3/transactions/assign/`	Assigna fins a 500 transaccions a un membre.

Totes dues crides reben assignee_email, el correu electrònic d’un membre de l’aplicació que hagi iniciat sessió a Didit. Envia null o una cadena buida per desassignar. La crida massiva també rep transaction_ids, una llista d’entre 1 i 500 UUID de transaccions.

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 crida individual retorna uuid, transaction_number, assignee i changed (false quan la transacció ja tenia aquesta persona assignada), o 404 quan la transacció no existeix a l’aplicació. La crida massiva retorna transactions (una entrada com l’anterior), updated_count i not_found_transaction_ids. Filtra la llista de transaccions amb assignee, una llista separada per comes en què qualsevol valor coincideix: me, unassigned, rules (decidida només per les regles, sense intervenció d’un revisor) o un correu electrònic de membre.

Idempotència

txn_id (el transaction_id que envies) és únic per aplicació. En tornar a enviar un transaction_id que ja existeix, es retorna 400 amb A transaction with this transaction_id already exists. al camp transaction_id, i si dues sol·licituds idèntiques arriben alhora, la segona rep 409. Cap de les dues respostes retorna la transacció existent. Per reintentar amb seguretat, tracta un 400 o un 409 per un transaction_id duplicat com a “ja creada” i consulta la transacció existent en lloc de tornar-la a enviar: llegeix-la amb GET /v3/transactions/{uuid}/ fent servir el uuid de la primera resposta, o utilitza el transaction_id (l’uuid de Didit) que el webhook transaction.created porta juntament amb el teu txn_id. Genera sempre el txn_id pel teu compte (per exemple, l’ID de la teva base de dades de transaccions, un UUID o un hash determinista).

Càrrega històrica

Passa un txn_date anterior per ingerir transaccions històriques. Les regles s’avaluen per defecte: si vols saltar l’avaluació de regles durant les càrregues massives històriques, utilitza la importació de CSV de la consola amb el mode d’ingesta en sec. Consulta la guia d’integració.

Següents passos

Regles i puntuació

Com s’avaluen les transaccions enviades en funció de les regles.

Esquema de resposta

Payload de resposta complet i anotat.

Cribratge de criptomonedes

Cribratge automàtic de carteres i transaccions per a transaccions amb criptomonedes.

Travel Rule

Adjunta les dades de compliment de la Travel Rule a les transferències d’actius virtuals.

Enriquiment d'IP

Context derivat de la IP disponible per a les regles.

Referència de l'API

Esquema complet de la sol·licitud de l’endpoint Create Transaction.

Primers passos

Funcionalitats

Referència

Consola

API per enviar transaccions: payload i model de dades

Categories de transacció

Detalls de la transacció

Subjecte i contrapart

Mètodes de pagament

Sobreescriptura del cribratge de criptoactius

Context del dispositiu

Propietats personalitzades

Exemple de sol·licitud

Resposta

Assignar una transacció a un revisor

Idempotència

Càrrega històrica

Següents passos

Regles i puntuació

Esquema de resposta

Cribratge de criptomonedes

Travel Rule

Enriquiment d'IP

Referència de l'API

​Categories de transacció

​Detalls de la transacció

​Subjecte i contrapart

​Mètodes de pagament

​Sobreescriptura del cribratge de criptoactius

​Context del dispositiu

​Propietats personalitzades

​Exemple de sol·licitud

​Resposta

​Assignar una transacció a un revisor

​Idempotència

​Càrrega històrica

​Següents passos

Regles i puntuació

Esquema de resposta

Cribratge de criptomonedes

Travel Rule

Enriquiment d'IP

Referència de l'API

Categories de transacció

Detalls de la transacció

Subjecte i contrapart

Mètodes de pagament

Sobreescriptura del cribratge de criptoactius

Context del dispositiu

Propietats personalitzades

Exemple de sol·licitud

Resposta

Assignar una transacció a un revisor

Idempotència

Càrrega històrica

Següents passos