Skip to main content
POST
curl
Didit’s ownership confirmation API returns the transfer decision with its nullable ownership proof request. The response includes proof_request with request_id, request status, expires_at and nullable proof, using the same transfer proof request contract as transaction detail. A missing proof is not a reversal of the saved transfer decision. Didit’s Travel Rule ownership API records the ownership decision and returns the transfer state.

Self-hosted wallets

When the counterparty wallet was declared self-hosted (counterparty.payment_method.method_type: "unhosted_wallet"), the transfer waits in UNCONFIRMED_OWNERSHIP. Calling this endpoint with confirmed: true records that your customer verified who controls that wallet and completes the transfer (COMPLETED), for both outbound withdrawals and inbound deposits. An inbound deposit whose on-chain hash is already known moves on to FINISHED. The wallet verified is the counterparty’s: the destination of an outbound withdrawal, or the source (the originator’s wallet) of an inbound deposit. Didit adds it to the wallet address book as ownership-verified under the counterparty’s name, so it is matched against the counterparty’s name (the originator, for a deposit). If the address book already holds that wallet under a different holder name, the transfer moves to COUNTERPARTY_MISMATCHED_DATA instead. If the transfer names no counterparty wallet at all, pass wallet_address in the request body. When neither the transfer nor the request supplies a wallet address, the request is rejected with 400. confirmed: false declines the transfer (COUNTERPARTY_VASP_GENERAL_DECLINE). Proof and exemption state The transfer response includes not_required_reason and proof_state, also returned on a transaction’s nested travel_rule object. See Proof and exemption state for their values and precedence.

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Headers

Idempotency-Key
string

Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.

Required string length: 1 - 255

Path Parameters

transaction_id
string<uuid>
required

Didit-stable UUID of the transaction your application holds for this transfer: the beneficiary side's transaction on an INTERNAL-rail transfer, or the transaction you created (outbound or inbound) when the counterparty wallet was declared self-hosted.

Body

application/json
confirmed
boolean
required

true to confirm ownership, false to deny it.

wallet_address
string
default:""

Inbound TRP transfers: the payment address Didit returns to the originating VASP when you approve. Defaults to the matched address book entry's address, then beneficiary_data.wallet_address. On a declared self-hosted wallet transfer that names no counterparty wallet, the wallet whose ownership you verified; without it the request is rejected with 400. Ignored for other transfers.

Response

The updated transfer. For an inbound transfer the counterparty's originator_data/beneficiary_data stay masked (data_masked: true) until ownership is confirmed, then data_unmasked records when, why and by whom.

Full transfer object returned by the ownership-confirmation and finish/cancel endpoints. While an inbound transfer's wallet ownership is unconfirmed, the counterparty's originator_data and beneficiary_data come back masked (the first letter of each word is kept; the wallet, chain and VASP routing stay readable) and data_masked is true.

uuid
string<uuid>
status
enum<string>
Available options:
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
enum<string>
Available options:
INBOUND,
OUTBOUND
rail
enum<string> | null

The rail the transfer was routed over, or null when no rail was selected (for example below the threshold, a self-hosted counterparty wallet, an after-deposit registration, or no reachable counterparty). INTERNAL means both sides are Didit applications; EMAIL means the counterparty was reached by an emailed pickup link. TEST_VASP means the Didit Test VASP answered the sandbox transfer. Over GTR, VERIFYVASP and SYGNA, Didit reads the counterparty's answer from the network's response or by polling it every 5 minutes. TRUST only sends, so a TRUST transfer stays AWAITING_COUNTERPARTY until it expires. A network rail is used only when you have connected your own membership for that network. It is chosen after the transaction create returns, so it is null in that response.

Available options:
INTERNAL,
TRP,
GTR,
TRUST,
VERIFYVASP,
SYGNA,
EMAIL,
TEST_VASP,
null
protocol
string | null
ivms_version
string
Example:

"ivms101.2023"

required
boolean
ownership_confirmed
boolean | null
deadline_at
string<date-time> | null
timeline
object[]
counterparty_vasp
object | null
originator_data
object

Originator party. For an inbound transfer the counterparty's values are masked until ownership is confirmed.

beneficiary_data
object

Beneficiary party. For an inbound transfer the counterparty's values are masked until ownership is confirmed.

name_match
object · null · null

