External Wallet Access Mode

Self-custody integration where users connect their own wallet and sign transactions directly.

In External Wallet Access Mode, users connect their own Web3 wallet (MetaMask, Rabby, SafePal, etc.) and maintain full self-custody of their keys. The URID is minted directly to their wallet address.

This mode is designed for partners building Web3-native products where users expect to sign transactions themselves.

User onboarding

User onboarding 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.

NFC scanning requires a mobile app. The Sumsub SDK's Passport/National ID NFC scan step is only supported in the Sumsub mobile SDK (iOS/Android). It is not available in the Sumsub web SDK. Partners integrating via the External Wallet Access Mode must surface this KYC step through their mobile app. Users on a web browser cannot complete NFC-based identity verification. If your platform is web-only, contact us to discuss alternatives.

• 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.).

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.

Off-ramp flow (crypto-to-fiat)

This flow enables users to convert held crypto assets into fiat balances within their UR account. UR supports two chain families:

• EVM chains (Ethereum, Arbitrum, Mantle, etc.) — the user interacts directly with UR Contracts via their EVM wallet. See §4.1 Offramp API for EVM.

• Solana — the user deposits USDC via a Solana wallet. The Partner calls §4.2 Offramp API for Solana to get a pre-built transaction, which the user signs and submits on Solana. The USDC is bridged cross-chain to Mantle via LayerZero and converted to fiat.

The diagrams below illustrate the EVM path. For the Solana-specific flow (quote → sign → send → cross-chain settlement), refer to §4.2 in the API Reference.

• 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.

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 loads payout fee metadata early and uses the selected currency's fee and minimalPayoutAmount when presenting the transfer form. It 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.