Choose your integration options

Integrating with UR comes down to three independent decisions. Pick one option from each.

UR is modular. You build your integration from three independent decisions: how your platform connects (Account Mode), how card spend settles (Card Mode), and how users verify identity (KYC Mode). Each decision stands on its own, so any combination of options works.

Three decisions

Before integration kicks off, confirm one option from each:

Decision	Options	What it determines
Account Mode	Managed Custody Mode · External Wallet Access Mode (+ legacy Delegated Mode)	How your platform connects to UR and who signs transactions
Card Mode	Fiat Only · Crypto Backed · No card	Where card spend draws funds from
KYC Mode	UR Webview · Sumsub SDK · Share token reuse	How the user completes identity verification

Once these three are fixed, the rest of the integration is a standard menu of Core Banking APIs (Pay-in, Payout, On-ramp, Off-ramp, FX, Card) wired against the chosen options.

Regardless of which options you choose, your platform is responsible for mapping and maintaining the relationship between your users' identifiers and their corresponding URID. This allows your platform to accurately reflect user states based on UR APIs and webhooks.

Account Mode

Account Mode determines how your platform connects to UR and who controls transaction signing.

Comparison

Feature	Managed Custody Mode	External Wallet Access Mode	Delegated Mode
Integration style	Web2 / API-first	Web3 / smart contract-first	Web2 / API-first
User onboarding	Partner-managed (Sumsub SDK or UR Webview)	Partner implements all UIs	Redirect user to UR Webview
Account creation	API-driven account provisioning	User signs a message with their wallet to mint a URID	Redirect to UR Webview
Transactions	Partner signs for fiat actions; user signs only for crypto (off-ramp)	User signs every action via their wallet	API-driven via delegated contract allowances
Asset custody	Fiat: UR-managed account / Crypto: same UR-managed account or a separate non-UR wallet	Self-custody in user's single external wallet	TEE-based embedded wallet (e.g., Turnkey, Privy)
Gas fees	UR pays (operator wallets)	User pays (gasless option available)	UR pays (operator wallets)
Card management	API-driven	User signature to authorize card creation and settings	Redirect to UR Card Webview
Development effort	Lower (standard REST API integration)	Higher (requires Web3 signatures and wallet connections)	Lower (standard REST API integration)

Delegated Mode is a legacy integration. New partners should use Managed Custody Mode or External Wallet Access Mode. See Delegated Mode for existing partners.

When to use each mode

We recommend Managed Custody Mode if your users don't have crypto wallets today, or if you want a banking app experience without exposing blockchain mechanics. Your backend calls UR APIs for fiat actions. The user's crypto can live in the UR-managed account or in a separate non-UR wallet. The user never deals with a wallet for banking actions.

We recommend External Wallet Access Mode if your users already manage their own wallets (MetaMask, Rabby, etc.) and expect to sign transactions themselves. You get more control over timing and execution, but you need Web3 infrastructure on your side.

Your platform looks like...	We recommend
Consumer FinTech app, exchange, or neobank	Managed Custody Mode
DApp, Web3 wallet, or DeFi aggregator	External Wallet Access Mode

Managed Custody Mode

Recommended path. Managed Custody Mode requires the least development effort (standard REST APIs, no Web3 wallet handling). Your backend orchestrates the user's fiat account via UR API; the user's crypto sits in that same UR-managed account, or in a separate non-UR wallet that your backend manages directly.

Your backend orchestrates the user's fiat account (managed by UR). The user's crypto can sit in that same UR-managed account or in a separate non-UR wallet. Users never interact with a wallet for fiat actions.

Architecture

How it works

• Your backend calls UR API for all fiat actions (pay-in, payout, FX, on-ramp, card).

• UR validates authentication, compliance, and executes on-chain.

• For off-ramp, your backend fetches a quote from UR; crypto is submitted to the UR off-ramp contract from whichever wallet holds it (the UR-managed account or a separate non-UR wallet).

• UR notifies you via webhooks on settlement.

User experience

Users complete KYC once during onboarding. After that, all banking actions (fiat and off-ramp) are handled by the partner backend; users are not prompted to sign.

See Managed Custody Mode for detailed integration steps and the API reference for endpoints.

External Wallet Access Mode

External Wallet Access Mode is for platforms where users bring their own wallet (e.g., MetaMask, Rabby) and maintain full self-custody of their keys.

UR does not provision an additional wallet for these users. The URID and fiat balances (tokenized deposits) are managed directly within the user's external wallet.

Architecture

Request flow

• Partner frontend requests an action from the partner backend.

• Partner backend calls UR API to get quote or transaction parameters.

• UR returns transaction data.

• Partner frontend prompts the user to sign with their wallet.

• User signs and submits the transaction to UR smart contracts.

