is_ownership_verified: true, which lets a linked Travel Rule transfer advance out of UNCONFIRMED_OWNERSHIP.
When Didit mints it for you
You rarely need to mint a session yourself. Whenauto_wallet_verification is on in your Travel Rule settings (the default), Didit auto-mints a widget session at transaction creation whenever a transfer needs end-user proof of wallet control:
- The transfer is in
UNCONFIRMED_OWNERSHIP- the counterparty wallet was declared self-hosted at submission. - The transfer is outbound and in
COUNTERPARTY_VASP_NOT_FOUND- no counterparty VASP could be identified, so ownership proof is the remaining path to completion.
action_required block (type: "wallet_ownership", with the url to open), and the SDKs launch it automatically on client-side submission.
Inbound transfers that Didit creates for you (a sunrise registration, an inbound TRP inquiry, or the INTERNAL-rail inbound leg) never get an auto-minted session, even when they land in UNCONFIRMED_OWNERSHIP.
Mint manually with POST /v3/travel-rule/widget-session/ when you want to pre-verify a wallet before any transfer exists, when you have auto_wallet_verification turned off, or for one of those inbound transfers.
What it proves
The widget offers up to four proof methods. Which ones appear depends on how you minted the session and your Travel Rule settings:Message signing verify contract
Submitting the signature returns200 with status: "VERIFIED" once it proves control of the wallet.
It returns 400 and leaves the proof open, so the customer can sign again, with one of these code values:
Satoshi test verify contract
Verifying a Satoshi test deposit is asynchronous, because the transaction has to be seen on-chain and then be confirmed. Submitting the deposit’stxid returns 200 with status: "PENDING" while the deposit is not yet confirmed on-chain - the txid is retained, not discarded.
It returns 200 with status: "VERIFIED" once the deposit confirms.
It returns 400 with status: "REJECTED" for a genuinely wrong deposit: sent from another wallet, not the expected amount to the deposit address, older than the challenge, or a transaction that already proved another wallet. The proof is closed and the customer can start a new one while the session has attempts left.
A deposit that is not indexed yet also returns 200 with status: "PENDING", and a lookup that fails on Didit’s side returns 400 with code DEPOSIT_LOOKUP_FAILED: in both cases the proof stays open and Didit keeps checking.
It returns 410 if the test window expires before a valid deposit is seen.
Once a txid has been submitted, a background job rechecks the pending deposit every five minutes and completes the proof after the transaction confirms, so the customer does not need to resubmit the txid.
When you pass a satoshi_deposit_address, the widget session’s own expires_at is extended to at least the 24-hour Satoshi test window, giving the deposit time to confirm before the session itself expires.
Flow
1
Mint a widget session
Call
POST /v3/travel-rule/widget-session/ with the wallet you need verified. Optionally link it to a transfer so the transfer advances automatically once ownership is proven.2
Open the returned URL
Send your customer to the
url from the response. They complete a proof there - no Didit account or API key needed; the token in the URL is the authentication.3
Detect completion
When a proof is verified, the widget marks the address-book entry verified and, if the session is linked to a transfer, advances it. Watch for
travel_rule.status.updated (linked transfers) or poll the widget context.Mint a widget session
This example links the session to the declared self-hosted transfer from the Travel Rule guide, sowallet_address is that transfer’s destination wallet.
A session linked to a transfer only accepts proofs for the transfer’s counterparty wallet.
url returned in the response verbatim - do not construct it yourself.
Open the returned URL
Detect completion
The widget exposes a public read endpoint keyed by the token - poll it to see progress, or rely on webhooks when the session is linked to a transfer:completed_atbecomes non-null once a proof is verified.- Each entry in
proofscarries the fields its method needs: aSATOSHI_TESTproof addsdeposit_address,expected_amount, and its ownexpires_at; aMESSAGE_SIGNINGproof addschallenge, the string the customer signs. - A
SATOSHI_TESTproof can sit atstatus: "PENDING"while its deposit is seen on-chain but unconfirmed, with no action needed from you or the customer - see Satoshi test verify contract above. - When the session was minted with a
transaction_id, verifying the proof advances the linked transfer, and on a live application atravel_rule.status.updatedwebhook fires. Prefer the webhook over polling. An inboundTRPinquiry is approved back to the sender and moves toCOMPLETEDonce that approval is delivered. Any other transfer inUNCONFIRMED_OWNERSHIP(or an inbound oneON_HOLD) moves toCOMPLETED, or toCOUNTERPARTY_MISMATCHED_DATAwhen the beneficiary name does not match the wallet holder, and a settled sunrise deposit that completes continues toFINISHED. An outbound transfer inCOUNTERPARTY_VASP_NOT_FOUNDmoves toCOMPLETED. - A
SCREENSHOTproof keepsstatus: "PENDING"in this context even after you confirm ownership. You approve it withPOST .../travel-rule/ownership/, which only accepts a transfer awaiting ownership confirmation. A screenshot therefore has no approval path on a session with no linked transfer, or on a session linked to an outbound transfer inCOUNTERPARTY_VASP_NOT_FOUND: turn offallow_screenshot_proofif those sessions must not offer it. - After a rejected proof the session takes a new attempt while attempts remain.
max_attempts,attempts_used, andattempts_remainingreport the count, a rejected proof carriesrejection_reason, and whenattempts_remainingis0starting another proof answers409and you mint a new session. - The context endpoint returns
404for an unknown token and410once the session has expired without completing.
There are no one-shot dependencies here: the widget and your backend both converge on the same durable state (the verified address-book entry and the transfer status), so a dropped webhook or a closed tab is always recoverable by re-reading the transfer or the widget context.
Localization and branding
The widget renders in 54 languages, following the language path of the link (or the browser default). When whitelabel is enabled for your application, the widget inherits your verification-flow branding automatically: logo, brand colors, button and panel styling, custom font, favicon, and your app’s public name in the title. No separate configuration - the same customization you set up for KYC sessions applies here. A user who returns to an already-completed link sees the completion screen again; if you passed acallback_url, the widget returns them there.
Expired links show a branded expiry screen prompting them to request a new link.
Mint a new session with POST /v3/travel-rule/widget-session/ for them: resending a transfer with action: "resend" does not mint one.
Next steps
Travel Rule
The full exchange lifecycle, rails, settings, and receiving flows.
Wallet address book
Register the wallets you control so inbound transfers resolve against them.
Webhooks
Subscribe to travel_rule.status.updated to react when a proof advances a transfer.
Native SDKs
Open the widget URL with the system browser, not the SDK webview.