Pular para o conteúdo principal
Esta página documenta o payload completo retornado por POST /v3/transactions/ e GET /v3/transactions/{transaction_id}/. Os dois endpoints retornam o mesmo objeto TransactionDetail; a referência da API traz o esquema campo a campo, e esta página explica esse esquema.

​
Estrutura de nível superior

Dois identificadores descrevem a mesma transação. uuid é o identificador estável da Didit e é o que GET /v3/transactions/{transaction_id}/ espera no path; txn_id é o transaction_id que você informou na criação. transaction_number é o número sequencial no escopo da aplicação que o console exibe. O titular e a contraparte que você enviou não voltam como chaves de nível superior. Eles são as entradas do array parties, diferenciadas por role, e vendor_data no nível superior é uma cópia de conveniência do vendor_data do solicitante.

​
Campos principais

​
Campos financeiros

  • amount / currency — valor da transação conforme enviado. amount é uma string decimal sem zeros à direita ("1500", "0.5"), com até 18 casas decimais.
  • currency_type — fiat ou crypto, conforme enviado em currency_kind; null quando omitido.
  • amount_in_default_currency / default_currency_code — o valor pré-convertido que você informou na requisição, devolvido sem alterações; null quando você não enviou nenhum.
  • preferred_currency_amount / preferred_currency_code — amount convertido para a moeda preferencial da sua aplicação. null quando não há taxa de câmbio disponível para currency e você não informou amount_in_default_currency.
  • payment_details / payment_txn_id — a referência de pagamento em texto livre e a referência externa do pagamento (por exemplo, um hash de transação em blockchain) enviadas na requisição.

​
Campos de status

  • status — APPROVED, IN_REVIEW, DECLINED, AWAITING_USER. As transações são criadas como APPROVED; as regras podem alterá-las de forma síncrona.
  • score — pontuação de risco inteira acumulada pelas regras. Quanto maior, mais arriscada.
  • severity — UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL, ou null até que uma regra ou um provedor a defina.
  • decision_reason_code / decision_reason_label — motivo do status atual, em formato estruturado e legível.
  • environment - live ou sandbox, de acordo com a aplicação dona da transação. Uma transação sandbox é armazenada, mas nunca avaliada, então um rule_runs vazio significa “não avaliada”, e não “nenhuma regra correspondeu”. Consulte Monitoramento de transações em sandbox.
  • source - LIVE para transações enviadas pela API ou pelo SDK, IMPORTED para transações carregadas pela importação de CSV no console.

​
Partes

Cada parte da transação é uma entrada em parties. O endpoint de criação registra o titular como APPLICANT e a contraparte opcional como COUNTERPARTY; o enum role também inclui REMITTER e BENEFICIARY. Todas as entradas têm o mesmo formato.
  • role — APPLICANT, COUNTERPARTY, REMITTER, BENEFICIARY. Use-o como filtro para encontrar o titular.
  • entity_type — individual, company, external, unhostedWallet, conforme enviado.
  • kind — USER ou BUSINESS quando a parte está vinculada a um usuário ou empresa da Didit por meio de vendor_data; caso contrário, EXTERNAL.
  • country_code / dob — extraídos de address.country e date_of_birth enviados.
  • address / institution_info — os objetos conforme enviados; {} quando omitidos.
  • external_party_snapshot — cópia congelada dos dados da parte para partes EXTERNAL; null enquanto a parte estiver vinculada a um usuário ou empresa da Didit.

​
device

device é o device_context que você enviou para essa parte, normalizado em snake_case, acrescido do enriquecimento de IP feito no servidor. Ele é {} quando a requisição não trouxe contexto de dispositivo, portanto trate sempre todas as chaves como opcionais. Não existe um objeto de enriquecimento separado. Quando a parte trouxe um network_context.ip_address público, a Didit o resolve na hora e grava os campos enriquecidos no mesmo objeto network_context, preenchendo apenas as chaves que você não informou. As chaves que o resolvedor retornou vazias são omitidas, então um network_context totalmente enriquecido contém as quatro chaves enviadas (ip_address, ip_country_code, latitude, longitude) mais as que tiverem sido resolvidas entre ip_country, ip_state, ip_city, isp, organization, is_vpn_or_tor, is_data_center, time_zone, time_zone_offset, asn_number, asn_organization, connection_type, carrier e proxy_type. is_vpn_or_tor e is_data_center estão sempre presentes após uma resolução bem-sucedida. O enriquecimento é ignorado, e network_context é retornado exatamente como enviado, quando o IP está ausente ou não é roteável, quando a aplicação está em sandbox ou quando a resolução falhou. ip_country_code é um código ISO 3166-1 alfa-2 quando a Didit o resolveu e, caso contrário, o valor que você enviou; as condições das regras normalizam as duas formas antes de comparar.