• UR listens for on-chain events and notifies the partner via webhook.

User experience

The experience is Web3-native. Users must connect their wallet and sign messages or transactions to approve actions. Your platform acts as a facilitator, relaying these signatures to UR or guiding the user to interact with smart contracts directly.

See External Wallet Access Mode for detailed integration steps.

Card Mode

Card Mode determines where card spend draws funds from when your user taps their co-branded debit card. You choose a Card Mode separately from your Account Mode.

Fiat Only

The card draws exclusively from the user's UR fiat balance.

Card spend is booked against the user's existing UR fiat balance. The user funds that balance through any of the standard channels: bank pay-in, crypto off-ramp into UR, or transfers from another UR user. No partner-side prefund pool is required.

If the user wants to spend crypto, they first off-ramp crypto into their UR fiat balance, then tap the card. The off-ramp and the card swipe are two separate operations.

Step 1 (optional): Off-ramp, user-initiated, only if the user is starting from crypto

The user converts crypto to fiat. UR executes the conversion at a quoted rate and credits the user's UR fiat balance.

Step 2: Card swipe

The user taps their card. UR authorizes against the available UR fiat balance.

User experience: if the user already holds fiat in UR, the swipe is one tap. If they're starting from crypto, they need to off-ramp first.

API reference: No additional partner-side integration surface. UR handles authorization on-chain against the user's tokenized fiat balance. Use the standard Card endpoints in your Account Mode reference (External Wallet Access or Managed Custody Mode).

Crypto Backed

The card can settle directly against the user's crypto holdings, with no per-swipe off-ramp required.

This mode is for products that need users to spend crypto directly via the card, without manually off-ramping into fiat before each purchase. You do not have to custody the user's crypto for this to work. What matters is that you can reliably debit the user's crypto after a swipe is approved, through centralized custody, a smart contract wallet under your programmatic control, or an equivalent arrangement.

The mechanism is a Buffer Pool (also called the Prefund channel): you periodically top up USDC into a UR-side prefund pool, and card authorizations settle in real time from that prefunded balance. You then debit the user's crypto asynchronously after the swipe, using UR's swipe-result webhook as the trigger. UR only reports the fiat swipe amount; you decide, based on your own pricing and conversion logic, how much crypto to debit from the user.

Phase 1: Prefund (partner-initiated, scheduled)

You periodically send USDC to UR's prefund address on a supported off-ramp chain. UR off-ramps the USDC into USD and credits your card-management account on UR. UR maintains a configured minimum balance to ensure continuous card authorization capacity.

Phase 2: Card spend (user-initiated, real-time)

When the user taps their card, UR routes the authorization and asks you via webhook whether to approve, and which source to use (CRYPTO or FIAT). You must respond within 500 ms so UR can return an APPROVE / DECLINE to Mastercard within the 1.5-second authorization window.

• If you return sourceUsed: CRYPTO, UR books the spend against your prefunded card-management account.

• If you return sourceUsed: FIAT, UR books the spend against the user's UR fiat balance (same path as Fiat Only).

After UR returns the result to Mastercard, UR sends you a follow-up webhook. On a successful CRYPTO swipe, you are responsible for debiting the equivalent crypto from the user. UR does not move crypto on your behalf. How you enforce the debit is part of your own business logic, and typically relies on a smart contract wallet under your programmatic control or a centralized custody arrangement so the user cannot move the crypto between approval and debit.

User experience: Seamless. The user taps and pays. No manual conversion step is required.

Refund handling: Any card refund is credited to the user's UR fiat balance, regardless of whether the original spend was settled from digital assets or fiat.

Prerequisites for Crypto Backed

• Ability to make an initial USDC prefund to seed card spending capacity.

• Ability to schedule periodic USDC top-ups to UR's prefund address on a supported off-ramp chain.

• Ability to respond to the authorization webhook within 500 ms.

• Ability to reliably debit crypto from the user after the swipe is approved (typically via a smart contract wallet under your programmatic control or centralized custody, so the user cannot move funds between approval and debit).

• Operational tolerance for working-float management. If your pool drains below the minimum balance, authorizations begin to decline.

API reference: Card Mode: Crypto Backed plugs into either Account Mode. Three integration surfaces: Prefund account, Card authorization callback, Card Mode webhooks.

KYC Mode

UR is a regulated financial product. Every user must complete KYC (Know Your Customer) checks before accessing core banking features. You choose how KYC is delivered to your users. The right option depends on whether you already verify users with Sumsub today.

For the full list of what UR verifies and the data UR collects, see KYC & Compliance. That page covers identity methods, including NFC, penny transfer, and video verification, plus domicile checks, questionnaire categories, and AML/sanctions screening. This section focuses on integration, not data collection.

