Saltar para o conteúdo principal
Esta página documenta o payload completo devolvido por POST /v3/transactions/ e GET /v3/transactions/{transaction_id}/. Ambos os endpoints devolvem o mesmo objeto TransactionDetail; a referência da API contém o esquema campo a campo, e esta página explica-o.

​
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 respetivo caminho; txn_id é o transaction_id que forneceu na criação. transaction_number é o número sequencial no âmbito da aplicação, que a consola apresenta. O sujeito e a contraparte que submeteu não são devolvidos como chaves de nível superior. Estão nas entradas do array parties, distinguidas pelo role, e o vendor_data de nível superior é uma cópia de conveniência do vendor_data do requerente.

​
Campos principais

​
Campos financeiros

  • amount / currency: montante da transação tal como foi enviado. amount é uma string decimal sem zeros finais ("1500", "0.5"), com até 18 casas decimais.
  • currency_type: fiat ou crypto, tal como enviado em currency_kind; null quando omitido.
  • amount_in_default_currency / default_currency_code: o montante pré-convertido que indicou no pedido, devolvido tal como foi enviado; null quando não enviou nenhum.
  • preferred_currency_amount / preferred_currency_code: amount convertido para a moeda preferida da sua aplicação. null quando não existe taxa de câmbio disponível para currency e não enviou amount_in_default_currency.
  • payment_details / payment_txn_id: a referência de pagamento em texto livre e a referência de pagamento externa (por exemplo, um hash de transação blockchain) do pedido.

​
Campos de estado

  • 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 mais alta, maior o risco.
  • severity: UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL, ou null até que uma regra ou um fornecedor a defina.
  • decision_reason_code / decision_reason_label: motivo estruturado e motivo legível para o estado atual.
  • environment: live ou sandbox, a partir da aplicação que detém a transação. Uma transação sandbox é armazenada mas nunca avaliada, pelo que o seu rule_runs vazio significa “não avaliada” e não “nenhuma regra correspondeu”. Consulte Monitorização de transações em sandbox.
  • source: LIVE para transações enviadas através da API ou do SDK, IMPORTED para transações carregadas através da importação de CSV na consola.

​
Intervenientes

Todos os intervenientes da transação são entradas em parties. O endpoint de criação regista o sujeito como APPLICANT e a contraparte opcional como COUNTERPARTY; o enum role inclui também REMITTER e BENEFICIARY. Todas as entradas têm a mesma estrutura.
  • role: APPLICANT, COUNTERPARTY, REMITTER, BENEFICIARY. Filtre por este campo para encontrar o sujeito.
  • entity_type: individual, company, external, unhostedWallet, tal como enviado.
  • kind: USER ou BUSINESS quando o interveniente está ligado a um utilizador ou a uma empresa da Didit através de vendor_data; EXTERNAL caso contrário.
  • country_code / dob: a partir de address.country e date_of_birth enviados.
  • address / institution_info: os objetos tal como foram enviados; {} quando omitidos.
  • external_party_snapshot: cópia congelada dos dados do interveniente para intervenientes EXTERNAL; null enquanto o interveniente estiver ligado a um utilizador ou a uma empresa da Didit.

​
device

device é o device_context que enviou para esse interveniente, normalizado para snake_case, com o enriquecimento de IP do lado do servidor. É {} quando o pedido não incluiu contexto de dispositivo, pelo que deve tratar sempre todas as chaves como opcionais. Não existe um objeto de enriquecimento separado. Quando o interveniente enviou um network_context.ip_address público, a Didit resolve-o em linha e escreve os campos enriquecidos no mesmo objeto network_context, preenchendo apenas as chaves que não enviou. As chaves que o resolvedor devolveu vazias são omitidas, pelo que um network_context totalmente enriquecido contém as quatro chaves enviadas (ip_address, ip_country_code, latitude, longitude), mais as de 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 que tenham sido resolvidas. 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 é devolvido exatamente como foi enviado, quando o IP está em falta 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 alpha-2 quando a Didit o resolveu e, caso contrário, é o valor que enviou; as condições das regras normalizam ambas as 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: numa transação de saída, o método do sujeito é o SOURCE e o da contraparte é o DESTINATION; numa 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 possa correlacionar a reutilização do mesmo instrumento. null quando não foi enviado nenhum account_id.
  • owner_kind / vendor_data / owner_name: quem é o titular do instrumento, seguindo a mesma convenção USER / BUSINESS / EXTERNAL dos intervenientes.
  • details: o objeto payment_method original, tal como foi enviado.

​
Execuções de regras

  • rule: UUID da regra que foi executada; rule_title, rule_description e rule_category são copiados dela.
  • matched: uma execução só é registada quando as condições da regra correspondem, pelo que as avaliações em produção têm sempre matched: true. As regras avaliadas sem correspondência não deixam registo. Os 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 é registada, mas não tem efeito em status, score ou severity.
  • score_delta / status_target / severity: o contributo desta execução. status_target é definido quando foi executada uma ação change_status ou quando a pontuação acrescentada ultrapassou um limiar.
  • action_summary: string com o resumo das ações executadas pela regra, 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, bem como 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; só é classificado para eventos de monitorização.
    • aggregations[]: uma entrada por agregação de velocidade, contagem ou soma, com metric, field, operator, expected_value, o computed_value resultante da avaliação da agregação, window, filters, matched e sample_references. As agregações que só puderam ser calculadas de forma assíncrona têm computed_value: null e deferred: true.

​
Alertas

alerts é sempre uma lista vazia de momento. Um alerta aberto corresponde a uma transação retida, por isso consulte status (IN_REVIEW ou AWAITING_USER). Consulte Alertas.

​
Atividades