​
Métodos de pagamento

  • role — SOURCE, DESTINATION, FUNDING, BENEFICIARY. O endpoint de criação atribui SOURCE / DESTINATION a partir de direction: em uma transação de saída, o método do titular é o SOURCE e o da contraparte é o DESTINATION; em uma transação de entrada, é o inverso.
  • payment_method_type — bank_card, bank_account, e_wallet, crypto_wallet, unhosted_wallet, other.
  • fingerprint — SHA-256 sobre type:account_id:issuing_country, estável entre transações para que você possa correlacionar o reúso do mesmo instrumento. null quando nenhum account_id foi enviado.
  • owner_kind / vendor_data / owner_name — quem é o dono do instrumento, seguindo a mesma convenção USER / BUSINESS / EXTERNAL das partes.
  • details — o objeto payment_method bruto, conforme enviado.

​
Execuções de regras

  • rule — UUID da regra executada; rule_title, rule_description e rule_category são copiados dela.
  • matched — uma execução só é registrada quando as condições da regra corresponderam, então as avaliações em produção sempre trazem matched: true. Regras avaliadas sem correspondência não deixam nenhuma entrada. Dados de demonstração podem incluir linhas com matched: false.
  • is_test / mode — true e TEST quando a regra foi executada em modo de teste; uma execução de teste é registrada, mas não tem efeito sobre status, score ou severity.
  • score_delta / status_target / severity — o que essa execução contribuiu. status_target é definido quando uma ação change_status foi executada ou quando a pontuação adicionada ultrapassou um limiar.
  • action_summary — um resumo em string das ações que a regra executou, unidas por ; (score +30, change_status:IN_REVIEW, add_tag:<name>, add_note, add_to_list, open_case); null quando a regra não executou nenhuma ação.
  • metadata — o detalhe da avaliação: scope_match, além de conditions[] e aggregations[]. As duas listas usam chaves de valor diferentes:
    • conditions[] — uma entrada por condição com field, operator, expected_value, o current_value lido da transação, matched, group_index e group_logic. field_source é sempre null nas execuções de regras de transação; ele só é classificado para eventos de monitoramento.
    • aggregations[] — uma entrada por agregação de velocidade / contagem / soma com metric, field, operator, expected_value, o computed_value resultante da agregação, window, filters, matched e sample_references. Agregações que só puderam ser calculadas de forma assíncrona trazem computed_value: null e deferred: true.

​
Alertas

alerts é sempre um array vazio hoje. Um alerta aberto é uma transação retida, então leia status (IN_REVIEW ou AWAITING_USER). Consulte Alertas.

​
Atividades

O registro de atividades da transação: criação, notas, revisões manuais e mudanças de status.
As notas dos analistas aparecem aqui como entradas TRANSACTION_NOTE_ADDED. Não existe um array notes separado.

​
Documentos

Arquivos anexados à transação pelo console. [] quando não há nenhum.
file_url é uma URL assinada de curta duração: busque-a quando precisar dela, em vez de armazená-la.

​
Resultados de provedores

Saídas de provedores externos (triagem de hash de transação, triagem de carteiras, monitoramento fiat, triagem de sanções).
result_type: FIAT_MONITORING, WALLET_SCREENING, TRANSACTION_SCREENING, TRAVEL_RULE, NETWORK_GRAPH, CUSTOM. payload.risk_factors é a explicação ordenada de score, ou seja, o que produziu o veredito: primeiro os fatores de alto risco e depois por valor movimentado. Um score alto sem nenhuma entrada is_high_risk significa que o provedor avaliou a entidade com seu próprio modelo de exposição, sem relatar correspondência com sanções ou com uma entidade atribuída. summary informa isso explicitamente. Referência campo a campo: Fatores de risco. Resultados triados antes da existência desse campo omitem a chave. Na triagem de hash de transações cripto, transaction_flows é preenchido quando o enriquecimento on-chain está disponível. Ele normaliza a atividade da cadeia para que o console possa renderizar tanto a visão geral da transação quanto o grafo de visualização a partir do mesmo payload de resposta. Fontes de enriquecimento compatíveis:
  • Cadeias EVM usam o Blockscout para normalizar a transação principal, as chamadas internas e as transferências de tokens.
  • Bitcoin usa o mempool.space para normalizar as entradas e saídas da transação.
  • Solana usa o Helius para normalizar transferências nativas de SOL, transferências de tokens SPL e o contexto disponível de eventos de NFT.
