> ## 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 envio de transações: payload e modelo de dados

> Envie transações ao Didit para monitorar em tempo real com partes, pagamento, dispositivo e propriedades. 1,000 por mês inclusas, depois $0.001 cada.

Envie transações para a Didit pela API [Create Transaction](https://docs.didit.me/pt-br/management-api/transactions/create.md). Cada transação inclui dados estruturados das partes, do pagamento e do contexto, que o mecanismo de regras avalia em tempo real.

> [!TIP]
>
> Quando a transação se origina no dispositivo do usuário final, como um saque de cripto ou um pagamento dentro do app, considere o [envio de transações pelo SDK](https://docs.didit.me/pt-br/transaction-monitoring/sdk-transaction-submission.md): um token com escopo restrito substitui a chave de API, a inteligência de dispositivo é coletada automaticamente e as ações exigidas do usuário (prova de propriedade da carteira, verificação adicional) são iniciadas na hora.

## Categorias de transação

Toda transação tem um `transaction_category` que determina como as regras e as análises a tratam:

| Categoria | Descrição |
| - | - |
| `finance` | Transação financeira padrão (depósito, saque, transferência) |
| `kyc` | Evento relacionado à verificação de identidade |
| `travel_rule` | Transferência de ativo virtual que exige conformidade com a Travel Rule |
| `user_event` | Evento personalizado da plataforma (login, alteração de perfil etc.) |
| `gambling_bet` | Aposta ou registro de aposta em jogos de azar |
| `gambling_limit_change` | Alteração no limite de depósito, de perda ou de aposta de um jogador |
| `gambling_bonus_change` | Concessão, resgate ou perda de bônus |
| `audit_trail_event` | Evento de auditoria do sistema ou de conformidade |

## Detalhes da transação

O objeto `transaction_details` contém os dados financeiros:

| Campo | Tipo | Descrição |
| - | - | - |
| `direction` | string | `inbound` ou `outbound` |
| `amount` | string | Valor da transação como string decimal (por exemplo, `"1500.50"`) |
| `currency` | string | Código ISO da moeda (por exemplo, `USD`, `EUR`, `BTC`) |
| `currency_kind` | string | `fiat` ou `crypto` (alias `currencyType`); determina se a triagem de cripto é acionada |
| `action_type` | string | Rótulo de ação definido pelo fornecedor (por exemplo, `deposit`, `withdrawal`, `purchase`) |
| `payment_details` | string | Descrição em texto livre do pagamento (por exemplo, `"Bank transfer from ABC Corp"`) |
| `payment_reference_id` | string | Identificador externo de referência do pagamento. Para a triagem de cripto pós-transferência, use o hash da transação na blockchain. |

## Titular e contraparte

Cada transação tem um **titular** (obrigatório) e uma **contraparte** opcional. Ambos usam o mesmo modelo de parte:

| Campo | Tipo | Descrição |
| - | - | - |
| `entity_type` | string | `person` ou `company` |
| `vendor_data` | string | Seu identificador para esta parte, que vincula a transação a um [usuário](https://docs.didit.me/pt-br/management-api/users/list.md) ou a um [perfil de empresa](https://docs.didit.me/pt-br/business-verification/business-profiles.md) |
| `full_name` | string | Nome completo da parte |
| `first_name` | string | Nome |
| `last_name` | string | Sobrenome |
| `date_of_birth` | string | Data no formato ISO (por exemplo, `1990-01-15`) |
| `country_code` | string | Código de país ISO 3166-1 alpha-2 |
| `address` | object ou string | Endereço estruturado com `street`, `city`, `state`, `country`, `postal_code`. Também aceita uma string simples, como o endereço de carteira de uma contraparte cripto; a Didit a armazena sem alterações na parte. |

A Didit deriva o `country_code` da parte a partir de `address.country` quando `address` é um objeto. Quando `address` é uma string, `country_code` retorna `null` nessa parte.

Quando `vendor_data` corresponde a um usuário ou a uma empresa existente, a Didit vincula automaticamente a transação ao perfil dessa entidade, o que permite a avaliação de regras entre sessões e verificações de frequência.
Na resposta, as duas partes são retornadas no array `parties` com as funções `APPLICANT` e `COUNTERPARTY`.

## Métodos de pagamento

Anexe um `payment_method` a cada parte para descrever o instrumento de pagamento associado a essa parte:

| Campo | Tipo | Descrição |
| - | - | - |
| `method_type` | string | `bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` ou `other` (alias `type`); `ewallet`, `card` e `crypto` são aceitos como aliases, e um valor não reconhecido é armazenado como `other` |
| `account_id` | string | Número da conta, endereço da carteira ou token do cartão |
| `issuing_country` | string | País que emitiu o instrumento de pagamento |

Em transações `travelRule`, um método de pagamento da contraparte com `method_type: "unhosted_wallet"` (alias `type`) declara a carteira da contraparte como autocustodiada.
Quando a Travel Rule está ativada e o valor, na moeda padrão da sua aplicação, não está abaixo de `threshold_amount`, a transferência vai direto para `UNCONFIRMED_OWNERSHIP` e para o fluxo de prova de propriedade. Consulte [Carteiras autocustodiadas declaradas](https://docs.didit.me/pt-br/transaction-monitoring/travel-rule.md#carteiras-autocustodiadas-declaradas).

Para transações cripto, inclua os endereços em `account_id` e defina `currency_kind` como `crypto` para que a triagem na blockchain possa ser executada automaticamente. A direção controla qual carteira é analisada: a triagem de entrada antes da transferência usa a carteira do remetente em `counterparty.payment_method.account_id`; a triagem de saída usa a carteira de destino em `counterparty.payment_method.account_id`. Se você enviar um hash da blockchain em `transaction_details.payment_reference_id`, a triagem de transações de entrada exige o endereço de depósito do seu serviço em `subject.payment_method.account_id`, enquanto a triagem de transações de saída exige a carteira de destino em `counterparty.payment_method.account_id`.

## Substituição da triagem de cripto

Use `include_crypto_screening` no nível superior da requisição para substituir o padrão configurado em **Transações** > **Configurações** no Console:

| Valor | Descrição |
| - | - |
| `true` | Força a triagem de cripto para esta transação |
| `false` | Ignora a triagem de cripto para esta transação |
| omitido ou `null` | Usa o padrão definido no nível da aplicação |

## Contexto do dispositivo

Inclua informações do dispositivo do titular (e, opcionalmente, da contraparte) para alimentar as regras de inteligência de dispositivo. O campo da requisição é `device_context` em cada parte. O alias em camelCase `device` também é aceito e é o que o formato de transmissão do SDK usa. A resposta o retorna como `device` em cada parte do array `parties`.

| Campo | Tipo | Descrição |
| - | - | - |
| `device_context.fingerprint` | string | Impressão digital (fingerprint) única do dispositivo |
| `device_context.persistent_device_id` | string | Identificador estável do dispositivo entre sessões (esquema de fingerprint v2) |
| `device_context.user_agent` | string | String de user agent do navegador ou do app |
| `device_context.browser_family` | string | Família do navegador (por exemplo, `Chrome`, `Firefox`, `Safari`). **Deve ser enviado explicitamente**: não é derivado de `user_agent`. Alimenta regras como `subject_browser_family`. |
| `device_context.browser_version` | string | String da versão do navegador (por exemplo, `131.0`). Deve ser enviado explicitamente. |
| `device_context.platform` | string | Identificador da plataforma (`web`, `ios`, `android`, `macos`, `windows`, `linux`). **Deve ser enviado explicitamente**: não é derivado de `user_agent`. Alimenta regras como `subject_platform`. |
| `device_context.os_family` | string | Família do sistema operacional (por exemplo, `iOS`, `Android`, `Windows`) |
| `device_context.os_version` | string | String da versão do sistema operacional |
| `device_context.accept_language` | string | Valor do cabeçalho Accept-Language (por exemplo, `en-US,en;q=0.9`). No fluxo do SDK, é coletado automaticamente. |
| `device_context.session_id` | string | Identificador da sessão atual do usuário. Armazenado nos metadados. Alias em camelCase: `sessionId`. |
| `device_context.session_age_ms` | number | Tempo decorrido desde o início da sessão do usuário, em milissegundos, no momento da transação. Alimenta regras como `subject_session_age_ms`. |
| `device_context.network_context.ip_address` | string | Endereço IP do cliente |
| `device_context.network_context.ip_country_code` | string | País do IP obtido por geolocalização (ISO 3166-1 alpha-3) |
| `device_context.network_context.latitude` | number | Latitude geográfica do IP |
| `device_context.network_context.longitude` | number | Longitude geográfica do IP |

> [!NOTE]
>
> `browser_family` e `platform` **não** são derivados de `user_agent`. Eles devem ser enviados como chaves explícitas de nível superior dentro de `device_context` para que as regras de inteligência de dispositivo sejam acionadas. Se você usa o SDK da Didit, esses campos são coletados automaticamente.

Aliases em camelCase são aceitos para todos os campos: `userAgent`, `browserFamily`, `browserVersion`, `osFamily`, `osVersion`, `acceptLang`, `sessionId`, `sessionAgeMs`. O subobjeto `network_context` aceita os aliases `ip` / `countryCode3` / `lat` / `lon`, e um bloco `ipInfo` de nível superior também é incorporado a `network_context`.

O contexto do dispositivo viabiliza regras como detecção de múltiplas contas (mesmo fingerprint em titulares diferentes), detecção da combinação de navegador novo com IP novo, transferências de alto valor com sessão recente e pontuação de risco baseada em localização.

## Propriedades personalizadas

Adicione quaisquer pares chave-valor extras no objeto `custom_properties`. As regras podem referenciar esses campos em suas condições, o que é útil para enviar contexto específico do seu negócio, como categoria de produto, ID do lojista ou canal.

```json theme={null}
"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}
```

Nas condições das regras, referencie cada chave com o caminho de campo `custom_values.<key>`. Por exemplo, o payload acima corresponde a `custom_values.product_category eq "electronics"`. No construtor de regras do Console, as chaves vistas em transações ingeridas recentemente aparecem no seletor de campos da condição em **Propriedades personalizadas**, e **Inserir propriedade personalizada**, no mesmo grupo, permite digitar qualquer chave manualmente (diferencia maiúsculas de minúsculas). Consulte [Regras e pontuação](https://docs.didit.me/pt-br/transaction-monitoring/rules.md#referência-a-propriedades-personalizadas) para mais detalhes.

## Exemplo de requisição

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

## Resposta

A API retorna a transação criada com os resultados da avaliação inicial:

| Campo | Tipo | Descrição |
| - | - | - |
| `uuid` | string | Identificador único da transação na Didit |
| `txn_id` | string | O ID de transação que você forneceu |
| `status` | string | `APPROVED`, `IN_REVIEW`, `DECLINED` ou `AWAITING_USER` |
| `score` | number | Pontuação de risco acumulada de todas as regras correspondentes |
| `severity` | string | Maior severidade entre as regras correspondentes (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`) |
| `decision_reason_code` | string | Motivo da decisão de status, legível por máquina |
| `decision_reason_label` | string | Descrição da decisão, legível por humanos |

Consulte a [Referência da API](https://docs.didit.me/pt-br/management-api/transactions/create.md) para o esquema completo de requisição e resposta, e a [referência do esquema de resposta](https://docs.didit.me/pt-br/transaction-monitoring/response-schema.md) dedicada, que apresenta um passo a passo comentado do payload.

## Atribuir uma transação a um revisor

Atribua uma transação retida a um membro da sua aplicação, ou remova a atribuição, com uma chave de API que tenha o privilégio `write:transactions`.
Cada alteração é registrada na linha do tempo da transação como `TRANSACTION_ASSIGNED`.

| Chamada | Uso |
| - | - |
| `POST /v3/transactions/{transaction_uuid}/assign/` | Atribui uma transação. |
| `POST /v3/transactions/assign/` | Atribui até 500 transações a um membro. |

As duas chamadas recebem `assignee_email`, o e-mail de um membro da aplicação que já fez login na Didit.
Envie `null` ou uma string vazia para remover a atribuição.
A chamada em massa também recebe `transaction_ids`, uma lista de 1 a 500 UUIDs de transações.

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

A chamada individual retorna `uuid`, `transaction_number`, `assignee` e `changed` (`false` quando a transação já tinha esse responsável), ou `404` quando a transação não existe na aplicação.
A chamada em massa retorna `transactions` (uma entrada como a acima por transação), `updated_count` e `not_found_transaction_ids`.

Filtre a [lista de transações](https://docs.didit.me/pt-br/management-api/transactions/list.md) com `assignee`, uma lista separada por vírgulas em que qualquer valor corresponde: `me`, `unassigned`, `rules` (decididas apenas pelas regras, sem envolvimento de revisor) ou o e-mail de um membro.

## Idempotência

`txn_id` (o `transaction_id` que você envia) é único por aplicação.
Reenviar um `transaction_id` que já existe retorna `400` com `A transaction with this transaction_id already exists.` no campo `transaction_id`, e, quando duas requisições idênticas concorrem entre si, a segunda recebe `409`.
Nenhuma das duas respostas retorna a transação existente.
Para tentar novamente com segurança, trate um `400` ou `409` para um `transaction_id` duplicado como indicação de que a transação já foi criada e consulte a transação existente em vez de reenviá-la: leia-a com [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/pt-br/management-api/transactions/get) usando o `uuid` da primeira resposta, ou use o `transaction_id` (o uuid da Didit) que o webhook `transaction.created` traz junto com o seu `txn_id`.
Sempre gere o `txn_id` do seu lado (por exemplo, o ID da transação no seu próprio banco de dados, um UUID ou um hash determinístico).

## Carga de dados históricos

Passe `txn_date` com uma data no passado para ingerir transações históricas. Por padrão, as regras continuam sendo avaliadas: use a importação de CSV do console com o modo dry-ingest se quiser pular a avaliação de regras durante cargas históricas em massa. Consulte o [guia de integração](https://docs.didit.me/pt-br/transaction-monitoring/integration-guide.md#ingestão-de-histórico).

## Próximos passos

> [card] [Regras e pontuação](https://docs.didit.me/pt-br/transaction-monitoring/rules.md)
>
> Como as transações enviadas são avaliadas em relação às regras.

> [card] [Esquema da resposta](https://docs.didit.me/pt-br/transaction-monitoring/response-schema.md)
>
> Payload completo da resposta, com anotações.

> [card] [Triagem de cripto](https://docs.didit.me/pt-br/transaction-monitoring/aml-screening.md)
>
> Triagem automática de carteiras e transações de criptoativos.

> [card] [Travel Rule](https://docs.didit.me/pt-br/transaction-monitoring/travel-rule.md)
>
> Anexe dados de conformidade com a Travel Rule a transferências de ativos virtuais.

> [card] [Enriquecimento de IP](https://docs.didit.me/pt-br/transaction-monitoring/ip-enrichment.md)
>
> Contexto derivado do IP disponível para as regras.

> [card] [Referência da API](https://docs.didit.me/pt-br/management-api/transactions/create.md)
>
> Esquema completo da requisição para o endpoint Create Transaction.


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