Merchant Deposit Travel Rule iframe integration

Companion screens: Select a Deposit Order · Submit Address Information
iframe pattern: FE: Create stablecoin collection sub-account link
APIs: Wallet · Deposit whitelist

Merchant-embedded hosted page: select a pending deposit, then submit Travel Rule (payer / source-address) details. Same model as Merchant Collect (server-issued URL in an iframe, close via postMessage, optional darkMode). This is the embed contract, not the in-app Wallet banner / Address Book.

1. Embedding

Suggested chrome: 720px right drawer, full viewport height, parent overlay rgba(0,0,0,0.5).

Attribute	Description
`allow="clipboard-write"`	Copy Transaction ID inside the iframe.

Do not set allow-same-origin in sandbox.

1.1 URL issuance (TBD with backend)

The merchant does not assemble the hosted path. Backend returns a short-lived URL that already carries auth (token), same as Merchant Collect.

Item	Proposed	Confirm
Path	`/{lng}/deposit-travel-rule`	Yes
Auth	URL `token`	Yes
Deep-link	`transactionId` skips the list	Yes

https://merchant.bpn.finance/en/deposit-travel-rule?token=xxx
https://merchant.bpn.finance/en/deposit-travel-rule?token=xxx&transactionId=20573580428712136704&darkMode=true

2. Screens

2.1 Select a Deposit Order

Title Select a Deposit Order. Each card: {amount} {symbol} Deposit, Submit, Time, Wallet, Wallet Address, Hash, Transaction ID (copy + open-in-new).

List: GET /v1/wallet/history?whiteListStatus=init and rejected. Empty / loading / error are not in Figma — follow Merchant Collect.

2.2 Submit Address Information

Title ID #{transactionId}. Banner: submit address information to avoid delays; non-whitelisted deposits stay pending. Tag Awaiting submission. Same detail rows as 2.1.

UI	API
Correspondent Type Entity / Individual	`correspondentType`: `ENTITY` / `INDIVIDUAL`
Wallet Label `0/50`	`walletLabel`
Address Type Standard / Universal	`addressType`: `STANDARD` / `UNIVERSAL`
Wallet Type VASP / Self-hosted	`walletType`: `VASP` / `SELF_HOSTED`

Footer Cancel / Submit (disabled until valid). Submit: POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit + Idempotency-Key. Never send walletAddress / network / memo / symbol / txHash (10000106).

2.3 Design vs API gap

Figma 6206:103270 does not show fields the submit API still requires:

ENTITY: fullName, countryCode, companyAddress

INDIVIDUAL: firstName, lastName, birthday, countryCode, residentialAddress

VASP: provider from GET /v1/wallet/deposit-whitelist/options

OTHERS: othersPleaseSpecify (not on this frame)

Decision: extend the iframe form to the full payer schema, or the submit will fail with 10000102 / 10000103.

3. Close event: postMessage

Field	Type	Description
`type`	string	Always `'DEPOSIT_TRAVEL_RULE_CLOSED'`
`source`	string	Always `'deposit-travel-rule'`

{
  "type": "DEPOSIT_TRAVEL_RULE_CLOSED",
  "source": "deposit-travel-rule"
}

Send only inside an iframe, to window.parent.

Proposed extra event after success: 'DEPOSIT_TRAVEL_RULE_SUBMITTED' with transactionId and whiteListStatus (pending). Confirm vs close-only (Merchant Collect is close-only).

4. Parent listener

5. darkMode

URL query darkMode=true|1|yes / false|0|no. Parent → iframe postMessage:

postMessage overrides the URL parameter.

6. APIs used by the hosted page (not by the embedder)

Scenario	Method	Path
Queue	GET	`/v1/wallet/history?whiteListStatus=init\|rejected`
Detail	GET	`/v1/wallet/transactions/{transactionId}`
VASP list	GET	`/v1/wallet/deposit-whitelist/options`
Submit	POST	`/v1/wallet/deposit-whitelist/transactions/{transactionId}/submit`

After submit, whiteListStatus is pending. Do not treat the deposit as SUCCESS. Already-ACTIVE source addresses never enter this UI.

FE: Deposit Travel Rule

Merchant Deposit Travel Rule iframe integration#

1. Embedding#

1.1 URL issuance (TBD with backend)#

2. Screens#

2.1 Select a Deposit Order#

2.2 Submit Address Information#

2.3 Design vs API gap#

3. Close event: postMessage#

4. Parent listener#

5. darkMode#

6. APIs used by the hosted page (not by the embedder)#