Cada item de transaction_flows[] inclui campos normalizados estáveis (flow_type, from_address, to_address, amount, amount_usd, currency, token_name, token_address, transaction_hash, block_timestamp, index, success), além de metadata específico do provedor. Exemplos comuns de metadata:
metadata é aditivo e específico do provedor. Não crie integrações críticas que exijam que todas as chaves estejam presentes para todas as cadeias.

​
Travel Rule

null quando a transação não tem transferência nem verificação de Travel Rule. Ele é preenchido quando você envia travel_rule_details e também quando a Travel Rule está habilitada para a aplicação e a transação foi criada com transaction_category: "travelRule": nesse caso, a Didit inicia a troca por conta própria, com ou sem travel_rule_details, e informa o status aqui. Leia este campo em vez da requisição que você enviou. Em uma transferência recebida, os dados originator_data e beneficiary_data da contraparte permanecem mascarados (data_masked: true) até que a propriedade da carteira seja confirmada (consulte Dados mascarados da contraparte).
direction, rail, counterparty_vasp, delivery, discovery, reason e next_actions têm o mesmo formato que no endpoint de transferência. reason e next_actions explicam por que uma transferência COUNTERPARTY_VASP_NOT_FOUND ou COUNTERPARTY_VASP_NOT_REACHABLE está parada e o que a faz avançar, e são "" e [] para qualquer outro status: consulte Por que uma transferência está parada. Cada linha de GET /v3/transactions/ traz o mesmo bloco. Consulte Travel Rule.

​
Snapshot da rede

O próprio grafo armazenado, não uma referência a ele. Ele vem de uma destas fontes:
  • um network_snapshot que você enviou com a transação, ou
  • o grafo que a Didit constrói quando a triagem de carteiras AML é concluída com sucesso para uma transação cripto, mesmo que a requisição não tenha incluído network_snapshot. Um grafo construído pela triagem substitui um grafo enviado, e uma nova triagem assíncrona o atualiza.
null quando nenhum dos dois existe:
A página de detalhes da transação no console renderiza o mesmo grafo.

​
Tags, metadados, props

  • tags[]: tags anexadas (por ação de regra ou por um analista): { "uuid", "name", "color", "description", "source" }, em que source é didit para uma tag predefinida e custom para uma das suas.
  • metadata: um snapshot dos payloads subject e counterparty exatamente como você os enviou no momento da criação, sob essas duas chaves.
  • props: as custom_properties que você forneceu no momento da criação. Cada chave pode ser referenciada nas condições de regra como custom_values.<key>.

​
Remediação

Quando uma regra aciona AWAITING_USER, a Didit cria a sessão de verificação vinculada e a retorna em dois campos:
  • remediation: a sessão vinculada: { "session_id", "session_token", "url", "status" }. Permanece preenchido durante toda a vida da transação, para que você sempre possa ver como terminou a ação do usuário.
  • action_required: a ação que o usuário deve realizar agora, ou null quando não há nada pendente: { "type": "verification_session", "url", "session_id", "session_token", "status" }. Redirecione o usuário para url ou passe session_token para um SDK da Didit. As ações de propriedade de carteira da Travel Rule usam { "type": "wallet_ownership", "url", "widget_session_id", "expires_at" } e têm precedência quando ambas puderem se aplicar. Quando uma ação de propriedade de carteira está pendente e a contraparte da transferência não pôde ser encontrada, o mesmo bloco também traz reason e next_actions (consulte descoberta da contraparte).
Os mesmos dois campos acompanham os payloads dos webhooks transaction.created e transaction.status.updated (action_required). Consulte webhooks.

​
Detalhamento de custos

null até que um recurso faturável tenha sido executado para a transação. Caso contrário, { "total_price", "items": [ { "usage_type", "price", "details" } ] }, com um item por recurso medido (triagem, enriquecimento e assim por diante).

​
Conversão de moeda

preferred_currency_amount é o amount convertido para a moeda preferida da sua aplicação pela taxa de câmbio média do mercado, a menos que você tenha informado amount_in_default_currency; nesse caso, esse valor já convertido é usado sem alterações. As condições de regra sobre amount comparam o valor na moeda original; use preferred_currency_amount nas condições quando precisar de um único limiar para todas as moedas.

​
Próximos passos

Enviar transações

Esquema completo da requisição.

Status

O que cada status significa.

Pontuação de risco

Como a pontuação é calculada.
Última modificação em 1 de novembro de 2026