The name comparison that decided the transfer, or null until one ran. While the parties are masked, and on the other customer's copy of an INTERNAL exchange, transfer_name, compared_name, matched_names and mismatched_names are hidden. score and matched can disagree: matched follows the strictness, score is the similarity of the two full names.

data_match
object | null

Field-by-field comparison of the transfer's party data with what the other side knows about the wallet holder. It names fields and results, never values, so it stays readable while the counterparty's data is masked. Null until a comparison ran.

mismatched_fields
string[]

Shortcut for data_match.mismatched_fields. Empty when nothing differs.

data_unmasked
object | null

Audit record of the moment the counterparty's data was unmasked. Null while the data is still masked, and for outbound transfers.

data_masked
boolean

True while the counterparty's personal data is masked in this response.

created_at
string<date-time>
delivery
object | null

Where the latest message this transfer owes the other side stands. Null when the transfer never owed one (for example below threshold_amount, a declared self-hosted wallet, or a sunrise registration).

discovery
object[]

How Didit looked for the counterparty, one entry per step that ran. Empty when no discovery ran, for example on an inbound transfer.

reason
string

Why a COUNTERPARTY_VASP_NOT_FOUND or COUNTERPARTY_VASP_NOT_REACHABLE transfer is stuck; "" for any other status. A failed delivery decides it first, on COUNTERPARTY_VASP_NOT_REACHABLE only: email_undeliverable (the mail provider refused the compliance email and no address is left to try: when it was sent, on a reminder, or as a permanent bounce reported later) or delivery_failed (the rail that was delivering failed for good: a network rail refused the message or ran out of retries, a TRP identity host did not answer, or the counterparty's TRP host did not accept the inquiry). Otherwise the discovery trace decides it: awaiting_end_user (no step named a counterparty Didit can reach), directory_match_no_route (a step named a directory VASP that has no route), picked_member_without_proven_wallet (the end user picked a Didit customer that has not proven control of the wallet and that the directory no longer lists), or no_directory_match when the trace gives no other reason. A resend moves the transfer on, so the reason clears. See Why a transfer is stuck.

next_actions
object[]

What moves the transfer on; [] for any status but COUNTERPARTY_VASP_NOT_FOUND or COUNTERPARTY_VASP_NOT_REACHABLE. email_undeliverable offers update_compliance_email, then resend. delivery_failed offers resend. A discovery reason offers select_counterparty_vasp, declare_self_hosted, add_vasp_hint and resend.

chain_details
object

How the transfer's chain names its two wallets, when that is more than one address paying another. Empty ({}) for an account-chain transfer (EVM, Solana, Tron), where the two addresses are the wallets. Matching, routing and the address book read the wallets from here first.

deliveries
object[]

Newest 100 delivery entries, presented oldest first (creation time, then identifier). Empty when no messages exist. Use the paginated delivery endpoint for complete history.

Maximum array length: 100
deliveries_truncated
boolean

True when older entries were omitted from deliveries. Follow GET /v3/transactions/{transaction_id}/travel-rule/deliveries/ for the complete history.

not_required_reason
string | null

Null when required is true. Otherwise below_threshold, the recorded chain exemption (for example LIGHTNING_NO_PAYEE_IDENTIFIER, LIGHTNING_BOLT12_BLINDED_PAYEE or LIGHTNING_LNURL_NAMES_NO_PAYEE), or unknown for legacy transfers without a recorded reason.

Example:

"below_threshold"

proof_state
enum<string>

not_required when the transfer is not required; otherwise confirmed or not_confirmed follows ownership_confirmed. With no verdict, requested means an active outbound ownership widget matches this transfer and subject; otherwise not_requested. A request is not completed proof.

Available options:
not_required,
confirmed,
not_confirmed,
requested,
not_requested
Example:

"not_requested"

cancel_reason
enum<string>

Recorded cancellation reason, empty when unspecified.

Available options:
,
user_cancelled,
wrong_wallet,
compliance_decision,
other
cancelled_by
string

Recorded cancellation actor, or an empty string when none is recorded.

notify_on_answer
boolean

Saved team notification preference. Initially false.

user_choice
object | null

Explicit user-choice state, or null when counterparty_choice=user was not requested.

proof_request
object | null

Latest application- and subject-scoped request if it matches this transfer counterparty wallet and chain; otherwise null. A standalone request is not attached to a transfer. Request status and proof verdict are separate from the saved transfer decision.

Last modified on November 14, 2026