Monitoratge de transaccions: integració de l'API KYT

Aquesta guia cobreix tota la superfície d’integració del monitoratge de transaccions. La guia d’inici ràpid et posa en marxa; aquesta pàgina t’ajuda a passar a producció.

Arquitectura

Autenticació

Capçalera estàndard x-api-key. Es fan servir les mateixes claus per a sessions i entitats. Consulta Autenticació de l’API.

Enviament d’una transacció

Un únic endpoint: POST /v3/transactions/. Consulta enviament de transaccions per veure l’esquema complet. Payload mínim:

{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}

Payload més complet, amb mètodes de pagament, context del dispositiu i propietats personalitzades:

{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}

Hi ha àlies en camelCase acceptats per a cada camp de primer nivell (txnId, txnDate, type, info, applicant, props, travelRule, includeCryptoScreening): el format de transmissió de l’SDK i el format snake_case arriben al mateix lloc.

Modelatge de les parts

Cada transacció té un subject obligatori (el teu client, la part que monitoritzes) i un counterparty opcional (l’altra part). Cadascun té el seu propi payment_method i un context device opcional. A la resposta, arriben a l’array parties amb els rols APPLICANT i COUNTERPARTY. Una part sense vendor_data s’emmagatzema com a instantània externa (kind: EXTERNAL) sense cap entitat vinculada. Consulta payload de transaccions per als camps de les parts.

Idempotència

txn_id (el transaction_id que envies) és únic per aplicació. Tornar a enviar un transaction_id que ja existeix retorna 400 amb A transaction with this transaction_id already exists. al camp transaction_id. Quan dues sol·licituds idèntiques competeixen entre si, la segona rep 409. Cap de les dues respostes retorna la transacció existent. Davant d’un 400 o 409 per un transaction_id duplicat, 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 fes servir el transaction_id (l’uuid de Didit) que el webhook transaction.created porta al costat del teu txn_id. Genera sempre el txn_id pel teu compte abans d’enviar; no confiïs en un ID generat per Didit per a la idempotència. Fes servir l’ID de la teva base de dades, un UUID o un hash dels camps de la transacció.

Temps real vs. lots

Temps real: recomanat per a la majoria de casos d’ús. Envia la transacció en el moment que es produeix al teu sistema. Les regles s’avaluen de manera síncrona i retornen la decisió.
Lot / càrrega retroactiva: per a la ingestió històrica, passa un txn_date en el passat. Les regles s’executen igualment i poden activar webhooks. Per evitar que les regles s’activin amb la càrrega, fes servir la importació CSV de la consola amb el marcador “dry ingest”.

Ingestió històrica

Quan migres des d’un altre sistema de monitoratge de transaccions:

Exporta les teves transaccions històriques a un CSV.
Fes servir Transactions → Import history a la consola (o envia-les per API en un bucle) amb txn_date en el passat.
Activa les regles només quan acabi la ingestió, o fes servir dry ingest per saltar-te l’avaluació de regles.

Sigues prudent amb l’avaluació històrica de regles. Passar 6 mesos d’historial per una regla de “20 transferències en 30 dies” generarà milers d’alertes de cop.

Webhooks

Subscriu-te a:

transaction.created: cada transacció enviada.
transaction.status.updated: canvis d’estat (p. ex. l’analista passa de IN_REVIEW a APPROVED, o una comprovació AML asíncrona actualitza la puntuació).

Detalls complets: webhooks de TM.

app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});

Gestió dels estats

Estat	Què fer
`APPROVED`	Processa la transacció amb normalitat.
`IN_REVIEW`	Reté la transacció fins que la revisió de l’analista o la reverificació automàtica la resolgui.
`DECLINED`	Rebutja la transacció. Mostra a l’usuari un error genèric.
`AWAITING_USER`	L’usuari ha d’actuar perquè la transacció es pugui liquidar: llegeix el bloc `action_required` i envia-li la seva `url` a l’usuari (els SDK ho poden gestionar automàticament).

Consulta estats de TM.

Vinculació de transaccions a entitats

Passa vendor_data a cada part. Beneficis:

Cada transacció s’agrega al perfil de l’usuari o de l’empresa.
Les regles de velocitat i de comportament tenen tot l’historial per avaluar-hi.
Bloquejar una entitat es propaga automàticament a les transaccions futures.

No tenir vendor_data no és un error greu: la transacció s’emmagatzema com a instantània externa, però perds l’agregació a nivell d’entitat.

Sessions de remediació

