> ## 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 Travel Rule: concluir, reenviar, atualizar
> Conclua uma transferência Travel Rule com o hash on-chain, cancele-a ou reenvie-a, ou registe a carteira de onde os fundos saíram com a Didit.
Prompt da API de ações de transferência da Travel Rule
Copiar o prompt para a área de transferência
\
\`Act on an existing Travel Rule transfer: report the on-chain hash to finish it, cancel it, re-run counterparty routing, replace a refused compliance email, or record the wallet the funds left from.
Endpoint:
PATCH https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/
Authentication:
Use the x-api-key header with my Didit API key. {transaction_id} is the Didit transaction uuid.
Four mutually exclusive bodies:
1\. Finish (close out after broadcasting on-chain):
\{"payment_txn_id": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060"}
\- Requires an OUTBOUND transfer in COMPLETED status - otherwise 409.
\- Moves the transfer (and its INTERNAL-rail counterpart, if any) to FINISHED and stores the hash on the transaction.
\- Over GTR, VerifyVASP or Sygna Bridge, the network learns the hash after the response, with retries (see delivery below).
\- On the TRP rail, Didit also posts the hash to the counterparty's confirmation callback.
2\. Cancel:
\{"action": "cancel"}
\- Allowed from any non-terminal status; moves the transfer (and its INTERNAL-rail counterpart, if any) to CANCELLED.
\- From a terminal status (FINISHED, CANCELLED, EXPIRED) it returns 409.
\- On an outbound TRP transfer, Didit also sends a cancellation to the counterparty.
\- Over GTR, VerifyVASP or Sygna Bridge, the network is told after the response, with retries.
3\. Resend (re-run the routing ladder):
\{"action": "resend"}
\- Allowed only on an OUTBOUND transfer in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE, or NOT_ENOUGH_COUNTERPARTY_DATA - otherwise 409.
\- Resets the deadline and re-runs routing; a transfer whose destination wallet was declared unhosted moves to UNCONFIRMED_OWNERSHIP.
\- First give Didit a route, for example by registering the destination wallet in your address book (same chain as the transfer, or a blank chain) with the counterparty's travel_address (TRP carries BTC, ETH, and USDC on a named network), or by adding a compliance contact for the counterparty's directory entry with POST /v3/travel-rule/counterparty-contacts/, then resend.
\- Resend reuses the transfer's beneficiary_data, which you cannot change after creation except for the compliance email (body 4), so submit a new transaction to send different beneficiary data.
\- A previously recorded blockchain-analytics attribution is reused - no new lookup, no new charge.
\- Discovery runs again from the first step (internal address book, wallet attribution, network lookup, your VASP hint, then the end user); the transfer's "discovery" list shows what each step found.
\- Queued, not run inside the request: the response shows the transfer back in AWAITING_COUNTERPARTY with a "resend queued" timeline entry, and the outcome arrives as a travel_rule.status.updated webhook. A resend sent while an earlier attempt is still running is sent once that attempt settles.
\- If routing still resolves nothing, the transfer lands back in COUNTERPARTY_VASP_NOT_FOUND.
4\. Update the compliance email (the fix for reason email_undeliverable):
\{"action": "update_compliance_email", "compliance_email": "desk@bene-casp.example"}
\- Allowed only on an OUTBOUND transfer in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE, or NOT_ENOUGH_COUNTERPARTY_DATA - otherwise 409.
\- A missing or malformed compliance_email returns 400.
\- Stores the address as this transfer's beneficiary_data.counterparty_vasp_email; it belongs to this transfer only and joins no directory entry or contact list.
\- The status does not change and the timeline gains "compliance email updated". The transfer keeps reason email_undeliverable until you send {"action": "resend"}, which sends the request to the new address.
4\. Update the originator wallet (the wallet the funds actually left from):
\{"action": "update_originator_wallet", "wallet_address": "bc1q...", "memo": ""}
\- Outbound transfers only (an inbound transfer -> 409), and never a CANCELLED or EXPIRED one (-> 409).
\- Use it when a withdrawal is broadcast from another address than the one declared, typically a UTXO withdrawal spending whichever addresses held the coins. When the transfer's UTXO inputs are known, wallet_address must be one of them (-> 400 otherwise).
\- Changes the record only: nothing is sent to the counterparty again and the status stays. chain_details.originator becomes the new wallet with source "updated", the timeline records the previous and the new wallet, and the INTERNAL-rail counterpart is updated the same way.
5\. Name the counterparty (when discovery could not):
\{"action": "beneficiary_vasp", "beneficiary_vasp": ""}
\- The id comes from GET /v3/travel-rule/vasps/.
\- Allowed only for an outbound transfer in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE, or NOT_ENOUGH_COUNTERPARTY_DATA - otherwise 409.
\- Routes the transfer to that VASP and sends it again; automatic discovery never overrides your choice.
\- 400 if beneficiary_vasp is missing or not a valid id, 404 if no directory entry has that id.
What to read from the response:
\- The full transfer object: status, rail, direction, ownership_confirmed, deadline_at, timeline, counterparty_vasp, delivery, discovery, reason, next_actions.
\- delivery: the latest message the transfer owes the other side - kind (SEND, ANSWER, TXID, CANCEL, POLL), status (QUEUED, SENDING, RETRYING, DELIVERED, FAILED), rail, attempts, last_error, next_attempt_at, delivered_at. Failures a network may recover from are retried after 30 s, 2, 10, 30 and 60 minutes; when a first message fails for good the transfer moves to COUNTERPARTY_VASP_NOT_REACHABLE. null when the transfer never owed a message.
\- reason and next_actions say why a COUNTERPARTY_VASP_NOT_FOUND or COUNTERPARTY_VASP_NOT_REACHABLE transfer is stuck and what moves it on: email_undeliverable offers update_compliance_email then resend, delivery_failed offers resend, and a discovery reason offers select_counterparty_vasp, declare_self_hosted, add_vasp_hint and resend. Both are empty for any other status, so they clear once a resend moves the transfer on.
Order of operations for outbound transfers:
submit transaction -> wait for travel_rule.status == "COMPLETED" -> broadcast on-chain -> PATCH with payment_txn_id -> FINISHED.
Never broadcast before COMPLETED.
A transfer sent over TRUST cannot reach COMPLETED, because TRUST sends back nothing Didit can read; it stays AWAITING_COUNTERPARTY until it expires. Over GTR, VerifyVASP and Sygna Bridge, Didit reads the counterparty's answer from the network.
If the message cannot be delivered, the transfer moves to COUNTERPARTY_VASP_NOT_REACHABLE instead.
Failure modes:
\- 400 - the body has none of payment_txn_id or a supported action, update_compliance_email has a missing or malformed compliance_email, or a wallet_address or memo the transfer's chain cannot carry.
\- 409 - action not allowed from the transfer's current status or direction (see the per-action rules above).
\- 400 - action=beneficiary_vasp without a valid beneficiary_vasp.
\- 404 - unknown transaction, no Travel Rule transfer attached, or (action=beneficiary_vasp) no directory entry has that id.
Full guide: /transaction-monitoring/travel-rule#sending-a-transfer and /transaction-monitoring/travel-rule#why-a-transfer-is-stuck.`
\
Colar em
## OpenAPI
````yaml pt/openapi-25.json PATCH /v3/transactions/{transaction_id}/travel-rule/
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}/travel-rule/:
patch:
tags:
- Travel Rule
summary: >-
Concluir, cancelar, reenviar ou atualizar a carteira do ordenante de uma
transferência da Travel Rule
description: >-
Forneça `payment_txn_id` para comunicar o hash on-chain e mover uma
transferência de saída COMPLETED para FINISHED (a sua contraparte no
canal INTERNAL também passa para FINISHED), `{"action": "cancel"}` para
cancelar uma transferência não terminal, ou `{"action": "resend"}` para
reencaminhar uma transferência de saída bloqueada em
COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou
NOT_ENOUGH_COUNTERPARTY_DATA (melhore primeiro os dados da contraparte,
por exemplo adicionando um travel_address à entrada da carteira de
destino). O resend aplica-se apenas a transferências de saída.
`{"action": "update_compliance_email", "compliance_email":
"desk@example.com"}` substitui o e-mail de conformidade de uma
transferência de saída num desses três estados, a correção para `reason:
email_undeliverable`: o estado não se altera e o próximo `resend` envia
o pedido para esse endereço. Um reenvio é colocado em fila, não
executado dentro do pedido: a resposta mostra a transferência novamente
em AWAITING_COUNTERPARTY com uma entrada na cronologia `resend queued` e
uma `delivery` em fila, e o respetivo destino é recebido através de um
webhook `travel_rule.status.updated`. Quando a transferência tiver sido
realizada através do GTR, VerifyVASP ou Sygna Bridge, a rede toma
conhecimento do hash on-chain ou do cancelamento após a resposta, com
novas tentativas; `delivery` mostra o estado dessa mensagem. `{"action":
"update_originator_wallet", "wallet_address": "..."}` regista a carteira
da qual os fundos realmente saíram numa transferência de saída, por
exemplo o endereço a partir do qual um levantamento de UTXO foi emitido
em vez da carteira principal que declarou. Altera apenas o registo: nada
é enviado novamente para a contraparte e o estado mantém-se. O ordenante
passa a ser `chain_details.originator` com `source: updated`, a
alteração é adicionada à `timeline` com a carteira anterior e a nova, e
a contraparte no canal INTERNAL da transferência é atualizada da mesma
forma. `{"action": "beneficiary_vasp", "beneficiary_vasp": ""}` indique pessoalmente a contraparte quando a deteção
automática não foi possível, numa transferência de saída em
COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou
NOT_ENOUGH_COUNTERPARTY_DATA: a transferência é encaminhada para esse
VASP e enviada novamente.
operationId: patchTravelRuleTransfer
parameters:
- name: transaction_id
in: path
required: true
description: UUID de transação estável da Didit proprietário da transferência.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TravelRuleTransferPatchRequest'
examples:
Finish:
value:
payment_txn_id: 0xchainhash
Cancel:
value:
action: cancel
Resend:
value:
action: resend
Update compliance email:
value:
action: update_compliance_email
compliance_email: desk@example.com
Update originator wallet:
value:
action: update_originator_wallet
wallet_address: bc1qOriginatorInputAddress01
Name the counterparty:
value:
action: beneficiary_vasp
beneficiary_vasp: 9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607
responses:
'200':
description: >-
A transferência atualizada. Após `update_compliance_email`, o
respetivo estado permanece inalterado e mantém `reason:
email_undeliverable` até ao próximo `resend`.
content:
application/json:
schema:
$ref: '#/components/schemas/TravelRuleTransferDetail'
'400':
description: >-
Nem payment_txn_id nem uma ação suportada foram fornecidos,
`compliance_email` está em falta ou não é um endereço de e-mail em
`update_compliance_email`, ou, para `update_originator_wallet`,
nenhum wallet_address, uma carteira ou memo que a blockchain da
transferência não consiga suportar, ou uma carteira que não seja uma
das entradas UTXO da transferência, ou `beneficiary_vasp` está em
falta ou não é um ID de VASP válido no diretório.
content:
application/json:
examples:
No action:
value:
detail:
- >-
Provide payment_txn_id, action=cancel, action=resend,
action=beneficiary_vasp, action=update_originator_wallet
or action=update_compliance_email.
Invalid compliance email:
value:
compliance_email:
- Enter a valid email address.
'404':
description: >-
Transação desconhecida, a transação não tem nenhuma transferência
Travel Rule, ou (ação `beneficiary_vasp`) nenhuma entrada do
diretório tem esse id.
'409':
description: >-
A transferência não está num estado que permita esta operação (por
exemplo, não está em COMPLETED/outbound para finalizar, já se
encontra num estado terminal para cancelar ou não é uma
transferência de saída num estado reenviável para reenviar).
`update_compliance_email` responde com `409` para uma transferência
de entrada e para uma transferência de saída fora de
COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE e
NOT_ENOUGH_COUNTERPARTY_DATA. `update_originator_wallet` responde
com `409` para uma transferência de entrada, cancelada ou expirada.
`beneficiary_vasp` responde com `409`, a menos que a transferência
seja de saída e esteja em COUNTERPARTY_VASP_NOT_FOUND,
COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA.
content:
application/json:
examples:
Cancel from a terminal status:
value:
detail: Transfer is already in a terminal state.
Resend not allowed:
value:
detail: Transfer cannot be resent from its current state.
Finish not allowed:
value:
detail: >-
Transfer must be an outbound transfer in COMPLETED status
to finish.
Compliance email cannot change:
value:
detail: >-
The compliance email of this transfer cannot change from
its current state.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X PATCH
https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/
\
-H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"payment_txn_id": "0xchainhash"}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.transactions.travel_rule.update_transfer(
"11111111-2222-3333-4444-555555555555",
payment_txn_id="0xchainhash",
)
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.travelRule.updateTransfer("11111111-2222-3333-4444-555555555555",
{
payment_txn_id: "0xchainhash",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.UpdateTransfer(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleTransferPatchRequest{\n\tPaymentTxnID: didit.String(\"0xchainhash\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.TravelRuleTransferPatchRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.transactions().travelRule().updateTransfer("11111111-2222-3333-4444-555555555555",
TravelRuleTransferPatchRequest.builder()
.paymentTxnId("0xchainhash")
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
transactions->travelRule->updateTransfer('11111111-2222-3333-4444-555555555555',
[
'payment_txn_id' => '0xchainhash',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.transactions.travel_rule.update_transfer(
"11111111-2222-3333-4444-555555555555",
payment_txn_id: "0xchainhash"
)
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.TravelRule.UpdateTransferAsync("11111111-2222-3333-4444-555555555555",
new TravelRuleTransferPatchRequest
{
PaymentTxnId = "0xchainhash",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
TravelRuleTransferPatchRequest:
type: object
description: >-
Forneça exatamente um de: payment_txn_id (finish), action=cancel,
action=resend, action=update_compliance_email com compliance_email,
action=update_originator_wallet com wallet_address ou
action=beneficiary_vasp com beneficiary_vasp.
properties:
payment_txn_id:
type: string
description: >-
O hash da transação on-chain. Exige que a transferência seja uma
transferência de saída no estado COMPLETED.
action:
type: string
enum:
- cancel
- resend
- update_compliance_email
- update_originator_wallet
- beneficiary_vasp
description: >-
"cancel" cancela uma transferência não terminal. "resend" executa
novamente o encaminhamento de uma transferência enviada retida em
COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou
NOT_ENOUGH_COUNTERPARTY_DATA. "update_compliance_email" substitui o
e-mail de conformidade para o qual o pedido é enviado, numa
transferência enviada num desses três estados; envie "resend" em
seguida. "update_originator_wallet" regista a carteira de onde os
fundos saíram efetivamente (`wallet_address`, `memo`).
"beneficiary_vasp" indica manualmente o VASP da contraparte (requer
`beneficiary_vasp`) para uma transferência enviada num desses
estados: é encaminhada para esse VASP e enviada novamente.
compliance_email:
type: string
format: email
maxLength: 254
description: >-
Obrigatório com `action: update_compliance_email`. Mantido como
`beneficiary_data.counterparty_vasp_email` desta transferência:
pertence apenas a esta transferência e não é associado a nenhuma
entrada do diretório nem a nenhuma lista de contactos.
wallet_address:
type: string
maxLength: 128
description: >-
Com `action: update_originator_wallet`: a carteira de onde os fundos
saíram. Quando as entradas UTXO da transferência são conhecidas, tem
de ser uma delas.
memo:
type: string
maxLength: 256
description: >-
Com `action: update_originator_wallet`: o memo ou etiqueta da
carteira numa rede com memo. Opcional.
beneficiary_vasp:
type: string
format: uuid
description: >-
Obrigatório com action=beneficiary_vasp: o `id` de um VASP do
diretório, de `GET /v3/travel-rule/vasps/`. A sua escolha tem
prioridade sobre qualquer passo de deteção automática, que nunca a
substitui.
TravelRuleTransferDetail:
type: object
description: >-
Objeto completo de transferência devolvido pelos endpoints de
confirmação de propriedade e de finalização/cancelamento. Enquanto a
propriedade da carteira de uma transferência recebida não estiver
confirmada, os campos `originator_data` e `beneficiary_data` da
contraparte são devolvidos mascarados (a primeira letra de cada palavra
é mantida; a carteira, a blockchain e o encaminhamento do VASP
permanecem legíveis) e `data_masked` é true.
properties:
uuid:
type: string
format: uuid
status:
type: string
enum:
- AWAITING_COUNTERPARTY
- ON_HOLD
- COMPLETED
- FINISHED
- CANCELLED
- EXPIRED
- COUNTERPARTY_MISMATCHED_DATA
- COUNTERPARTY_VASP_NOT_FOUND
- COUNTERPARTY_VASP_NOT_REACHABLE
- UNCONFIRMED_OWNERSHIP
- COUNTERPARTY_VASP_GENERAL_DECLINE
- NOT_ENOUGH_COUNTERPARTY_DATA
- NOT_APPLICABLE
direction:
type: string
enum:
- INBOUND
- OUTBOUND
rail:
type: string
nullable: true
enum:
- INTERNAL
- TRP
- GTR
- TRUST
- VERIFYVASP
- SYGNA
- EMAIL
- TEST_VASP
- null
description: >-
O canal através do qual a transferência foi encaminhada, ou null
quando nenhum canal foi selecionado (por exemplo, abaixo do limiar,
uma carteira de contraparte autocustodiada, um registo pós-depósito,
ou nenhuma contraparte alcançável). INTERNAL significa que ambos os
lados são aplicações da Didit; EMAIL significa que a contraparte foi
alcançada através de uma ligação de recolha enviada por e-mail.
TEST_VASP significa que o Didit Test VASP respondeu à transferência
em sandbox. Através de GTR, VERIFYVASP e SYGNA, a Didit lê a
resposta da contraparte a partir da resposta da rede ou
consultando-a a cada 5 minutos. TRUST apenas envia, pelo que uma
transferência TRUST permanece AWAITING_COUNTERPARTY até expirar. Um
canal de rede só é utilizado quando tiver associado a sua própria
adesão a essa rede. É escolhido após o retorno da criação da
transação, pelo que é null nessa resposta.
protocol:
type: string
nullable: true
ivms_version:
type: string
example: ivms101.2023
required:
type: boolean
ownership_confirmed:
type: boolean
nullable: true
deadline_at:
type: string
format: date-time
nullable: true
timeline:
type: array
items:
type: object
properties:
status:
type: string
at:
type: string
format: date-time
detail:
type: string
name_match:
allOf:
- $ref: '#/components/schemas/TravelRuleNameMatch'
nullable: true
description: >-
A comparação de nomes decidida por esta entrada, junto a
`detail`. Ausente em entradas que não compararam qualquer
nome.
reason:
type: string
description: >-
Presente apenas na entrada de uma transição causada por uma
entrega com falha: `email_undeliverable` ou `delivery_failed`,
o valor que `reason` da transferência reporta.
counterparty_vasp:
type: object
nullable: true
properties:
name:
type: string
lei:
type: string
dd_score:
type: integer
description: >-
Pontuação de diligência devida de 0 a 100, onde quanto mais
alto, melhor. Mesma escala que no diretório VASP.
dd_score_breakdown:
type: object
description: >-
Contribuições por componente para dd_score, um objeto por
componente como no diretório VASP (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: Pontos máximos que este componente pode atribuir.
reason:
type: string
description: Código legível por máquina do veredito do componente.
detail:
type: string
description: Motivo legível por humanos para os pontos atribuídos.
dd_assessed_at:
type: string
format: date-time
nullable: true
description: >-
Quando a avaliação de diligência devida foi executada pela
última vez. Nulo até que a contraparte tenha sido avaliada.
originator_data:
type: object
description: >-
Parte ordenante. Para uma transferência de entrada, os valores da
contraparte são ocultados até que a propriedade seja confirmada.
beneficiary_data:
type: object
description: >-
Parte beneficiária. Para uma transferência de entrada, os valores da
contraparte são ocultados até que a propriedade seja confirmada.
name_match:
allOf:
- $ref: '#/components/schemas/TravelRuleNameMatch'
nullable: true
description: >-
A comparação de nomes que decidiu a transferência, ou nulo até que
uma seja executada. Enquanto as partes estiverem mascaradas, e na
cópia do outro cliente de uma troca INTERNAL, `transfer_name`,
`compared_name`, `matched_names` e `mismatched_names` são ocultados.
`score` e `matched` podem divergir: `matched` segue o rigor, `score`
é a semelhança dos dois nomes completos.
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: >-
Verdadeiro enquanto os dados pessoais da contraparte estiverem
mascarados nesta resposta.
created_at:
type: string
format: date-time
delivery:
nullable: true
allOf:
- $ref: '#/components/schemas/TravelRuleDelivery'
description: >-
O estado em que se encontra a mensagem mais recente que esta
transferência deve à outra parte. Nulo quando a transferência nunca
deveu nenhuma (por exemplo, abaixo de `threshold_amount`, uma
carteira autocustodiada declarada ou um registo sunrise).
discovery:
type: array
description: >-
Como a Didit procurou a contraparte, uma entrada por passo
executado. Vazio quando não foi executada qualquer deteção, por
exemplo, numa transferência recebida.
items:
$ref: '#/components/schemas/TravelRuleDiscoveryStep'
reason:
type: string
description: >-
O motivo pelo qual uma transferência `COUNTERPARTY_VASP_NOT_FOUND`
ou `COUNTERPARTY_VASP_NOT_REACHABLE` está bloqueada; `""` para
qualquer outro estado. Uma falha na entrega determina-o primeiro,
apenas em `COUNTERPARTY_VASP_NOT_REACHABLE`: `email_undeliverable`
(o fornecedor de e-mail recusou o e-mail de conformidade e não resta
nenhum endereço para tentar: quando foi enviado, num lembrete ou
como uma devolução permanente comunicada posteriormente) ou
`delivery_failed` (o canal que estava a efetuar a entrega falhou
definitivamente: um canal de rede recusou a mensagem ou esgotou as
tentativas, um host de identidade `TRP` não respondeu, ou o host
`TRP` da contraparte não aceitou a consulta). Caso contrário, o
rastreio de `discovery` determina-o: `awaiting_end_user` (nenhum
passo identificou uma contraparte que a Didit consiga contactar),
`directory_match_no_route` (um passo identificou um VASP de
diretório que não tem rota), `picked_member_without_proven_wallet`
(o utilizador final escolheu um cliente Didit que não comprovou o
controlo da carteira), ou `no_directory_match` quando o rastreio não
fornece outro motivo. Um novo envio faz avançar a transferência,
pelo que o motivo é limpo. Consulte [Por que motivo uma
transferência está
bloqueada](/pt/transaction-monitoring/travel-rule#por-que-motivo-uma-transferência-está-bloqueada).
next_actions:
type: array
description: >-
O que faz a transferência avançar; `[]` para qualquer estado exceto
`COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE`.
`email_undeliverable` disponibiliza `update_compliance_email` e, em
seguida, `resend`. `delivery_failed` disponibiliza `resend`. Um
motivo de descoberta disponibiliza `select_counterparty_vasp`,
`declare_self_hosted`, `add_vasp_hint` e `resend`.
items:
$ref: '#/components/schemas/TravelRuleNextAction'
chain_details:
$ref: '#/components/schemas/TravelRuleChainDetails'
TravelRuleNameMatch:
type: object
nullable: true
description: >-
A comparação de nomes que decidiu a transferência, ou nulo até que uma
seja executada. Enquanto as partes estiverem mascaradas, e na cópia do
outro cliente de uma troca INTERNAL, `transfer_name`, `compared_name`,
`matched_names` e `mismatched_names` são ocultados. `score` e `matched`
podem divergir: `matched` segue o rigor, `score` é a semelhança dos dois
nomes completos.
properties:
score:
type: integer
minimum: 0
maximum: 100
description: >-
Semelhança dos dois nomes completos, de 0 a 100. 0 quando qualquer
um dos nomes estiver em branco.
matched:
type: boolean
description: >-
Se os nomes cumprem `strictness`. O resultado da transferência segue
`data_match`, que compara todos os campos, pelo que uma
transferência pode ser COUNTERPARTY_MISMATCHED_DATA enquanto isto
for verdadeiro.
method:
type: string
enum:
- none
- exact_token
- token_subset
- token_containment
- sequence_ratio
description: >-
Como `matched` foi decidido: nenhum (`NONE`), token exato
(`STRICT`), subconjunto de tokens (`DEFAULT`), contenção de tokens
(`CONTAINS`) ou proporção de sequência (`FUZZY`).
strictness:
type: string
enum:
- NONE
- STRICT
- CONTAINS
- DEFAULT
- FUZZY
compared_with:
type: string
enum:
- wallet_holder
- counterparty_vasp
description: >-
wallet_holder: o titular registado para a carteira.
counterparty_vasp: o nome que a contraparte indicou na página de
resposta por e-mail, ou a resposta do Didit Test VASP na sandbox.
transfer_name:
type: string
description: O nome na transferência.
compared_name:
type: string
description: O nome com o qual foi comparado.
matched_names:
type: array
items:
type: string
description: Palavras de `transfer_name` encontradas em `compared_name`.
mismatched_names:
type: array
items:
type: string
description: >-
Palavras de `transfer_name` em falta em `compared_name`, seguidas de
palavras de `compared_name` em falta em `transfer_name`.
TravelRuleDataMatch:
type: object
nullable: true
description: >-
Comparação campo a campo dos dados das partes da transferência com o que
a outra parte sabe sobre o titular da carteira. Indica campos e
resultados, nunca valores, para que permaneça legível enquanto os dados
da contraparte estiverem mascarados. Null até que uma comparação tenha
sido executada.
properties:
matched:
type: boolean
description: True quando nenhum campo comparado difere.
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: >-
Registo de auditoria do momento em que os dados da contraparte foram
desmascarados. Nulo enquanto os dados ainda estiverem mascarados e para
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 (a sua
confirmação através da consola ou da 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 livro de endereços), own_verified_wallet (a carteira
própria verificada do seu utilizador), inquiry_approved (a sua
aprovação de um pedido TRP de entrada ou de uma mensagem GTR ou
Sygna), known_payment_method (uma carteira com a qual o seu
utilizador já pagou) ou travel_address (o Travel Address por
carteira que nomeou a carteira).
actor:
type: string
description: >-
Quem o confirmou: o e-mail do utilizador da consola ou a etiqueta da
chave de API. Em branco para uma decisão automática.
TravelRuleDelivery:
type: object
description: >-
O estado em que se encontra a mensagem mais recente que a transferência
deve à outra parte. A Didit contacta a contraparte após o pedido que
criou ou alterou a transferência ter retornado, pelo que este objeto
indica se essa mensagem chegou ao destino: em fila, a ser enviada, a
aguardar nova tentativa após um erro, entregue ou com falha. Uma falha
da qual a rede ainda possa recuperar (sem resposta a tempo, ligação
falhada, 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 a sexta tentativa também falhou, a transferência transita
para `COUNTERPARTY_VASP_NOT_REACHABLE` com `last_error` na sua
`timeline`; qualquer outra mensagem que falhe definitivamente é anotada
na `timeline`. O `status` da transferência permanece a fonte da verdade
para o intercâmbio 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
quando é enviada). `ANSWER`: a sua aceitação ou recusa, devida à
rede requerente (de entrada). `TXID`: o hash da transação on-chain,
após concluir a transferência. `CANCEL`: o cancelamento, após
cancelá-la. `POLL`: uma consulta de estado a uma rede que o
disponibilize, repetida a cada 5 minutos enquanto a transferência
aguarda a contraparte.
status:
type: string
enum:
- QUEUED
- SENDING
- RETRYING
- DELIVERED
- FAILED
description: >-
`QUEUED`: a aguardar envio. `SENDING`: tentativa em curso.
`RETRYING`: uma tentativa falhou e a próxima será executada em
`next_attempt_at`. `DELIVERED`: o outro lado aceitou a mensagem.
`FAILED`: o outro lado recusou-a, ou a última tentativa falhou.
rail:
type: string
enum:
- INTERNAL
- TRP
- GTR
- TRUST
- VERIFYVASP
- SYGNA
- EMAIL
- ''
description: >-
O canal que transporta a mensagem. Vazio até que a Didit escolha um
para uma primeira mensagem.
attempts:
type: integer
minimum: 0
description: >-
Tentativas efetuadas até ao momento para esta mensagem. Uma mensagem
que não seja uma sondagem de estado é tentada no máximo 6 vezes.
last_error:
type: string
description: >-
O tipo de falha ocorrida na última tentativa, `""` se não tiver
ocorrido nenhuma: por exemplo `email undeliverable`, `trp identity
endpoint unreachable` ou `trp transfer inquiry delivery failed`.
Nunca inclui a resposta da própria contraparte, que permanece na
`timeline` da transferência.
Quando a GTR responde com um erro, o respetivo código de estado e
mensagem 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 estiver
em `QUEUED` ou `RETRYING`.
delivered_at:
type: string
format: date-time
nullable: true
description: Quando a outra parte recebeu a mensagem.
TravelRuleDiscoveryStep:
type: object
description: >-
Um passo da deteção de contraparte que a Didit executou para uma
transferência de saída, na ordem em que foram executados. O primeiro
passo que identifique um VASP com uma rota termina 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 provou o
controlo da carteira de destino. `wallet_attribution`: a atribuição
da carteira na análise de blockchain. `network_lookup`: uma rede que
pode indicar qual VASP detém o endereço. `customer_hint`: o nome do
VASP, LEI ou jurisdição que enviou em `beneficiary_data`.
`end_user`: a contraparte que o utilizador final (ou você) escolheu,
ou o pedido para escolher uma.
outcome:
type: string
enum:
- match
- miss
- skipped
description: >-
`match`: o passo indicou uma contraparte. `miss`: foi executado e
não encontrou nenhuma. `skipped`: não pôde ser executado, e `reason`
indica o motivo.
reason:
type: string
description: >-
Motivo legível por máquina, `""` numa 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 pelo passo, quando este tiver indicado
um.
rail:
type: string
nullable: true
description: O canal que alcança essa contraparte, quando o passo encontrou um.
at:
type: string
format: date-time
TravelRuleNextAction:
type: object
description: >-
Um elemento que faz avançar uma transferência com
`COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE`.
Consulte [Por que motivo uma transferência está
bloqueada](/pt/transaction-monitoring/travel-rule#por-que-motivo-uma-transferência-está-bloqueada).
properties:
action:
type: string
enum:
- select_counterparty_vasp
- declare_self_hosted
- add_vasp_hint
- update_compliance_email
- resend
description: >-
`select_counterparty_vasp`: o utilizador final escolhe o VASP de
destino no widget de titularidade da carteira, ou você envia um
PATCH com `action=beneficiary_vasp`. `declare_self_hosted`: o
utilizador final declara a carteira como autocustodiada no widget.
`add_vasp_hint`: indique à Didit quem é a contraparte, com um nome
de VASP, LEI ou Travel Address (por exemplo, um `travel_address` na
entrada do livro de endereços da carteira de destino) e, em seguida,
reenvie. `update_compliance_email` e `resend` são valores de
`action` de `PATCH /v3/transactions/{transaction_id}/travel-rule/`:
forneça novamente o e-mail de conformidade da contraparte e execute
o encaminhamento outra vez.
url:
type: string
format: uri
description: >-
A ligação do widget de titularidade da carteira, em
`select_counterparty_vasp` e `declare_self_hosted` enquanto a
transferência tem uma sessão do widget aberta.
required:
- action
TravelRuleChainDetails:
type: object
description: >-
Como a blockchain da transferência designa as suas duas carteiras,
quando se trata de mais do que um endereço a pagar a outro. Vazio (`{}`)
para uma transferência numa blockchain baseada em contas (EVM, Solana,
Tron), onde os dois endereços são as carteiras. A correspondência, o
encaminhamento e o livro de endereços leem primeiro as carteiras 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: >-
Numa transferência UTXO: as entradas e saídas conforme armazenadas
(quantias como cadeias decimais) e quais saídas a Didit interpretou
como o quê.
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 ao beneficiário; null quando não foi possível
distingui-la.
lightning:
type: object
description: >-
Numa transferência Lightning: o conteúdo do pedido de pagamento.
Sempre `kind` (`bolt11`, `bolt12_offer`, `bolt12_invoice`,
`bolt12_invoice_request`, `lnurl`, `lightning_address`, `node_id` ou
`unknown`); uma fatura BOLT11 adiciona `network`, `payee_node_id`,
`payment_hash`, `amount_msat`, `created_at` e `expires_at`; uma
cadeia BOLT12 adiciona `blinded_paths` e `payee_node_id`; um LNURL
ou um Lightning Address adiciona o seu `domain`. Nada é resolvido
através da rede: o pedido é apenas descodificado.
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 ordenante declarado
não é uma entrada, o beneficiário declarado não é uma saída, nenhuma
saída individual de beneficiário pôde ser identificada ou a saída do
beneficiário paga um montante diferente do indicado na transação.
not_applicable_reason:
type: string
enum:
- LIGHTNING_NO_PAYEE_IDENTIFIER
- LIGHTNING_BOLT12_BLINDED_PAYEE
- LIGHTNING_LNURL_NAMES_NO_PAYEE
description: >-
Numa transferência Lightning de saída cujo pedido de pagamento não
indique um beneficiário: o motivo pelo qual a transferência é
`NOT_APPLICABLE`. `LIGHTNING_NO_PAYEE_IDENTIFIER` (o pedido não
indica o nó do beneficiário ou não pôde ser descodificado),
`LIGHTNING_BOLT12_BLINDED_PAYEE` (a oferta oculta o seu beneficiário
através de caminhos ocultos), `LIGHTNING_LNURL_NAMES_NO_PAYEE` (um
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. Numa rede memo, o endereço clássico (um endereço X do
XRP é dividido no seu endereço clássico e na respetiva etiqueta); na
Lightning, o ID do nó do beneficiário ou o Lightning Address.
memo:
type: string
description: >-
A tag ou memo de destino que faz parte da carteira; `""` quando não
existe nenhum memo.
source:
type: string
enum:
- declared
- x_address
- largest_input
- only_non_change_output
- amount_match
- invoice_payee
- updated
description: >-
Origem da carteira: `declared` (o seu pedido), `x_address` (dividido
a partir de um X-address de 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 montante da transferência), `invoice_payee` (o beneficiário
indicado por um pedido de pagamento Lightning), `updated` (definido
posteriormente com `action: update_originator_wallet`).
TravelRuleUtxoEntry:
type: object
description: >-
Uma entrada ou saída de uma transação UTXO, tal como a blockchain a
registou.
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 um input gasta.
vout:
type: integer
nullable: true
minimum: 0
description: Opcional. O índice do output que é gasto por um input.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
A chave de API da sua aplicação, a partir de Programadores -> Chaves de
API na Business Console. A chave principal tem acesso total. Uma chave
nomeada pode ter o âmbito definido: nenhum, 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á
incorreta, 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 o
pedido veio de um endereço fora da sua lista de IP; 404 numa rota de
sessão significa que a sessão está fora dos fluxos ou estados da chave.
Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs
como nulos, e uma chave sem permissão de escrita em sessões recebe
ligações de sessão e tokens como nulos. Consulte
https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.