> ## 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 para criar evento de monitoramento
> A API da Didit recebe do seu backend eventos de login, jogo, bônus, pagamento, disputa ou segurança e os armazena, enriquece e pontua com suas regras.
Prompt da API para criar evento de monitoramento
Copiar o prompt para a área de transferência
\
\`Send one non-monetary monitoring event (login, session, gameplay, bonus, affiliate, payment, dispute, security, responsible gambling or custom) from my backend to Didit.
Endpoint:
POST https://verification.didit.me/v3/events/
Authentication:
Use the x-api-key header with my Didit API key, from my backend only. A scoped key needs transactions: write.
Goal:
\- Record what happened on my platform so Didit's event rules can score it alongside my transactions, and read the verdict from the response.
Request body (application/json):
\{
"event_id": "login-2026-10-17-000001", // required - my id, unique per application, the idempotency key (max 128)
"event_category": "auth", // required - auth, session, gameplay, bonus, affiliate, payment, dispute, security, responsible_gambling, custom
"action_type": "login", // required - what happened inside the category (max 128)
"occurred_at": "2026-10-17T09:15:02.481Z", // required - at most 7 days in the past, 5 minutes in the future
"subject": { "vendor_data": "user-42", "entity_type": "individual" }, // required - entity_type individual (default) or company
"session": { "session_id": "web-session-abc", "sequence": 142 },
"device_context": { "fingerprint": "didit-fp-v2:a8c1", "network_context": { "ip_address": "203.0.113.42" } },
"transaction_context": { "amount": "1000.00", "currency": "EUR", "payment_reference_id": "dep_735" },
"payload": { "method": "password" }, // category fields, max 16 KB
"custom_values": { "vip_tier": "gold" } // max 100 scalar keys
}
Behavior:
\- Validated, stored, IP-enriched and evaluated by the real-time event rules before the response returns. Cross-subject and long-window rules run asynchronously within minutes (correlation_pending: true).
\- Some actions require payload keys, for example gameplay.p2p_settlement (game_id, counterparty_vendor_data, stake_amount, net_result_amount, role, and one of hand_id, round_id, match_id), payment.deposit_completed (payment_reference_id, amount, currency, payment_method, status) and dispute.chargeback_opened (payment_reference_id and one of dispute_id, chargeback_id). transaction_context keys count towards these requirements.
\- Send hashes and references, never a card number, a full withdrawal address, a password hash or an MFA secret.
\- Idempotency: the same event_id with the same event_category, action_type, occurred_at, subject.vendor_data and payload returns 200 with idempotent_replay true and the stored event's result. Different values in those fields return 409; the other fields are not compared. Retry safely on timeouts.
\- The IP address used for enrichment and rules is device_context.network_context.ip_address as you send it.
\- In a sandbox application no rules run: status is ACCEPTED and rules_evaluated_count is 0.
\- The subject resolves to the user (or company) with that vendor_data; one is created when none exists.
\- Event ingestion is opt-in: until it is switched on in Transactions > Settings > Event monitoring, this call returns 403 with code event_monitoring_disabled and stores nothing.
Example call:
curl -X POST "https://verification.didit.me/v3/events/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"event_id":"login-2026-10-17-000001","event_category":"auth","action_type":"login","occurred_at":"2026-10-17T09:15:02.481Z","subject":{"vendor_data":"user-42"},"device_context":{"network_context":{"ip_address":"203.0.113.42"}},"payload":{"method":"password"}}'
What to read from the response:
\- event_uuid - Didit id of the stored event.
\- status - ACCEPTED (stored, no rule changed it), APPROVED, IN_REVIEW or DECLINED.
\- score, rules_evaluated_count, rules_matched_count, rule_matches[] (rule_id, library_key, mode, is_async).
\- correlation_pending - when true, read GET /v3/events/{event_uuid}/ later for the final status.
\- retention_class and expires_at (null for payment and dispute events).
\- idempotent_replay - true when the event was already stored.
Failure modes:
\- 400 - validation error keyed by field (missing field, occurred_at outside the window, payload over 16 KB, nested custom_values, missing required payload keys).
\- 401 - the API key has expired.
\- 403 - missing API key (a wrong, revoked or expired key gets 401), a scoped key without transactions: write, or code event_monitoring_disabled.
\- 409 - event_id reused with different content; use a new event_id.
\- 429 - more than 300 writes per minute for this API key; honor Retry-After.
Side effects: stores the event, may create the subject's user or company, and applies the actions of matched active rules (score, status, tags, notes, list entries, cases).
For the full integration shape, see /integration/integration-prompt.`
\
Colar em
> [!NOTE]
>
> A ingestão de eventos é opcional. Ative-a em **Transactions > Settings > Event monitoring** antes de enviar eventos; até lá, este endpoint responde `403` com `"code": "event_monitoring_disabled"`.A página [Ingestão de eventos](https://docs.didit.me/pt-br/transaction-monitoring/events.md) aborda o envelope, as dez categorias, as chaves obrigatórias do payload e as classes de retenção. A página [Regras sobre eventos](https://docs.didit.me/pt-br/transaction-monitoring/event-rules.md) explica quais regras são executadas na requisição e quais são executadas de forma assíncrona. Para enviar eventos de um navegador ou aplicativo em vez do seu backend, use o [envio de eventos pelo SDK](https://docs.didit.me/pt-br/transaction-monitoring/sdk-event-submission.md).
## OpenAPI
````yaml pt-br/openapi-25.json POST /v3/events/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/events/:
post:
tags:
- Monitoring Events
summary: Criar evento de monitoramento
description: >-
Envie um evento não monetário (login, sessão, jogabilidade, bônus,
afiliado, pagamento, disputa, segurança, jogo responsável ou
personalizado) a partir do seu backend. O evento é validado em relação
ao contrato da sua categoria, armazenado, enriquecido com dados de IP
uma vez por endereço público único e avaliado pelas suas regras de
eventos em tempo real antes de a resposta ser retornada; as regras entre
sujeitos e de janela longa são executadas de forma assíncrona
(`correlation_pending: true`) e, em uma aplicação de sandbox, nenhuma
regra é executada. `event_id` é a chave de idempotência: o mesmo
`event_id` com os mesmos `event_category`, `action_type`, `occurred_at`,
`subject.vendor_data` e `payload` retorna `200` com `idempotent_replay:
true` e o resultado armazenado (os demais campos do envelope não são
comparados), enquanto valores diferentes retornam `409`. A ingestão de
eventos é opcional por aplicação: até ser ativada, este endpoint retorna
`403` com `code: event_monitoring_disabled` e não armazena nada. Uma
chave de API com escopo precisa de `transactions: write`. Consulte
[Ingestão de
eventos](https://docs.didit.me/pt-br/transaction-monitoring/events) e
[Regras sobre
eventos](https://docs.didit.me/pt-br/transaction-monitoring/event-rules);
para enviar eventos a partir de um navegador ou app, use o [Envio de
eventos pelo
SDK](https://docs.didit.me/pt-br/transaction-monitoring/sdk-event-submission).
operationId: create_monitoring_event
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventCreateRequest'
examples:
Login:
value:
event_id: login-2026-10-17-000001
event_category: auth
action_type: login
occurred_at: '2026-10-17T09:15:02.481Z'
time_zone: Europe/Madrid
subject:
vendor_data: user-42
entity_type: individual
session:
session_id: web-session-abc
sequence: 142
device_context:
fingerprint: fp-a8c1
network_context:
ip_address: 203.0.113.42
payload:
method: password
custom_values:
vip_tier: gold
Deposit completed:
value:
event_id: deposit-2026-10-17-000002
event_category: payment
action_type: deposit_completed
occurred_at: '2026-10-17T09:16:40Z'
subject:
vendor_data: user-42
transaction_context:
amount: '100.00'
currency: EUR
direction: inbound
payment_reference_id: dep_736
payload:
payment_method: card
status: completed
Chargeback opened:
value:
event_id: chargeback-2026-10-16-000318
event_category: dispute
action_type: chargeback_opened
occurred_at: '2026-10-16T14:02:11Z'
subject:
vendor_data: user-42
payload:
payment_reference_id: dep_735
chargeback_id: cb_5521
amount: '250.00'
currency: EUR
reason_code: fraud
responses:
'200':
description: >-
Reprodução idempotente: um evento com este `event_id` e o mesmo
conteúdo já está armazenado. Nada foi armazenado nem avaliado
novamente; o corpo descreve o evento armazenado.
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventIngestResult'
examples:
Replay:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: ACCEPTED
score: 0
rules_evaluated_count: 6
rules_matched_count: 0
correlation_pending: false
retention_class: standard
expires_at: '2026-11-16T09:15:02.481000Z'
idempotent_replay: true
rule_matches: []
'201':
description: O evento foi armazenado e avaliado.
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventIngestResult'
examples:
Stored, no rule matched:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: ACCEPTED
score: 0
rules_evaluated_count: 6
rules_matched_count: 0
correlation_pending: false
retention_class: standard
expires_at: '2026-11-16T09:15:02.481000Z'
idempotent_replay: false
rule_matches: []
Rule matched, async rule pending:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: IN_REVIEW
score: 40
rules_evaluated_count: 6
rules_matched_count: 1
correlation_pending: true
retention_class: risk_relevant
expires_at: '2027-01-15T09:15:02.481000Z'
idempotent_replay: false
rule_matches:
- rule_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
library_key: null
mode: ACTIVE
is_async: false
'400':
description: >-
Falha na validação. O corpo é indexado por campo; campos aninhados
são objetos aninhados. Nada é armazenado.
content:
application/json:
examples:
Missing fields:
value:
event_id:
- This field is required.
subject:
- This field is required.
Unknown category:
value:
event_category:
- '"login" is not a valid choice.'
occurred_at too old:
value:
occurred_at:
- >-
occurred_at is more than 7 days in the past. Use the
batch import lane for backfills.
occurred_at in the future:
value:
occurred_at:
- occurred_at is more than 5 minutes in the future.
Missing subject vendor_data:
value:
subject:
vendor_data:
- This field is required.
Missing required payload keys:
value:
payload:
- >-
payment.deposit_completed requires: payment_method,
status.
Missing one-of payload key:
value:
payload:
- >-
dispute.chargeback_opened requires one of: dispute_id,
chargeback_id.
Security change without changed_field:
value:
payload:
- security.*_changed requires 'changed_field'.
Payload too large:
value:
payload:
- >-
payload exceeds 16384 bytes. Summarise telemetry
client-side.
Too many custom_values:
value:
custom_values:
- custom_values accepts at most 100 keys.
Nested custom value:
value:
custom_values:
- >-
custom_values['limits'] must be a scalar - rule
conditions cannot address nested values.
'401':
description: >-
A chave de API com escopo expirou. Somente uma chave expirada recebe
`401`; uma chave ausente ou inválida recebe `403`.
content:
application/json:
examples:
Expired key:
value:
detail: This API key has expired.
'403':
description: >-
Ausência de `x-api-key` (uma chave incorreta, revogada ou expirada
recebe `401`), uma chave com escopo sem `transactions: write`, uma
chave limitada a alguns fluxos ou a sessões aprovadas (essa chave
nunca acessa dados de monitoramento de transações) ou uma requisição
feita de fora da lista de IPs permitidos da chave. Também é
retornado com `code: event_monitoring_disabled` enquanto a ingestão
de eventos estiver desativada para a aplicação; nesse caso, nada é
armazenado, e a verificação é executada antes da validação do corpo.
content:
application/json:
examples:
Event monitoring disabled:
value:
detail: >-
Event monitoring is not enabled for this application. Turn
on event ingestion in the transaction monitoring settings
before submitting events.
code: event_monitoring_disabled
Missing or invalid API key:
value:
detail: You do not have permission to perform this action.
Scoped key without access:
value:
detail: This API key has no write access to transactions.
Key limited to workflows or approved sessions:
value:
detail: >-
This API key only reaches sessions inside its workflow or
status limits, so it can't use this endpoint.
IP not allowed:
value:
detail: This API key can't be used from this IP address.
'409':
description: >-
`event_id` já foi usado para um evento com conteúdo diferente
(categoria, tipo de ação, `occurred_at`, `vendor_data` do sujeito ou
payload). Envie o evento com um novo `event_id`.
content:
application/json:
examples:
event_id reused:
value:
event_id: >-
event_id 'login-2026-10-17-000001' already exists with a
different payload.
'429':
description: >-
Limite de requisições excedido: requisições de escrita (`POST`,
`PATCH`, `DELETE`) compartilham uma cota de 300 requisições por
minuto por chave de API. Aguarde `Retry-After` segundos e tente
novamente.
headers:
Retry-After:
description: Segundos de espera antes de tentar novamente.
schema:
type: integer
minimum: 1
example: 30
content:
application/json:
examples:
Throttled:
value:
detail: >-
Write request rate limit exceeded. You can make up to 300
requests per minute.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
curl -X POST 'https://verification.didit.me/v3/events/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"event_id": "login-2026-10-17-000001",
"event_category": "auth",
"action_type": "login",
"occurred_at": "2026-10-17T09:15:02.481Z",
"subject": {"vendor_data": "user-42", "entity_type": "individual"},
"session": {"session_id": "web-session-abc", "sequence": 142},
"device_context": {
"fingerprint": "fp-a8c1",
"network_context": {"ip_address": "203.0.113.42"}
},
"payload": {"method": "password"}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.monitoring_events.create(
event_id="login-2026-10-17-000001",
event_category="auth",
action_type="login",
occurred_at="2026-10-17T09:15:02.481Z",
time_zone="Europe/Madrid",
subject={
"vendor_data": "user-42",
"entity_type": "individual",
},
session={
"session_id": "web-session-abc",
"sequence": 142,
},
device_context={
"fingerprint": "fp-a8c1",
"network_context": {
"ip_address": "203.0.113.42",
},
},
payload={"method": "password"},
custom_values={"vip_tier": "gold"},
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.monitoringEvents.create({
event_id: "login-2026-10-17-000001",
event_category: "auth",
action_type: "login",
occurred_at: "2026-10-17T09:15:02.481Z",
time_zone: "Europe/Madrid",
subject: {
vendor_data: "user-42",
entity_type: "individual",
},
session: {
session_id: "web-session-abc",
sequence: 142,
},
device_context: {
fingerprint: "fp-a8c1",
network_context: {
ip_address: "203.0.113.42",
},
},
payload: { method: "password" },
custom_values: { vip_tier: "gold" },
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Create(ctx, didit.MonitoringEventCreateRequest{\n\tEventID: \"login-2026-10-17-000001\",\n\tEventCategory: \"auth\",\n\tActionType: \"login\",\n\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\tTimeZone: didit.String(\"Europe/Madrid\"),\n\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\tVendorData: \"user-42\",\n\t\tEntityType: didit.String(\"individual\"),\n\t},\n\tSession: didit.Some(didit.MonitoringEventCreateRequestSession{\n\t\tSessionID: didit.String(\"web-session-abc\"),\n\t\tSequence: didit.Int(142),\n\t}),\n\tDeviceContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContext{\n\t\tFingerprint: didit.String(\"fp-a8c1\"),\n\t\tNetworkContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContextNetworkContext{\n\t\t\tIPAddress: didit.String(\"203.0.113.42\"),\n\t\t}),\n\t}),\n\tPayload: didit.Some(map[string]any{\"method\": \"password\"}),\n\tCustomValues: didit.Some(map[string]any{\"vip_tier\": \"gold\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import java.time.OffsetDateTime;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.MonitoringEventCreateRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.monitoringEvents().create(MonitoringEventCreateRequest.builder()
.eventId("login-2026-10-17-000001")
.eventCategory(MonitoringEventCreateRequest.EventCategory.of("auth"))
.actionType("login")
.occurredAt(OffsetDateTime.parse("2026-10-17T09:15:02.481Z"))
.timeZone("Europe/Madrid")
.subject(MonitoringEventCreateRequest.Subject.builder()
.vendorData("user-42")
.entityType("individual")
.build())
.session(MonitoringEventCreateRequest.Session.builder()
.sessionId("web-session-abc")
.sequence(142L)
.build())
.deviceContext(MonitoringEventCreateRequest.DeviceContext.builder()
.fingerprint("fp-a8c1")
.networkContext(MonitoringEventCreateRequest.DeviceContext.NetworkContext.builder()
.ipAddress("203.0.113.42")
.build())
.build())
.payload(Map.of("method", "password"))
.customValues(Map.of("vip_tier", MonitoringEventCreateRequest.CustomValuesValue.ofString("gold")))
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
monitoringEvents->create([
'event_id' => 'login-2026-10-17-000001',
'event_category' => 'auth',
'action_type' => 'login',
'occurred_at' => '2026-10-17T09:15:02.481Z',
'time_zone' => 'Europe/Madrid',
'subject' => [
'vendor_data' => 'user-42',
'entity_type' => 'individual',
],
'session' => [
'session_id' => 'web-session-abc',
'sequence' => 142,
],
'device_context' => [
'fingerprint' => 'fp-a8c1',
'network_context' => [
'ip_address' => '203.0.113.42',
],
],
'payload' => ['method' => 'password'],
'custom_values' => ['vip_tier' => 'gold'],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.monitoring_events.create(
event_id: "login-2026-10-17-000001",
event_category: "auth",
action_type: "login",
occurred_at: "2026-10-17T09:15:02.481Z",
time_zone: "Europe/Madrid",
subject: {
vendor_data: "user-42",
entity_type: "individual",
},
session: {
session_id: "web-session-abc",
sequence: 142,
},
device_context: {
fingerprint: "fp-a8c1",
network_context: {
ip_address: "203.0.113.42",
},
},
payload: { method: "password" },
custom_values: { vip_tier: "gold" }
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.MonitoringEvents.CreateAsync(new
MonitoringEventCreateRequest
{
EventId = "login-2026-10-17-000001",
EventCategory = "auth",
ActionType = "login",
OccurredAt = DateTimeOffset.Parse("2026-10-17T09:15:02.481Z"),
TimeZone = "Europe/Madrid",
Subject = new()
{
VendorData = "user-42",
EntityType = "individual",
},
Session = new MonitoringEventCreateRequestSession
{
SessionId = "web-session-abc",
Sequence = 142,
},
DeviceContext = new MonitoringEventCreateRequestDeviceContext
{
Fingerprint = "fp-a8c1",
NetworkContext = new MonitoringEventCreateRequestDeviceContextNetworkContext
{
IpAddress = "203.0.113.42",
},
},
Payload = new Dictionary { ["method"] = "password" },
CustomValues = new Dictionary { ["vip_tier"] = "gold" },
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
MonitoringEventCreateRequest:
type: object
description: >-
O envelope do evento, igual para todas as categorias. Aliases em
camelCase são aceitos: `eventId`, `eventCategory` (ou `category`),
`actionType`, `occurredAt`, `timeZone` (ou `zoneId`), `deviceContext`
(ou `device`), `transactionContext`, `customValues` (ou `props`); dentro
de `subject`: `vendorData`, `entityType`, `fullName`; dentro de
`session`: `sessionId`, `pageUrl`; dentro de `transaction_context`:
`paymentReferenceId`.
required:
- event_id
- event_category
- action_type
- occurred_at
- subject
properties:
event_id:
type: string
maxLength: 128
description: >-
Seu identificador do evento, único por aplicação. Ele é a chave de
idempotência: reenviar os mesmos `event_category`, `action_type`,
`occurred_at`, `subject.vendor_data` e `payload` com ele é uma
repetição; qualquer diferença é um conflito.
example: login-2026-10-17-000001
event_category:
type: string
enum:
- auth
- session
- gameplay
- bonus
- affiliate
- payment
- dispute
- security
- responsible_gambling
- custom
description: Categoria do evento.
example: auth
action_type:
type: string
minLength: 1
maxLength: 128
description: >-
O que aconteceu dentro da categoria. Vocabulário aberto; as ações
gerenciadas listadas em [Ingestão de
eventos](https://docs.didit.me/pt-br/transaction-monitoring/events)
(por exemplo, `login`, `deposit_completed`, `chargeback_opened`)
habilitam validação tipada e campos de regra gerenciados. Os espaços
em branco no início e no fim são removidos.
example: login
occurred_at:
type: string
format: date-time
description: >-
Quando o evento ocorreu do seu lado, em ISO 8601 (um valor sem
deslocamento de fuso horário é interpretado como UTC). Deve estar no
máximo 7 dias no passado e no máximo 5 minutos no futuro.
example: '2026-10-17T09:15:02.481Z'
time_zone:
type: string
nullable: true
maxLength: 64
description: >-
Fuso horário da ocorrência do seu lado, por exemplo `Europe/Madrid`.
Armazenado com o evento; não é retornado pelos endpoints de leitura.
subject:
type: object
description: >-
O usuário ou a empresa a que o evento pertence. Ele é associado ao
usuário (ou à empresa) com este `vendor_data` na sua aplicação; um
novo é criado quando não existe nenhum.
required:
- vendor_data
properties:
vendor_data:
type: string
minLength: 1
maxLength: 255
description: Seu ID do sujeito.
example: user-42
entity_type:
type: string
maxLength: 32
default: individual
description: >-
`company` resolve o titular como uma empresa; qualquer outro
valor (padrão `individual`) o resolve como uma pessoa física. O
mesmo `vendor_data` pode identificar um de cada.
example: individual
full_name:
type: string
nullable: true
maxLength: 512
description: >-
Nome de exibição, usado apenas quando este evento cria o usuário
ou a empresa.
email:
type: string
format: email
nullable: true
description: Validado como endereço de e-mail; não é armazenado no evento.
phone:
type: string
nullable: true
maxLength: 32
description: Validado; não é armazenado no evento.
country:
type: string
nullable: true
maxLength: 3
description: Validado; não é armazenado no evento.
business:
type: object
description: >-
A empresa à qual o evento pertence, quando difere do sujeito. Apenas
`vendor_data` é lido.
additionalProperties: true
properties:
vendor_data:
type: string
maxLength: 255
description: Seu ID da empresa. Filtrável como `business_vendor_data`.
example: merchant-7
session:
type: object
description: O contexto da sua sessão para o evento.
properties:
session_id:
type: string
nullable: true
maxLength: 255
description: >-
Seu identificador de sessão. Filtrável e retornado como
`session_id`.
sequence:
type: integer
nullable: true
description: >-
Posição do evento dentro da sessão. Retornada como
`session_sequence`.
page_url:
type: string
nullable: true
maxLength: 2048
description: Validado; não é armazenado no evento.
referrer:
type: string
nullable: true
maxLength: 2048
description: Validado; não é armazenado no evento.
device_context:
type: object
additionalProperties: true
description: >-
Contexto de dispositivo e rede, armazenado como enviado e retornado
por `GET /v3/events/{event_uuid}/`. Nesta via de servidor, a Didit
não vê a conexão do usuário final. Por isso, o IP enriquecido e
usado pelas regras é `network_context.ip_address`, exatamente como
você o envia.
properties:
fingerprint:
type: string
maxLength: 255
description: >-
Impressão digital do dispositivo. Filtrável como
`device_fingerprint`.
persistent_device_id:
type: string
maxLength: 255
description: Seu identificador persistente do dispositivo.
bot_score:
type: integer
description: Pontuação de bot da sua própria detecção, como número inteiro.
network_context:
type: object
additionalProperties: true
properties:
ip_address:
type: string
maxLength: 64
description: >-
Endereço IP do usuário final. Endereços públicos são
enriquecidos uma vez por endereço único.
example: 203.0.113.42
transaction_context:
type: object
description: >-
Contexto monetário. Valores não vazios aqui também atendem às chaves
obrigatórias do payload da ação.
properties:
amount:
type: string
nullable: true
description: Valor como string decimal (um número também é aceito).
example: '1000.00'
currency:
type: string
nullable: true
maxLength: 10
description: Código da moeda.
direction:
type: string
nullable: true
maxLength: 16
description: >-
Direção da movimentação de dinheiro, por exemplo `inbound` ou
`outbound`.
payment_reference_id:
type: string
nullable: true
maxLength: 255
description: >-
Sua referência de pagamento. Filtrável como
`payment_reference_id`.
payload:
type: object
additionalProperties: true
description: >-
Os campos de domínio da categoria, com no máximo 16384 bytes após a
codificação em JSON. Algumas ações exigem chaves (em `payload` ou
`transaction_context`): `gameplay.p2p_settlement` exige `game_id`,
`counterparty_vendor_data`, `stake_amount`, `net_result_amount`,
`role` e um entre `hand_id`, `round_id`, `match_id`;
`gameplay.bet_placed` e `gameplay.bet_settled` exigem `game_id`;
`payment.deposit_initiated`, `payment.deposit_completed`,
`payment.withdrawal_requested` e `payment.withdrawal_completed`
exigem `payment_reference_id`, `amount`, `currency`,
`payment_method`, `status`; `payment.withdrawal_address_changed`
exige `withdrawal_address_hash`; `dispute.chargeback_opened`,
`dispute.chargeback_won` e `dispute.chargeback_lost` exigem
`payment_reference_id` e um entre `dispute_id`, `chargeback_id`;
`session.bot_signal_observed` exige `telemetry_schema_version` e um
entre `bot_score`, `actions_per_minute`, `timing_variance_ms`,
`pointer_entropy`, `keystroke_entropy`, `reaction_time_ms_p50`;
`responsible_gambling.self_exclusion_match` exige `registry_source`,
`exclusion_status`, `identity_match_ref`. Toda ação `security`
terminada em `_changed` exige `changed_field`, além de
`previous_reference_hash` ou `new_reference_hash` quando o campo é
`password`, `mfa_method`, `mfa`, `email`, `phone`,
`withdrawal_address`, `payout_method` ou `api_key`. Envie hashes e
referências, nunca um número de cartão, um endereço de saque
completo, um hash de senha ou um segredo de MFA.
custom_values:
type: object
description: >-
Até 100 chaves próprias, acessíveis nas regras como
`custom_values.`. Os valores devem ser escalares (string,
número, booleano ou null); objetos aninhados e arrays são
rejeitados.
additionalProperties:
nullable: true
oneOf:
- type: string
- type: number
- type: boolean
example:
event_id: login-2026-10-17-000001
event_category: auth
action_type: login
occurred_at: '2026-10-17T09:15:02.481Z'
time_zone: Europe/Madrid
subject:
vendor_data: user-42
entity_type: individual
session:
session_id: web-session-abc
sequence: 142
device_context:
fingerprint: fp-a8c1
network_context:
ip_address: 203.0.113.42
payload:
method: password
custom_values:
vip_tier: gold
MonitoringEventIngestResult:
type: object
description: >-
Resultado da ingestão de um evento. O mesmo formato é retornado para um
evento novo e para uma repetição idempotente.
required:
- event_uuid
- event_id
- status
- score
- rules_evaluated_count
- rules_matched_count
- correlation_pending
- retention_class
- expires_at
- idempotent_replay
- rule_matches
properties:
event_uuid:
type: string
format: uuid
description: Identificador da Didit para o evento armazenado.
event_id:
type: string
description: Seu `event_id`.
status:
type: string
enum:
- ACCEPTED
- APPROVED
- IN_REVIEW
- DECLINED
description: >-
Status após a execução das regras em tempo real. Consulte
`MonitoringEvent.status`.
score:
type: integer
description: Pontuação após a execução das regras em tempo real.
rules_evaluated_count:
type: integer
minimum: 0
description: >-
Número de regras de evento avaliadas na requisição. 0 em uma
aplicação de sandbox, onde nenhuma regra é executada.
rules_matched_count:
type: integer
minimum: 0
description: >-
Número de regras que corresponderam, incluindo regras no modo
`TEST`.
correlation_pending:
type: boolean
description: >-
`true` quando uma regra assíncrona ainda precisa ser executada.
Consulte `GET /v3/events/{event_uuid}/` alguns minutos depois para
obter o `status` e o `score` finais.
retention_class:
type: string
enum:
- low_value
- standard
- risk_relevant
- monetary_or_compliance
description: >-
Classe de retenção, após qualquer promoção por uma regra
correspondente.
expires_at:
type: string
format: date-time
nullable: true
description: >-
Quando o evento expira conforme sua classe de retenção e é excluído.
Nulo para eventos `monetary_or_compliance` (pagamento e
contestação).
idempotent_replay:
type: boolean
description: >-
`true` quando um evento com este `event_id` e o mesmo conteúdo já
estava armazenado; os valores são os do evento armazenado e nenhuma
regra foi executada novamente.
rule_matches:
type: array
description: Regras que corresponderam ao evento.
items:
type: object
required:
- rule_id
- library_key
- mode
- is_async
properties:
rule_id:
type: string
format: uuid
description: UUID da regra.
library_key:
type: string
nullable: true
description: >-
Chave da biblioteca quando a regra foi instalada a partir da
biblioteca de regras; caso contrário, null.
mode:
type: string
enum:
- ACTIVE
- TEST
description: >-
Regras `TEST` registram a correspondência, mas não aplicam
nenhuma ação.
is_async:
type: boolean
description: '`true` quando a correspondência veio da passagem assíncrona.'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Chave de API da sua aplicação, em Developers -> API keys no Business
Console. A chave principal tem acesso total. Uma chave nomeada pode ter
escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada
a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a
uma data de validade. 401 significa que a chave está errada, revogada ou
expirada; 403 significa que nenhuma chave foi enviada, que a chave não
tem acesso a este recurso ou ação, ou que a requisição veio de um
endereço fora da sua lista de IPs; 404 em uma rota de sessão significa
que a sessão está fora dos fluxos ou status da chave. Uma chave sem
acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave
sem permissão de escrita em sessões recebe links e tokens de sessão como
null. Consulte https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.