External Wallet Access Mode

1. User Onboarding

User Onboarding in External Wallet Access Mode is designed for Web3 wallet users to apply for a UR Account. The process focuses on cryptographically verifying wallet ownership and minting the URID (Identity NFT) directly to the user's wallet, ensuring they maintain full control of their identity from day one.

Flow Description:

• Identity Initialization: The Partner App first validates the user's email availability and, upon success, triggers the minting of a "Tourist" status URID NFT associated with the user's wallet address.

• KYC Data Collection: The Partner integrates the Sumsub SDK. The partner's frontend requests a specific Sumsub token scoped to the user's URID and launches the SDK to collect identity documents and biometric data. A webhook notifies the Partner when data collection is complete.

• Document Signature: UR generates 'Form A' — a legal declaration required by regulation — for users to sign. Upon receiving the webhook notification confirming the completion of KYC data collection, the Partner must fetch the user's KYC document and display the information to the user. The user cryptographically signs this document using their external wallet (EIP-712 standard), and the Partner submits this signature to UR for compliance validation.

• Approval & Finalization: Once the asynchronous compliance review is completed, UR updates the on-chain status to "Live" and notifies the Partner. The Partner can then retrieve the user's profile details (IBAN, etc.).

2. Card

Card Operations in External Wallet Access Mode are designed for users to manage their co-branded debit card directly from their self-custody wallet. High risk actions, such as setting spending limits, card activation, and viewing card details, are secured through user's offline signatures.

• Status Check: The Partner App queries the current card status to determine if the user needs to activate a new card or view an existing one.

• Activation (If applicable): If no card exists, the user initiates an activation request. This involves signing a request to create the card.

• Set Allowance: The user grants spending authority over their UR account balance (on-chain Fiat tokens) by generating an EIP-2612 "Permit" signature. This offline signature authorizes the default currency allowance, with UR handling the subsequent on-chain submission and gas payment.

• Secure Display: To view sensitive data (PAN, CVV), the user first calls the card information API. The response includes a cardToken alongside basic card details. The Partner Frontend uses this token to launch a secure Webview to display the sensitive data within a secure zone.

3. Off-ramp Flow (Crypto-to-Fiat)

This flow enables users to convert held crypto assets into fiat balances within their UR account. In External Wallet Mode, this could be a direct interaction between the user and the UR Contracts. The user requests a quote and manually signs the transaction using their wallet to transfer crypto assets, ensuring the user remains the sole entity capable of initiating fund movements.

• Quotation: The user requests a conversion amount (e.g., USDC), and the Partner frontend fetches a quote containing the exchange rate, fees, and estimated fiat output.

• Execution: Upon confirmation, the Partner App prompts the user to sign and submit the transaction directly to the UR Contract.

  • Note: In this mode, the user pays the gas fee for the on-chain transaction.

• Settlement: The Partner App monitors the blockchain for the specific DepositSuccess event. If confirmed within the timeout window, the UI is updated; otherwise, the Partner reports the timeout to UR operations for reconciliation.

4. On-ramp Flow (Fiat-to-Crypto)

The On-ramp process in External Wallet Access Mode is designed to convert UR fiat balances into crypto assets using a gasless execution model. Instead of broadcasting the transaction themselves, the user provides a EIP-2612 signature (Permit) authorizing the trade, which the Partner submits to onchain via API to help users to abstract gas fees from the transaction.

• Quotation & Risk: The Partner App requests an onramp quote. UR's backend performs real-time risk checks and returns the quote along with any required verification flags.

• Step-up Verification (If required): If the transaction triggers a risk rule (e.g., Liveness Check), the Partner App must redirect the user to a verification Webview before the user can continue the onramp request.

• Gasless Execution: The user accepts the quote and provides an offline signature (Permit). The Partner frontend submits this signature via API. UR validates the signature and executes the onramp contract on-chain, covering the gas fees on behalf of the user.

• Settlement: The Partner App monitors the transaction hash for confirmation and updates the user interface upon success or reports a timeout if the network is congested.

Fiat-to-Fiat (FX)

The FX flow allows users to exchange one fiat token for another by signing an off-chain authorization and letting UR execute the transaction on-chain.

Flow Description:

• Quotation: The Partner frontend calls POST /fx/quote with input token, output token, and amount, then shows the user the estimated output, fees, and effective rate.

• Permit & Execution: After user confirmation, the app collects a wallet signature and submits POST /fx-permit. UR verifies the signature and executes the exchange on-chain.

• Status Update: The Partner receives asynchronous webhook updates (fx.approved or fx.rejected) and updates UI and balances.

• Fee Handling: Per PRD, network costs are deducted from the user's input fiat amount.

Cash Pay-in

Users' bank account details can be retrieved via the Profile API. Currently, bank transfers are limited to same-name accounts in EUR and CHF only.

Cash Pay-out (Bank Transfer)

This flow covers direct bank transfer payouts with recipient verification, signed authorization, and asynchronous transfer/refund webhooks.

Flow Description:

• Recipient Setup: The user either selects an existing contact or creates a new recipient.

  • Create a contact:

    • Get the supported bank&country list from the bank country API. User can select the country from the returned list.

      • If the selected country has ibanMetadata , you can let users to input IBAN, and use this API to verify and retrieve bank info .

      • If the selected country is a non-IBAN country (no ibanMetadata value), you will need users to select the bank name from the list and input the bank account.

    • Recipient's personal info should be input carefully, includes input name, select country and city, select payout purpose, inout address and and reference.

      • All the info should be verified by this API, if the recipient info is valid, a contactId, a refId and a purposeId will be returned. These three parameters are mandatory prerequisites for proceeding to the payout.

  • Select a contact:

    • Recipient Selection: Users can select a pre-saved recipient retrieved via the profile API. The contactId and are automatically derived from the selected recipient profile.

      • Reference Validation: The user manually inputs the payment reference, which is then verified via the API to generate the refId and purposeId .

      • With the 3 parameters collected, user can proceed the payout.

• Permit and Payout : The app requests a payout quote, then collects a wallet signature tied to refId, contactId, and purposeId before calling the payout API.

• On-chain Execution: UR submits the payout transaction and returns txHash for partner-side status tracking.

• Asynchronous Final State: Final outcome is delivered by webhooks (transfer.approved, transfer.rejected, transfer.refunded). If rejected, refund completion is notified separately.

• Input Constraints: Name/address/reference fields should use Latin characters only. Gas fee is deducted from the user's fiat transfer amount.