> ## 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 consulta de transação: detalhes de KYT
> Consulte uma transação KYT na Didit: partes, meios de pagamento, alertas, regras acionadas, Travel Rule, links de remediação e snapshots de rede.
Prompt da API de obtenção de transação
Copiar o prompt para a área de transferência
\
\`Fetch the full detail of a Didit monitored transaction through the Management API.
Endpoint:
GET https://verification.didit.me/v3/transactions/{transaction_id}/
Authentication:
Use the x-api-key header with my Didit API key.
Goal:
\- Retrieve every detail of a transaction — linked parties, payment methods, alerts, rule matches, travel-rule checks, remediation links, network snapshots, cost breakdown — so I can render a detail screen or feed a downstream decision.
Path parameter:
\- transaction_id - Didit's transaction uuid (the uuid returned by POST /v3/transactions/).
Your own txn_id is not accepted here and returns 404.
Example call:
curl -X GET "https://verification.didit.me/v3/transactions/{transaction_id}/" \
-H "x-api-key: YOUR_API_KEY"
What to read from the response:
\- uuid, transaction_number, txn_id — identifiers.
\- status, score, severity, decision_reason_code, decision_reason_label — current verdict.
\- direction, amount, currency, currency_type, action_type, payment_details, payment_txn_id - the submitted details as top-level fields (there is no transaction_details object, and currency_type carries the currency_kind you sent).
\- parties - party records with role APPLICANT (the subject) or COUNTERPARTY (the other side) and kind USER, BUSINESS or EXTERNAL, each with entity_type, vendor_data, full_name, address and device.
\- payment_methods - the linked payment methods, each with payment_method_type, account_id and role (for example SOURCE or DESTINATION).
\- cost_breakdown — provider-by-provider cost detail for this transaction.
\- rule_runs / alerts — which rules fired and their outcomes.
\- provider_results - crypto screening (blockchain analytics) results, when a screening ran.
\- travel_rule - the Travel Rule transfer (uuid, status, protocol, required, obligations_count, originator_data, beneficiary_data, metadata, direction, rail, counterparty_vasp, delivery, discovery, reason, next_actions), or null when the transaction has none.
For a COUNTERPARTY_VASP_NOT_FOUND or COUNTERPARTY_VASP_NOT_REACHABLE transfer, reason says why it is stuck and next_actions what moves it on: email_undeliverable offers update_compliance_email then resend, delivery_failed offers resend, and a discovery reason (awaiting_end_user, directory_match_no_route, picked_member_without_proven_wallet, no_directory_match) offers select_counterparty_vasp, declare_self_hosted, add_vasp_hint and resend.
delivery is the newest message the transfer owes the other side (kind, status, rail, attempts, last_error, next_attempt_at, delivered_at), or null; discovery is the trace of where Didit looked for the counterparty.
On an inbound transfer, the counterparty's originator_data and beneficiary_data stay masked (data_masked: true) until wallet ownership is confirmed.
\- tags — Console tags (uuid, name, color).
\- assigned_to_name (the Console reviewer) is not part of this response; the list endpoint GET /v3/transactions/ returns it.
Use cases:
\- Render the Console-equivalent "Transaction detail" screen in your back-office.
\- Reconcile rule outcomes against your own ledger.
\- Poll after a transaction.status.updated webhook to fetch the fresh verdict.
Failure modes:
\- 403 - missing x-api-key (a wrong, revoked or expired key gets 401), or a key without permission for this action ({ "detail": "..." } envelope).
\- 404 - transaction not found in this application, including a transaction that belongs to another application (or deleted via the Console).
\- 429 — rate limited; back off and retry.
Side effects: none. This is a pure read.
For the full integration shape, see /integration/integration-prompt.`
\
Colar em
## OpenAPI
````yaml pt-br/openapi-25.json GET /v3/transactions/{transaction_id}/
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/transactions/{transaction_id}/:
get:
tags:
- Transactions
summary: Obter transação
description: >-
Recupera o registro completo de monitoramento de uma transação: partes,
pontuação/gravidade, execuções de regras, alertas, resultado da Travel
Rule e sessão de remediação.
operationId: getTransaction
parameters:
- name: transaction_id
in: path
required: true
description: >-
UUID estável da transação na Didit (o `uuid` retornado por create /
list, **não** o seu `txn_id`).
schema:
type: string
format: uuid
example: abcdef12-3456-7890-abcd-ef1234567890
responses:
'200':
description: Detalhes completos da transação.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionDetail'
examples:
In review with an alert:
value:
uuid: abcdef12-3456-4890-abcd-ef1234567890
environment: live
transaction_number: 4123
txn_id: your-txn-2026-05-17-001
txn_date: '2026-05-17T08:42:00Z'
zone_id: Europe/Madrid
transaction_type: finance
action_type: withdrawal
direction: OUTBOUND
status: IN_REVIEW
source: LIVE
amount: '1500'
currency: EUR
currency_type: fiat
amount_in_default_currency: '1620.45'
default_currency_code: USD
preferred_currency_amount: '1620.45'
preferred_currency_code: USD
payment_details: Withdrawal to crypto wallet
payment_txn_id: null
score: 78
severity: HIGH
decision_reason_code: WALLET_HIGH_RISK
decision_reason_label: Destination wallet flagged as high risk
vendor_data: user-12345
metadata:
subject:
entity_type: individual
vendor_data: user-12345
full_name: Maria Garcia
address: {}
institution_details: {}
device_context: {}
counterparty: {}
props:
order_id: ord-9988
tags: []
parties:
- uuid: b1111111-2222-4333-8444-555555555555
role: APPLICANT
entity_type: individual
kind: USER
vendor_data: user-12345
full_name: Maria Garcia
first_name: null
last_name: null
country_code: null
dob: null
address: {}
institution_info: {}
device: {}
external_party_snapshot: null
payment_methods: []
documents: []
activities: []
alerts:
- uuid: a7b8c9d0-1234-4abc-9def-567890abcdef
title: Destination wallet flagged as high risk
description: Provider risk score exceeded the configured threshold.
severity: HIGH
status: OPEN
source: RULE
metadata: {}
created_at: '2026-05-17T08:42:12Z'
due_at: null
rule_runs: []
provider_results: []
travel_rule: null
network_snapshot: null
remediation: null
action_required: null
cost_breakdown: null
'403':
description: >-
Chave de API ausente, inválida ou revogada, ou a chave não pode ler
as transações desta aplicação. Uma chave ausente retorna `403`; uma
chave incorreta, revogada ou expirada retorna `401`.
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'404':
description: >-
Não existe nenhuma transação com este UUID na aplicação (excluída,
nunca criada, pertencente a outra aplicação, ou o segmento do
caminho não é um UUID válido).
content:
application/json:
examples:
Not found:
value:
detail: Not found.
'429':
description: >-
Limite de requisições excedido; aguarde e tente novamente após o
intervalo indicado em `Retry-After`.
content:
application/json:
examples:
Throttled:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X GET
'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/'
\
-H 'x-api-key: YOUR_API_KEY'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.transactions.retrieve(
"abcdef12-3456-7890-abcd-ef1234567890",
)
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.transactions.retrieve("abcdef12-3456-7890-abcd-ef1234567890");
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Retrieve(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.transactions().retrieve("abcdef12-3456-7890-abcd-ef1234567890");
System.out.println(result);
- lang: php
label: PHP
source: >-
transactions->retrieve('abcdef12-3456-7890-abcd-ef1234567890');
print_r($result->toArray());
- lang: ruby
label: Ruby
source: >-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result =
didit.transactions.retrieve("abcdef12-3456-7890-abcd-ef1234567890")
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await
client.Transactions.RetrieveAsync("abcdef12-3456-7890-abcd-ef1234567890");
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
TransactionDetail:
type: object
description: >-
Registro de monitoramento completo de uma transação, conforme retornado
por `GET /v3/transactions/{transaction_id}/` e `POST /v3/transactions/`.
properties:
uuid:
type: string
format: uuid
description: >-
Identificador estável da transação na Didit. Use como
`{transaction_id}` nas chamadas subsequentes.
environment:
type: string
enum:
- live
- sandbox
description: >-
Ambiente da aplicação proprietária da transação. Uma transação
`sandbox` é armazenada, mas nunca é avaliada, analisada, notificada
ou cobrada, portanto o seu `rule_runs` vazio significa "não
avaliada".
transaction_number:
type: integer
description: >-
Número sequencial da transação no escopo da aplicação exibido no
Console (por exemplo, `4123`).
txn_id:
type: string
description: >-
O `transaction_id` que você informou na criação (máximo de 128
caracteres). Único por aplicação.
txn_date:
type: string
format: date-time
description: >-
Quando a transação ocorreu (a partir de `transaction_at`; o padrão é
o momento do envio).
zone_id:
type: string
nullable: true
description: Identificador de fuso horário IANA informado na criação.
transaction_type:
type: string
description: >-
Categoria de nível superior, como armazenada: `finance`, `kyc`,
`travelRule`, `userPlatformEvent`, `gamblingBet`,
`gamblingLimitChange`, `gamblingBonusChange`, `auditTrailEvent`.
Observe que valores com várias palavras são retornados em camelCase
mesmo quando enviados em snake_case.
action_type:
type: string
description: >-
Subtipo dentro da categoria (por exemplo `deposit`, `withdrawal`,
`transfer`). O padrão é a categoria quando não for informado.
direction:
type: string
enum:
- INBOUND
- OUTBOUND
description: >-
Direção em relação ao titular. Armazenada em maiúsculas,
independentemente da caixa usada no envio
(`in`/`out`/`inbound`/`outbound` são aceitos na entrada).
status:
type: string
enum:
- APPROVED
- IN_REVIEW
- DECLINED
- AWAITING_USER
description: >-
Veredito de monitoramento atual. As transações são criadas como
`APPROVED`; as regras podem alterá-las para `IN_REVIEW`/`DECLINED`
de forma síncrona.
source:
type: string
enum:
- LIVE
- IMPORTED
description: >-
Como o registro se originou: `LIVE` para transações enviadas pela
API ou pelo SDK, `IMPORTED` para transações carregadas pela
importação do console.
amount:
type: string
description: >-
Valor da transação como string decimal, sem zeros à direita (por
exemplo, `"1500"`, `"0.5"`, `"0.123456789012345678"`). Até 18 casas
decimais.
currency:
type: string
description: >-
Código da moeda de `amount`. Qualquer código alfabético ISO 4217 é
aceito (por exemplo, `EUR`, `USD`, `NGN`), assim como um símbolo de
ativo cripto (por exemplo, `BTC`). Prefira um código atualmente em
circulação. Nem todo código aceito tem taxa de câmbio: quando não há
nenhuma disponível para o código (por exemplo, a unidade contábil
ISO `XSU` ou um símbolo cripto que a Didit não precifica), a
conversão automática falha e `preferred_currency_amount` é retornado
como null, a menos que a requisição tenha fornecido um
`amount_in_default_currency` já convertido.
currency_type:
type: string
nullable: true
description: '`fiat` ou `crypto`, conforme enviado em `currency_kind`.'
amount_in_default_currency:
type: string
nullable: true
description: >-
Valor já convertido que você informou, como string decimal sem zeros
à direita.
default_currency_code:
type: string
nullable: true
preferred_currency_amount:
type: string
nullable: true
description: >-
`amount` convertido para a moeda preferida da aplicação, quando
disponível.
preferred_currency_code:
type: string
nullable: true
payment_details:
type: string
nullable: true
description: Referência ou memorando de pagamento em texto livre do envio.
payment_txn_id:
type: string
nullable: true
description: >-
Referência do sistema de pagamento externo (por exemplo, hash da
transação na blockchain) obtida de `payment_reference_id`.
score:
type: integer
description: >-
Pontuação de risco acumulada pelas regras (normalmente de 0 a 100).
Quanto maior, mais arriscado.
severity:
type: string
nullable: true
enum:
- UNKNOWN
- LOW
- MEDIUM
- HIGH
- CRITICAL
description: >-
Gravidade categórica do risco definida por regras ou provedores
(`UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`). `null` até que
algo a defina.
decision_reason_code:
type: string
nullable: true
description: Motivo legível por máquina do `status` atual.
decision_reason_label:
type: string
nullable: true
description: Rótulo legível de `decision_reason_code`.
vendor_data:
type: string
nullable: true
description: Cópia de conveniência do `vendor_data` do solicitante.
metadata:
type: object
description: >-
Snapshot dos payloads `subject` e `counterparty` como foram enviados
no momento da criação.
props:
type: object
description: >-
As `custom_properties` que você informou na criação. Cada chave pode
ser referenciada nas condições de regras como `custom_values.`.
tags:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description:
type: string
nullable: true
source:
type: string
enum:
- didit
- custom
description: Se a tag é uma predefinição da Didit ou uma tag personalizada.
description: Tags anexadas à transação (manualmente ou por regras).
parties:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
role:
type: string
enum:
- APPLICANT
- REMITTER
- BENEFICIARY
- COUNTERPARTY
description: >-
Função da parte. O endpoint de criação atribui `APPLICANT` (o
titular) e `COUNTERPARTY`.
entity_type:
type: string
enum:
- individual
- company
- external
- unhostedWallet
kind:
type: string
enum:
- USER
- BUSINESS
- EXTERNAL
description: >-
Partes `USER`/`BUSINESS` se vinculam a uma entidade da Didit
por meio de `vendor_data`. Partes `EXTERNAL` não têm nenhuma
entidade da Didit por trás.
vendor_data:
type: string
nullable: true
description: Seu identificador interno de usuário/empresa.
full_name:
type: string
nullable: true
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
country_code:
type: string
nullable: true
description: >-
Código do país a partir do `address.country` enviado
(normalmente ISO 3166-1 alpha-3).
dob:
type: string
format: date
nullable: true
description: Data de nascimento do `date_of_birth` enviado.
address:
type: object
description: Objeto de endereço conforme enviado. `{}` quando omitido.
institution_info:
type: object
description: Dados da instituição conforme enviados. `{}` quando omitidos.
device:
type: object
description: >-
Contexto normalizado do dispositivo, incluindo o
enriquecimento de IP no servidor em network_context
(geolocalização, indicadores de VPN/data center) quando um IP
foi informado.
properties:
fingerprint:
type: string
description: Impressão digital única do dispositivo.
persistent_device_id:
type: string
description: >-
Identificador estável do dispositivo entre sessões
(esquema de fingerprint v2).
user_agent:
type: string
description: String de user agent do navegador ou do app.
browser_family:
type: string
description: >-
Família do navegador (por exemplo, Chrome, Firefox,
Safari).
browser_version:
type: string
description: String da versão do navegador.
platform:
type: string
description: >-
Identificador da plataforma (web, ios, android, macos,
windows, linux).
os_family:
type: string
description: >-
Família do sistema operacional (por exemplo, iOS, Android,
Windows).
os_version:
type: string
description: String de versão do sistema operacional.
accept_language:
type: string
description: Valor do cabeçalho Accept-Language.
session_id:
type: string
description: Identificador da sessão (armazenado nos metadados).
session_age_ms:
type: number
description: Idade da sessão em milissegundos.
network_context:
type: object
description: Contexto de rede com endereço IP e geolocalização.
properties:
ip_address:
type: string
description: Endereço IP do cliente.
ip_country_code:
type: string
description: >-
País do IP resolvido por geolocalização (ISO 3166-1
alpha-3).
latitude:
type: number
description: Latitude geográfica do IP.
longitude:
type: number
description: Longitude geográfica do IP.
external_party_snapshot:
type: object
nullable: true
description: >-
Cópia congelada dos dados da parte para partes `EXTERNAL`.
`null` enquanto a parte estiver vinculada a um usuário ou
empresa da Didit.
description: Partes da transação (solicitante, contraparte).
payment_methods:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
payment_method_type:
type: string
enum:
- bank_card
- bank_account
- e_wallet
- crypto_wallet
- unhosted_wallet
- other
label:
type: string
nullable: true
fingerprint:
type: string
nullable: true
description: >-
SHA-256 sobre `type:account_id:issuing_country`: identificador
estável para correlacionar a reutilização do mesmo
instrumento.
account_id:
type: string
nullable: true
description: >-
Identificador da conta (IBAN, endereço de carteira, token de
cartão, …).
issuing_country:
type: string
nullable: true
owner_kind:
type: string
enum:
- USER
- BUSINESS
- EXTERNAL
vendor_data:
type: string
nullable: true
description: Seu identificador do usuário/empresa proprietário.
owner_name:
type: string
nullable: true
institution_info:
type: object
details:
type: object
description: Objeto `payment_method` bruto, conforme enviado.
external_owner_snapshot:
type: object
nullable: true
role:
type: string
enum:
- SOURCE
- DESTINATION
- FUNDING
- BENEFICIARY
description: >-
Como este método foi usado na transação. O endpoint de criação
atribui `SOURCE`/`DESTINATION` com base na direção (saída:
titular = SOURCE; entrada: titular = DESTINATION).
description: Meios de pagamento vinculados à transação.
documents:
type: array
description: >-
Arquivos anexados à transação pelo console. `[]` quando não há
nenhum.
items:
type: object
properties:
uuid:
type: string
format: uuid
label:
type: string
nullable: true
note:
type: string
nullable: true
uploaded_by:
type: string
nullable: true
created_at:
type: string
format: date-time
files:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
file_url:
type: string
format: uri
nullable: true
description: >-
URL de download assinada de curta duração; obtenha-a
quando necessário em vez de armazená-la.
original_filename:
type: string
nullable: true
file_size:
type: integer
nullable: true
activities:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
activity_type:
type: string
description: >-
Por exemplo, `TRANSACTION_CREATED`, `TRANSACTION_NOTE_ADDED`,
`TRANSACTION_STATUS_CHANGED`.
source:
type: string
status:
type: string
nullable: true
title:
type: string
nullable: true
description:
type: string
nullable: true
metadata:
type: object
occurred_at:
type: string
format: date-time
description: >-
Entradas do registro de atividades (criação, notas, revisões
manuais, alterações de status).
alerts:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
title:
type: string
description:
type: string
nullable: true
severity:
type: string
enum:
- UNKNOWN
- LOW
- MEDIUM
- HIGH
- CRITICAL
status:
type: string
enum:
- OPEN
- INVESTIGATING
- AWAITING_USER
- PENDING_SAR
- SAR_FILED
- RESOLVED
- DISMISSED
source:
type: string
enum:
- RULE
- PROVIDER
- MANUAL
metadata:
type: object
created_at:
type: string
format: date-time
due_at:
type: string
format: date-time
nullable: true
description: >-
Sempre vazio atualmente. Um alerta aberto é uma transação com status
`IN_REVIEW` ou `AWAITING_USER`.
rule_runs:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
rule:
type: string
format: uuid
description: UUID da regra que foi executada.
rule_title:
type: string
rule_description:
type: string
nullable: true
rule_category:
type: string
matched:
type: boolean
description: >-
Se as condições da regra corresponderam a esta transação. Uma
execução é registrada apenas para regras correspondidas, então
as avaliações em produção sempre trazem `true`.
is_test:
type: boolean
description: >-
True quando a regra foi executada no modo TEST (sem efeito no
status/pontuação).
mode:
type: string
enum:
- ACTIVE
- DISABLED
- TEST
severity:
type: string
nullable: true
score_delta:
type: integer
description: Pontuação adicionada pelas ações `add_score` desta regra.
status_target:
type: string
nullable: true
description: Status definido por uma ação `change_status`, se houver.
action_summary:
type: string
nullable: true
description: >-
Resumo das ações que a regra executou, unidas com `; ` (por
exemplo, `score +30; change_status:IN_REVIEW;
add_tag:high_risk_country`). Partes: `score +N`,
`change_status:`, `add_tag:`, `add_note`,
`add_to_list`, `open_case`. `null` quando a regra não executou
nenhuma ação.
metadata:
type: object
description: >-
Detalhe da avaliação: `scope_match`, `conditions[]` e
`aggregations[]`. Cada entrada de condição contém `field`,
`operator`, `expected_value`, o `current_value` lido da
transação, `matched`, `group_index` e `group_logic`. Cada
entrada de agregação (velocidade / contagem / soma) contém
`metric`, `field`, `operator`, `expected_value`, o
`computed_value` resultante da agregação, `window`, `filters`,
`matched` e `sample_references`; agregações assíncronas
adiadas têm `computed_value: null` e `deferred: true`. Um
grupo de condições aninhado é uma entrada de `conditions[]`
com `operator` `any_of` ou `all_of`, `field` nulo e os
resultados dos seus membros em seu próprio `conditions`.
created_at:
type: string
format: date-time
description: >-
Resultados de execução por regra: qual regra foi acionada e com qual
impacto na pontuação.
provider_results:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
provider:
type: string
result_type:
type: string
enum:
- FIAT_MONITORING
- WALLET_SCREENING
- TRANSACTION_SCREENING
- TRAVEL_RULE
- NETWORK_GRAPH
- CUSTOM
status:
type: string
severity:
type: string
nullable: true
score:
type: integer
summary:
type: string
nullable: true
payload:
type: object
description: Payload bruto da resposta do provedor.
created_at:
type: string
format: date-time
description: >-
Payloads brutos dos provedores (Análise AML, análise de blockchain
etc.).
travel_rule:
nullable: true
allOf:
- $ref: '#/components/schemas/TransactionTravelRule'
description: >-
Transferência ou verificação da Travel Rule. Preenchido quando
`travel_rule_details` foi enviado e também quando a Travel Rule está
ativada e a transação foi criada com `transaction_category:
travelRule` (a própria Didit inicia a troca, mesmo sem
`travel_rule_details`). `null` quando não existe transferência nem
verificação. Em uma transferência de entrada, os `originator_data` e
`beneficiary_data` da contraparte permanecem mascarados
(`data_masked: true`) até que a propriedade da carteira seja
confirmada.
network_snapshot:
type: object
nullable: true
description: >-
Snapshot do grafo de transações/partes relacionadas usado pelo motor
de regras. É o `network_snapshot` enviado com a transação ou o grafo
que a Didit constrói a partir de uma triagem AML de carteira
bem-sucedida (que substitui o enviado). `null` quando nenhum dos
dois existe.
properties:
uuid:
type: string
format: uuid
nodes:
type: array
items:
type: object
edges:
type: array
items:
type: object
metrics:
type: object
remediation:
type: object
nullable: true
description: >-
Sessão de correção oferecida ao usuário quando a reverificação é
necessária. Substituída por `action_required`, que é o bloco
canônico; mantida por compatibilidade com versões anteriores.
properties:
session_id:
type: string
session_token:
type: string
url:
type: string
format: uri
status:
type: string
action_required:
type: object
nullable: true
description: >-
Ação pendente do usuário final necessária para concluir esta
transação, ou null quando não houver nenhuma. Os SDKs da Didit
iniciam a ação automaticamente por padrão e atualizam a transação
quando ela termina. Há duas variantes, diferenciadas por `type`:
`verification_session` (uma sessão de verificação hospedada criada
por uma ação de regra) e `wallet_ownership` (uma sessão do widget de
propriedade da carteira gerada automaticamente para uma
transferência da Travel Rule que exige prova de controle da
carteira, condicionada à configuração `auto_wallet_verification` da
Travel Rule). Quando ambas puderem se aplicar, `wallet_ownership`
tem precedência, pois bloqueia a troca da Travel Rule.
oneOf:
- $ref: '#/components/schemas/TransactionVerificationSessionAction'
- $ref: '#/components/schemas/TransactionWalletOwnershipAction'
discriminator:
propertyName: type
mapping:
verification_session: '#/components/schemas/TransactionVerificationSessionAction'
wallet_ownership: '#/components/schemas/TransactionWalletOwnershipAction'
cost_breakdown:
type: object
nullable: true
description: >-
Custo desta transação: `total_price` e `items`, um por cobrança,
cada um com `usage_type`, `price`, `details` e `created_at`. Uma
nova triagem da mesma transação gera um novo item.
TransactionTravelRule:
type: object
description: >-
A transferência Travel Rule de uma transação, como retornada por `GET
/v3/transactions/{transaction_id}/`, pela resposta `201` de `POST
/v3/transactions/` e por cada linha de `GET /v3/transactions/`.
`direction`, `rail`, `counterparty_vasp`, `delivery`, `discovery`,
`reason` e `next_actions` têm o mesmo formato que em `PATCH
/v3/transactions/{transaction_id}/travel-rule/`, de modo que uma única
leitura de uma transação informa por que a transferência está travada e
o que a faz avançar.
properties:
uuid:
type: string
format: uuid
status:
type: string
protocol:
type: string
nullable: true
required:
type: boolean
obligations_count:
type: integer
originator_data:
type: object
description: >-
Parte remetente. Em uma transferência de entrada, os valores da
contraparte ficam mascarados até que a propriedade seja confirmada.
beneficiary_data:
type: object
description: >-
Parte beneficiária. Em uma transferência recebida, os valores da
contraparte ficam mascarados até que a propriedade seja confirmada.
name_match:
type: object
nullable: true
description: >-
A comparação de nomes que decidiu a transferência (pontuação e
rigor). Nula até que uma seja executada. Os nomes comparados são
mascarados junto com as partes.
data_match:
$ref: '#/components/schemas/TravelRuleDataMatch'
mismatched_fields:
type: array
items:
type: string
description: >-
Atalho para `data_match.mismatched_fields`. Vazio quando nada
difere.
data_unmasked:
$ref: '#/components/schemas/TravelRuleDataUnmasked'
data_masked:
type: boolean
description: >-
True enquanto os dados pessoais da contraparte estão mascarados
nesta resposta.
metadata:
type: object
direction:
type: string
enum:
- INBOUND
- OUTBOUND
description: De qual lado da troca está esta transferência.
rail:
type: string
nullable: true
description: >-
O canal pelo qual a transferência passou: `INTERNAL`, `TRP`, `GTR`,
`TRUST`, `VERIFYVASP`, `SYGNA` ou `EMAIL` (`TEST_VASP` em uma
aplicação de sandbox, quando o Didit Test VASP respondeu), ou `null`
até que um canal seja escolhido.
counterparty_vasp:
type: object
nullable: true
properties:
name:
type: string
lei:
type: string
dd_score:
type: integer
description: >-
Pontuação de due diligence de 0 a 100, em que valores maiores
são melhores. Mesma escala do diretório de VASPs.
dd_score_breakdown:
type: object
description: >-
Contribuições de cada componente para o dd_score, um objeto por
componente, como no diretório de VASPs (jurisdiction,
verification, protocol, lei, history, essentials,
responsiveness), cada um com {points, max, reason, detail}. {}
até que a contraparte tenha sido avaliada.
additionalProperties:
type: object
properties:
points:
type: number
description: Pontos atribuídos a este componente.
max:
type: integer
description: Pontuação máxima que este componente pode conceder.
reason:
type: string
description: Código legível por máquina do veredito do componente.
detail:
type: string
description: Motivo legível dos pontos atribuídos.
dd_assessed_at:
type: string
format: date-time
nullable: true
description: >-
Quando a avaliação de devida diligência foi executada pela
última vez. Nulo até que a contraparte tenha sido avaliada.
description: >-
A entrada da contraparte no diretório, ou `null` quando a
transferência não vincula nenhuma.
delivery:
nullable: true
allOf:
- $ref: '#/components/schemas/TravelRuleDelivery'
description: >-
A mensagem mais recente que a transferência deve a outra parte.
`null` quando não deveu nenhuma, por exemplo abaixo de
`threshold_amount` ou para uma carteira autocustodiada declarada.
discovery:
type: array
description: >-
Como a Didit procurou a contraparte, com uma entrada por etapa
executada. Vazio quando nenhuma descoberta foi executada, por
exemplo, em uma transferência de entrada.
items:
$ref: '#/components/schemas/TravelRuleDiscoveryStep'
reason:
type: string
description: >-
Motivo pelo qual uma transferência `COUNTERPARTY_VASP_NOT_FOUND` ou
`COUNTERPARTY_VASP_NOT_REACHABLE` está parada; `""` para qualquer
outro status. Uma falha de entrega decide primeiro, apenas em
`COUNTERPARTY_VASP_NOT_REACHABLE`: `email_undeliverable` (o provedor
de e-mail recusou o e-mail de conformidade e não resta nenhum
endereço para tentar: no envio, em um lembrete ou como uma devolução
permanente informada depois) ou `delivery_failed` (o canal que fazia
a entrega falhou definitivamente: um canal de rede recusou a
mensagem ou esgotou as novas tentativas, um host de identidade `TRP`
não respondeu ou o host `TRP` da contraparte não aceitou a
consulta). Caso contrário, o rastro de `discovery` decide:
`awaiting_end_user` (nenhuma etapa indicou uma contraparte que a
Didit consiga alcançar), `directory_match_no_route` (uma etapa
indicou um VASP do diretório que não tem rota),
`picked_member_without_proven_wallet` (o usuário final escolheu um
cliente da Didit que não comprovou o controle da carteira) ou
`no_directory_match` quando o rastro não indica nenhum outro motivo.
Um reenvio faz a transferência avançar, e o motivo é então limpo.
Veja [Por que uma transferência está
parada](/pt-br/transaction-monitoring/travel-rule#por-que-uma-transferência-fica-travada).
next_actions:
type: array
description: >-
O que faz a transferência avançar; `[]` para qualquer status que não
seja `COUNTERPARTY_VASP_NOT_FOUND` ou
`COUNTERPARTY_VASP_NOT_REACHABLE`. `email_undeliverable` oferece
`update_compliance_email` e depois `resend`. `delivery_failed`
oferece `resend`. Um motivo de descoberta oferece
`select_counterparty_vasp`, `declare_self_hosted`, `add_vasp_hint` e
`resend`.
items:
$ref: '#/components/schemas/TravelRuleNextAction'
chain_details:
$ref: '#/components/schemas/TravelRuleChainDetails'
TransactionVerificationSessionAction:
title: Verification session
type: object
properties:
type:
type: string
enum:
- verification_session
url:
type: string
format: uri
description: URL de verificação hospedada a ser aberta para o usuário final.
session_id:
type: string
format: uuid
description: ID da sessão de verificação.
session_token:
type: string
description: >-
Token da sessão, usado pelos SDKs móveis para iniciar o fluxo de
forma nativa.
status:
type: string
description: Status da sessão de verificação.
required:
- type
- url
TransactionWalletOwnershipAction:
title: Wallet ownership
type: object
properties:
type:
type: string
enum:
- wallet_ownership
url:
type: string
format: uri
description: >-
URL do widget hospedado de comprovação de propriedade da carteira.
Abra-a em um navegador real: no celular, use SFSafariViewController
ou uma Chrome Custom Tab, nunca um webview incorporado.
widget_session_id:
type: string
format: uuid
description: ID da sessão do widget de propriedade da carteira.
expires_at:
type: string
format: date-time
description: Quando a sessão do widget expira.
required:
- type
- url
TravelRuleDataMatch:
type: object
nullable: true
description: >-
Comparação campo a campo entre os dados das partes da transferência e o
que o outro lado sabe sobre o titular da carteira. Ela indica campos e
resultados, nunca valores, por isso continua legível enquanto os dados
da contraparte estão mascarados. Nulo até que uma comparação seja
executada.
properties:
matched:
type: boolean
description: True quando nenhum campo comparado é diferente.
mismatched_fields:
type: array
items:
type: string
enum:
- name
- date_of_birth
- address
- account
description: Os campos que diferem.
fields:
type: object
description: >-
Uma entrada por campo comparado para o tipo de entidade da parte
(`name`, `date_of_birth`, `address`, `account`; uma empresa não tem
`date_of_birth`).
additionalProperties:
type: object
properties:
result:
type: string
enum:
- matched
- mismatched
- not_compared
description: >-
`not_compared` quando a regra é `NONE` ou um dos lados não tem
valor para o campo.
strictness:
type: string
enum:
- NONE
- STRICT
- CONTAINS
- DEFAULT
- FUZZY
TravelRuleDataUnmasked:
type: object
nullable: true
description: >-
Registro de auditoria do momento em que os dados da contraparte foram
desmascarados. É nulo enquanto os dados ainda estão mascarados e em
transferências de saída.
properties:
at:
type: string
format: date-time
reason:
type: string
enum:
- ownership_confirmed
- wallet_proof
- address_book_match
- own_verified_wallet
- inquiry_approved
- known_payment_method
- travel_address
description: >-
O que confirmou a propriedade: ownership_confirmed (sua confirmação
pelo console ou pela API), wallet_proof (uma prova de carteira no
widget ou uma transferência de entrada INTERNAL, definida quando é
criada), address_book_match (uma carteira verificada do catálogo de
endereços), own_verified_wallet (a carteira verificada do próprio
usuário), inquiry_approved (sua aprovação de uma consulta TRP de
entrada ou de uma mensagem GTR ou Sygna), known_payment_method (uma
carteira com a qual seu usuário já pagou) ou travel_address (o
travel address por carteira identificou a carteira).
actor:
type: string
description: >-
Quem confirmou: o e-mail do usuário do console ou o rótulo da chave
de API. Em branco para uma decisão automática.
TravelRuleDelivery:
type: object
description: >-
Situação da mensagem mais recente que a transferência deve à outra
parte. A Didit contata a contraparte depois que a requisição que criou
ou alterou a transferência retorna, então este objeto indica se essa
mensagem foi entregue: na fila, em envio, aguardando nova tentativa após
um erro, entregue ou com falha. Uma falha da qual a rede ainda pode se
recuperar (sem resposta a tempo, falha de conexão, HTTP `408`, `429` ou
`5xx`) é tentada novamente após 30 segundos, 2 minutos, 10 minutos, 30
minutos e 1 hora. Quando uma primeira mensagem (`kind: SEND`) falha
definitivamente, porque a rede a recusou ou porque a sexta tentativa
também falhou, a transferência passa para
`COUNTERPARTY_VASP_NOT_REACHABLE` com `last_error` em sua `timeline`;
qualquer outra mensagem que falhe definitivamente é registrada na
`timeline`. O `status` da transferência continua sendo a fonte da
verdade sobre a troca em si.
required:
- kind
- status
- rail
- attempts
- last_error
- next_attempt_at
- delivered_at
properties:
kind:
type: string
enum:
- SEND
- ANSWER
- TXID
- CANCEL
- POLL
description: >-
O que a mensagem transporta. `SEND`: a primeira mensagem da
transferência para a contraparte (de saída; o canal é escolhido no
momento do envio). `ANSWER`: sua aceitação ou recusa, devida à rede
que fez a solicitação (de entrada). `TXID`: o hash da transação
on-chain, depois que você conclui a transferência. `CANCEL`: o
cancelamento, depois que você cancela a transferência. `POLL`: uma
consulta de status a uma rede que oferece esse recurso, repetida a
cada 5 minutos enquanto a transferência aguarda a contraparte.
status:
type: string
enum:
- QUEUED
- SENDING
- RETRYING
- DELIVERED
- FAILED
description: >-
`QUEUED`: aguardando envio. `SENDING`: uma tentativa está em
andamento. `RETRYING`: uma tentativa falhou e a próxima será
executada em `next_attempt_at`. `DELIVERED`: o outro lado recebeu a
mensagem. `FAILED`: o outro lado a recusou, ou a última tentativa
falhou.
rail:
type: string
enum:
- INTERNAL
- TRP
- GTR
- TRUST
- VERIFYVASP
- SYGNA
- EMAIL
- ''
description: >-
O canal que transporta a mensagem. Fica vazio até que a Didit
escolha um para uma primeira mensagem.
attempts:
type: integer
minimum: 0
description: >-
Tentativas feitas até agora para esta mensagem. Uma mensagem que não
seja uma consulta de status é tentada no máximo 6 vezes.
last_error:
type: string
description: >-
O tipo de falha que a última tentativa encontrou, `""` quando não
houve nenhuma: por exemplo `email undeliverable`, `trp identity
endpoint unreachable` ou `trp transfer inquiry delivery failed`.
Nunca inclui a resposta da própria contraparte, que fica na
`timeline` da transferência.
Quando o GTR responde com um erro, o código de status e a mensagem
dele são incluídos. Os corpos de resposta nunca são incluídos.
example: email undeliverable
next_attempt_at:
type: string
format: date-time
nullable: true
description: >-
Quando a próxima tentativa é executada enquanto a mensagem está
`QUEUED` ou `RETRYING`.
delivered_at:
type: string
format: date-time
nullable: true
description: Quando o outro lado recebeu a mensagem.
TravelRuleDiscoveryStep:
type: object
description: >-
Uma etapa da descoberta de contraparte que a Didit executou para uma
transferência de saída, na ordem em que as executou. A primeira etapa
que identifica um VASP com rota encerra a cadeia.
properties:
step:
type: string
enum:
- internal_address_book
- wallet_attribution
- network_lookup
- customer_hint
- end_user
description: >-
`internal_address_book`: outro cliente da Didit que comprovou o
controle da carteira de destino. `wallet_attribution`: a atribuição
da carteira feita por análise de blockchain. `network_lookup`: uma
rede capaz de informar qual VASP detém o endereço. `customer_hint`:
o nome do VASP, o LEI ou a jurisdição que você enviou em
`beneficiary_data`. `end_user`: a contraparte que o usuário final
(ou você) escolheu, ou o pedido para escolher uma.
outcome:
type: string
enum:
- match
- miss
- skipped
description: >-
`match`: a etapa identificou uma contraparte. `miss`: ela foi
executada e não encontrou nenhuma. `skipped`: ela não pôde ser
executada, e `reason` informa o motivo.
reason:
type: string
description: >-
Motivo legível por máquina, `""` quando há correspondência:
`no_proven_internal_wallet`, `attribution_disabled`,
`already_attributed`, `no_attributed_entity`,
`directory_match_no_route`, `gtr_address_lookup_runs_on_dispatch`,
`no_membership`, `network_switched_off`,
`no_network_address_lookup`, `no_directory_match`,
`awaiting_end_user` ou `picked_member_without_proven_wallet`.
vasp:
type: string
format: uuid
nullable: true
description: O VASP do diretório indicado pela etapa, quando ela indicou um.
rail:
type: string
nullable: true
description: O canal que alcança essa contraparte, quando a etapa encontrou um.
at:
type: string
format: date-time
TravelRuleNextAction:
type: object
description: >-
Algo que faz avançar uma transferência `COUNTERPARTY_VASP_NOT_FOUND` ou
`COUNTERPARTY_VASP_NOT_REACHABLE`. Consulte [Por que uma transferência
está
parada](/pt-br/transaction-monitoring/travel-rule#por-que-uma-transferência-fica-travada).
properties:
action:
type: string
enum:
- select_counterparty_vasp
- declare_self_hosted
- add_vasp_hint
- update_compliance_email
- resend
description: >-
`select_counterparty_vasp`: o usuário final escolhe o VASP de
destino no widget de propriedade da carteira, ou você faz um PATCH
com `action=beneficiary_vasp`. `declare_self_hosted`: o usuário
final declara no widget que a carteira é autocustodiada.
`add_vasp_hint`: informe à Didit quem é a contraparte, com um nome
de VASP, um LEI ou um travel address (por exemplo, um
`travel_address` na entrada do catálogo de endereços da carteira de
destino) e depois reenvie. `update_compliance_email` e `resend` são
valores de `action` de `PATCH
/v3/transactions/{transaction_id}/travel-rule/`: informe novamente o
e-mail de conformidade da contraparte e execute o roteamento outra
vez.
url:
type: string
format: uri
description: >-
O link do widget de propriedade da carteira, em
`select_counterparty_vasp` e `declare_self_hosted`, enquanto a
transferência tiver uma sessão de widget aberta.
required:
- action
TravelRuleChainDetails:
type: object
description: >-
Como a blockchain da transferência identifica suas duas carteiras,
quando isso vai além de um endereço pagando a outro. Vazio (`{}`) para
uma transferência em blockchain baseada em contas (EVM, Solana, Tron),
em que os dois endereços são as próprias carteiras. A correspondência, o
roteamento e o catálogo de endereços leem as carteiras primeiro a partir
daqui.
properties:
chain:
type: string
description: >-
Blockchain canônica, por exemplo, `BTC`, `XRP` ou `LIGHTNING` para
uma transferência Lightning.
shape:
type: string
enum:
- utxo
- memo
- lightning
originator:
$ref: '#/components/schemas/TravelRuleChainSide'
beneficiary:
$ref: '#/components/schemas/TravelRuleChainSide'
utxo:
type: object
description: >-
Em uma transferência UTXO: as entradas e saídas conforme armazenadas
(valores como strings decimais) e como a Didit interpretou cada
saída.
properties:
inputs:
type: array
items:
$ref: '#/components/schemas/TravelRuleUtxoEntry'
outputs:
type: array
items:
$ref: '#/components/schemas/TravelRuleUtxoEntry'
change_output_indexes:
type: array
items:
type: integer
description: Saídas que pagam de volta a um endereço de entrada.
beneficiary_output_index:
type: integer
nullable: true
description: >-
A saída que paga o beneficiário; null quando nenhuma pôde ser
distinguida.
lightning:
type: object
description: >-
Em uma transferência Lightning: o que a requisição de pagamento
informa. Sempre `kind` (`bolt11`, `bolt12_offer`, `bolt12_invoice`,
`bolt12_invoice_request`, `lnurl`, `lightning_address`, `node_id` ou
`unknown`); uma fatura BOLT11 acrescenta `network`, `payee_node_id`,
`payment_hash`, `amount_msat`, `created_at` e `expires_at`; uma
string BOLT12, `blinded_paths` e `payee_node_id`; uma LNURL ou um
Lightning Address, o respectivo `domain`. Nada é resolvido pela
rede: a requisição é apenas decodificada.
additionalProperties: true
warnings:
type: array
items:
type: string
enum:
- declared_originator_not_an_input
- declared_beneficiary_not_an_output
- beneficiary_output_ambiguous
- beneficiary_output_amount_differs
description: >-
Inconsistências de UTXO que merecem atenção: o remetente declarado
não é uma entrada, o beneficiário declarado não é uma saída, não foi
possível distinguir uma única saída do beneficiário, ou a saída do
beneficiário paga um valor diferente do informado na transação.
not_applicable_reason:
type: string
enum:
- LIGHTNING_NO_PAYEE_IDENTIFIER
- LIGHTNING_BOLT12_BLINDED_PAYEE
- LIGHTNING_LNURL_NAMES_NO_PAYEE
description: >-
Em uma transferência Lightning de saída cuja requisição de pagamento
não indica nenhum beneficiário: o motivo pelo qual a transferência é
`NOT_APPLICABLE`. `LIGHTNING_NO_PAYEE_IDENTIFIER` (a requisição não
indica nenhum nó beneficiário ou não pôde ser decodificada),
`LIGHTNING_BOLT12_BLINDED_PAYEE` (a oferta oculta o beneficiário
atrás de blinded paths), `LIGHTNING_LNURL_NAMES_NO_PAYEE` (uma LNURL
indica um serviço, não um beneficiário). O mesmo código abre a
última entrada de `timeline` da transferência.
TravelRuleChainSide:
type: object
description: >-
A carteira de uma das partes, conforme a Didit a resolveu a partir dos
dados da blockchain.
properties:
address:
type: string
description: >-
A carteira. Em uma rede com memo, o endereço clássico (um X-address
da XRP é dividido em endereço clássico e tag); na Lightning, o ID do
nó do beneficiário ou o Lightning Address.
memo:
type: string
description: >-
A destination tag ou o memo que faz parte da carteira; `""` para
nenhum.
source:
type: string
enum:
- declared
- x_address
- largest_input
- only_non_change_output
- amount_match
- invoice_payee
- updated
description: >-
Origem da carteira: `declared` (sua requisição), `x_address`
(extraída de um X-address do XRP), `largest_input` (o endereço de
entrada UTXO que mais contribuiu), `only_non_change_output` (a única
saída UTXO que não é troco), `amount_match` (a única saída UTXO que
paga o valor da transferência), `invoice_payee` (o beneficiário
indicado em uma solicitação de pagamento Lightning), `updated`
(definida posteriormente com `action: update_originator_wallet`).
TravelRuleUtxoEntry:
type: object
description: >-
Uma entrada ou saída de uma transação UTXO, conforme registrada na
blockchain.
required:
- address
properties:
address:
type: string
maxLength: 128
amount:
type: string
nullable: true
description: >-
String decimal na própria unidade da moeda (BTC, não satoshis).
Opcional.
example: '0.0125'
txid:
type: string
maxLength: 128
description: Opcional. A transação que uma entrada gasta.
vout:
type: integer
nullable: true
minimum: 0
description: Opcional. O índice da saída que uma entrada gasta.
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.