Quan una acció de regla mou una transacció a AWAITING_USER, Didit crea automàticament una sessió de remediació: una sessió de verificació allotjada estàndard per al mateix vendor_data. Les regles personalitzades sempre indiquen el flux de treball a la mateixa acció; per a les regles de la biblioteca integrada, es recorre al flux de treball de remediació de la configuració de transaccions, després al flux de treball d’Autenticació biomètrica de la vostra aplicació (quan el subjecte té una cara de referència emmagatzemada) i, finalment, al flux de treball per defecte de la vostra aplicació. Les transaccions Travel Rule queden excloses d’aquest recurs automàtic: la seva acció pendent és la prova de titularitat de la cartera. La transacció (la resposta, cada lectura posterior i cada webhook) l’inclou al bloc canònic action_required:

{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}

remediation es manté per compatibilitat amb versions anteriors; action_required és el bloc canònic (també inclou les accions wallet_ownership per a les transferències Travel Rule). Una acció wallet_ownership no canvia per si sola l’estat de la transacció: la transacció conserva l’estat que li assignin les regles, sovint APPROVED, de manera que cal revisar action_required en cada resposta, i no només quan l’estat és AWAITING_USER. L’usuari completa la verificació: per a un flux de treball d’Autenticació biomètrica, un selfie amb prova de vida comparat amb la cara capturada durant el seu alta KYC original, la verificació addicional més forta per a les transaccions d’alt valor. Quan la sessió arriba a una decisió, la transacció la segueix automàticament: APPROVED (decision_reason_code: user_action_approved), DECLINED (user_action_declined) o IN_REVIEW (user_action_in_review), i s’envia un webhook transaction.status.updated.

Es pot seleccionar qualsevol tipus de flux de treball excepte KYB. Els fluxos de treball d’Autenticació biomètrica (i els fluxos en què la coincidència facial s’executa abans de la verificació d’identitat) requereixen que el subjecte ja tingui una cara de referència emmagatzemada d’una verificació aprovada; els usuaris que no en tinguin són derivats al flux de treball per defecte de la vostra aplicació, i la transacció registra una nota que indica la substitució.

Bones pràctiques

Pràctica	Motiu
Passa sempre `vendor_data`	Permet l’agregació.
Utilitza el teu propi `txn_id`	Idempotència.
Subscriu-te tant a `transaction.created` com a `transaction.status.updated`	Detecta els canvis d’estat asíncrons (p. ex., els resultats de la revisió de l’analista).
Defineix els llindars de les regles amb criteri	Llindars baixos = més alertes; llindars alts = més riscos no detectats. Consulta puntuació de risc.
Supervisa el nombre d’execucions de les regles a la consola	Detecta regles que mai s’activen (mal configurades) o que s’activen per a tot (massa laxes).
Prova les regles en mode TEST abans de posar-les en producció	Consulta regles.

Límits de freqüència

Consulta límit de freqüència. La creació de transaccions és un dels endpoints amb més volum de trànsit; els límits habituals són de diversos centenars de sol·licituds per segon. Envia ràfegues amb cura.

Següents passos

Transaccions

Referència completa del payload.

Regles

Com s’avaluen les regles.

Webhooks

Catàleg d’esdeveniments.

Resolució de problemes

Problemes habituals d’integració.

Primers passos

Funcionalitats

Referència

Consola

Monitoratge de transaccions: integració de l'API KYT

Arquitectura

Autenticació

Enviament d’una transacció

Modelatge de les parts

Idempotència

Temps real vs. lots

Ingestió històrica

Webhooks

Gestió dels estats

Vinculació de transaccions a entitats

Sessions de remediació

Bones pràctiques

Límits de freqüència

Següents passos

Transaccions

Regles

Webhooks

Resolució de problemes

​Arquitectura

​Autenticació

​Enviament d’una transacció

​Modelatge de les parts

​Idempotència

​Temps real vs. lots

​Ingestió històrica

​Webhooks

​Gestió dels estats

​Vinculació de transaccions a entitats

​Sessions de remediació

​Bones pràctiques

​Límits de freqüència

​Següents passos

Transaccions

Regles

Webhooks

Resolució de problemes

Arquitectura

Autenticació

Enviament d’una transacció

Modelatge de les parts

Idempotència

Temps real vs. lots

Ingestió històrica

Webhooks

Gestió dels estats

Vinculació de transaccions a entitats

Sessions de remediació

Bones pràctiques

Límits de freqüència

Següents passos