O registo de atividade da transação: criação, notas, revisões manuais e alterações de estado.
As notas do analista aparecem aqui como entradas TRANSACTION_NOTE_ADDED; não existe um array notes separado.

​
Documentos

Ficheiros anexados à transação a partir da consola. [] quando não existe nenhum.
file_url é um URL assinado de curta duração; obtenha-o quando precisar, em vez de o guardar.

​
Resultados dos prestadores

Resultados devolvidos por prestadores externos (triagem de hashes de transações, triagem de carteiras, monitorização de moeda fiduciária, 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: o que produziu o veredicto, primeiro os fatores de risco elevado e, depois, por valor movimentado. Um score elevado sem entrada is_high_risk significa que o prestador classificou a entidade com base no seu próprio modelo de exposição, sem reportar uma correspondência com sanções ou com entidade atribuída; o summary indica-o explicitamente. Referência campo a campo: Fatores de risco. Os resultados triados antes de existir este campo não incluem a chave. Na triagem de hashes de transações cripto, transaction_flows é preenchido quando o enriquecimento on-chain está disponível. Normaliza a atividade da cadeia para que a consola possa apresentar, a partir do mesmo payload de resposta, tanto a visão geral da transação como o grafo de visualização. Fontes de enriquecimento suportadas:
  • As cadeias EVM usam o Blockscout para normalizar a transação principal, as chamadas internas e as transferências de tokens.
  • O Bitcoin usa o mempool.space para normalizar as entradas e saídas da transação.
  • A Solana usa a Helius para normalizar as transferências nativas de SOL, as transferências de tokens SPL e o contexto disponível dos 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 prestador. Exemplos comuns de metadata:
metadata é aditivo e específico de cada prestador. Não crie integrações críticas que exijam que todas as chaves estejam presentes em todas as cadeias.

​
Travel Rule

null quando a transação não tem nenhuma transferência nem verificação da Travel Rule. Fica preenchido quando envia travel_rule_details, e também quando a Travel Rule está ativada para a aplicação e a transação foi criada com transaction_category: "travelRule": nesse caso, a Didit inicia a troca por si própria, com ou sem travel_rule_details, e indica aqui o respetivo status. Leia este campo em vez do pedido que enviou. Numa transferência recebida, os originator_data e beneficiary_data da contraparte permanecem mascarados (data_masked: true) até a propriedade da carteira ser confirmada (consulte Dados da contraparte mascarados).
direction, rail, counterparty_vasp, delivery, discovery, reason e next_actions têm a mesma estrutura que no endpoint de transferência. reason e next_actions indicam porque é que uma transferência COUNTERPARTY_VASP_NOT_FOUND ou COUNTERPARTY_VASP_NOT_REACHABLE está bloqueada e o que a faz avançar, e têm os valores "" e [] para qualquer outro estado: consulte Porque está bloqueada uma transferência. Cada linha de GET /v3/transactions/ inclui o mesmo bloco. Consulte Travel Rule.

​
Instantâneo da rede

O próprio grafo armazenado, e não uma referência a ele. Provém de uma das seguintes fontes:
  • um network_snapshot que enviou com a transação, ou
  • o grafo que a Didit constrói quando a triagem AML de carteiras é bem-sucedida numa transação cripto, mesmo que o pedido não tenha incluído network_snapshot. Um grafo construído pela triagem substitui um grafo enviado, e uma nova triagem assíncrona atualiza-o.
null quando nenhum dos dois existe:
A página de detalhe da transação na consola apresenta o mesmo grafo.

​
Etiquetas, metadados e propriedades

  • tags[]: etiquetas associadas (por ação de uma regra ou pelo analista): { "uuid", "name", "color", "description", "source" }, em que source é didit para uma etiqueta predefinida e custom para uma das suas.
  • metadata: um instantâneo dos payloads de subject e counterparty exatamente como os enviou na criação, sob essas duas chaves.
  • props: os custom_properties que forneceu na criação. Cada chave pode ser referenciada nas condições das regras como custom_values.<key>.

​
Remediação

Quando uma regra dispara AWAITING_USER, a Didit cria a sessão de verificação associada e devolve-a em dois campos:
  • remediation: a sessão associada: { "session_id", "session_token", "url", "status" }. Permanece preenchido durante toda a vida da transação, pelo que pode ver sempre como terminou a ação do utilizador.
  • action_required: a ação que o utilizador tem de executar neste momento, ou null quando não existe nenhuma pendente: { "type": "verification_session", "url", "session_id", "session_token", "status" }. Redirecione o utilizador para url ou passe session_token a um SDK da Didit. As ações de propriedade da carteira da Travel Rule usam { "type": "wallet_ownership", "url", "widget_session_id", "expires_at" } e têm prioridade quando ambas podem aplicar-se. Quando uma ação de propriedade da carteira está pendente e não foi possível encontrar a contraparte da transferência, o mesmo bloco inclui também reason e next_actions (consulte descoberta da contraparte).
Os mesmos dois campos também constam dos payloads dos webhooks transaction.created e transaction.status.updated (action_required). Consulte webhooks.

​
Detalhe de custos

null até que uma funcionalidade faturável seja executada para a transação. Caso contrário, { "total_price", "items": [ { "usage_type", "price", "details" } ] }, com um item por funcionalidade contabilizada (triagem, enriquecimento e outras).

​
Conversão de moeda

preferred_currency_amount é o amount convertido para a moeda preferida da sua aplicação, às taxas médias de mercado, a menos que tenha fornecido amount_in_default_currency, caso em que esse valor já convertido é usado tal como está. As condições de regras sobre amount comparam o montante na moeda de origem; use preferred_currency_amount nas condições quando precisar de um único limiar para todas as moedas.

​
Próximos passos

Submeter transações

Esquema completo do pedido.

Estados

O que significa cada estado.

Pontuação de risco

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