Choosing an option

Option	Best for	User-side action on UR	Partner engineering effort
1a. UR Webview (recommended for new partners)	Partners with no existing KYC vendor.	Full KYC inside UR's webview.	Lowest: redirect and handle return.
1b. Sumsub SDK (token from UR)	Partners who want KYC inside their own app and can integrate the Sumsub SDK.	Full KYC inside the partner app, against UR's Sumsub level.	Medium: Sumsub SDK integration.
2. Reuse via share token (recommended if Sumsub already in place)	Partners who already verify users with Sumsub on their own tenant.	None in the happy path. Step-up only if your level is lighter than UR's.	Medium: backend webhook and share-token automation.

Option 1: UR-hosted KYC

UR runs the full KYC flow for your user. You do not need any KYC vendor infrastructure on your side. KYC outcomes are delivered to you via the kyc_status webhook.

UR Webview (recommended)

This is the fastest integration path. Your platform redirects the user to a UR-hosted webview, where the full KYC flow runs end to end.

Happy path

• You redirect the user to UR's webview after partner-side authentication.

• User completes questionnaire, identity verification, domicile check, and Form A signing inside UR.

• UR notifies you via the kyc_status webhook when KYC reaches Live.

When to use it: Choose this path if you do not have an existing KYC stack or you want the fastest route to launch. It works for both web and mobile platforms because UR handles the NFC handoff internally, so the mobile-NFC constraint does not apply to your app.

Sumsub SDK (token from UR)

You integrate the Sumsub WebSDK or Mobile SDK directly. UR's backend issues the SDK access token, so KYC runs inside your app shell while still using UR's Sumsub level.

Happy path

• Your backend calls POST /api/v1/sumsub/create-access-token for the user. See Section 2.1.5 in the API reference.

• Your frontend initializes the Sumsub SDK with the returned token.

• User completes KYC inside the partner app, including questionnaire, identity verification, domicile check, and Form A.

• UR notifies the partner via the kyc_status webhook on completion.

Mobile NFC requirement. NFC chip scan is only supported in the Sumsub mobile SDK (iOS / Android). Web-only platforms cannot complete the NFC step inside their own shell. If you are web-only, choose 1a (Webview). UR handles the NFC handoff for you. Penny transfer and video verification are also available for users who cannot complete NFC; see KYC & compliance: identity verification.

When to use it: You want KYC to feel native inside your app and you have the engineering capacity to integrate Sumsub.

Option 2: reuse your existing KYC (share token) (recommended if already on Sumsub)

If you have already verified the user with Sumsub on your own tenant, you can share that verification with UR through Sumsub's share-token mechanism. UR reruns the required checks against UR's verification level. In the happy path, the user is not prompted again.

Prerequisites

• Your platform uses Sumsub.

• You and UR have configured each other as Donor / Recipient Partners in the Sumsub dashboard.

• A Data Processing Agreement (DPA) is in place between your company and UR.

• Your privacy notice and consent flow explicitly disclose the share to UR for the purpose of opening a banking account.

Happy path

• Your backend listens for Sumsub's applicantReviewed webhook on your tenant.

• On approval, your backend calls Sumsub to generate a share token scoped to UR's clientId.

• Your backend submits the share token together with your internal user reference to UR through the channel agreed with UR integration support.

• UR calls Sumsub reuse against UR's verification level. Selfie/liveness is reused from the donor profile.

• UR notifies you via the kyc_status webhook with the result.

When to use it: Your users have already been verified on your Sumsub tenant and you want to onboard them to UR without re-verification.

What this option is not: UR does not accept raw KYC data exports through your app token. The share-token reuse flow is the only supported backend path because it produces a verification attestation on UR's Sumsub tenant, which is required for UR's Customer Due Diligence (CDD) obligations.

Where to read more

This page focuses on the integration contract. For the underlying KYC process, including what UR verifies, the data UR collects, identity-verification methods, proof-of-address constraints, AML/sanctions screening, and URID status outcomes, see KYC & compliance.

For partner-engineering notes on document uploads: when a user uploads proof-of-address documents through your application, you can pre-filter for the supported languages (English, German, French, Italian) and reject unsupported documents early. Documents in other scripts can still be forwarded to UR. They will be routed to manual review by UR's support team, which adds latency.

Next steps

Once you have chosen one option from each, proceed to the detailed integration guide for your Account Mode:

• Managed Custody Mode integration guide

• External Wallet Access Mode integration guide

For card integration:

• Fiat Only: uses the standard Card endpoints in your Account Mode API reference (no separate integration surface).

• Crypto Backed: has a dedicated API reference that plugs into either Account Mode.

For KYC details beyond integration mechanics:

• KYC & compliance covers the full verification process, data collected, and status outcomes.