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:
Managed Custody Mode · External Wallet Access Mode (+ legacy Delegated Mode)
How your platform connects to UR and who signs transactions
UR-hosted webview · Sumsub SDK in your app · Sumsub reuse (share token)
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 (coming soon), Off-ramp, FX, Card) wired against the chosen options.
Before you start
Every integration starts with the same setup, whichever options you pick. Work through the following steps with UR once:
Check eligibility and limits
Two rules are enforced by UR, not configured by you, and both shape your product before you write any code:
Eligibility. UR checks country and nationality rules when a user opens an account. A user outside the supported lists cannot onboard, no matter how your funnel is built, so design for the rejection path. See Supported regions.
Monthly limit. Every
Liveuser carries a rolling monthly limit, denominated in CHF. Outbound and conversion operations (card spend, FX, payout, on-ramp) are checked against it and fail once it is exhausted. Read each user's live limit rather than hardcoding a figure, and subscribe to themonthly_limit_exceededwebhook so you can surface it. See Fetch UR Account information and Webhooks.
Raising a user's limit is a compliance review with UR, not an API call.
Generate and register your signing key
Get your signing key and partnerId. You have two options: create them in the API sandbox, which generates them for you, or generate an EVM key pair yourself and send UR the public address. Either way, UR issues a partnerId that scopes your API calls, and your private key stays on your side. See API signing key on this page for both paths and the full key lifecycle.
Account Mode
Account Mode determines how your platform connects to UR and who controls transaction signing.
Comparison
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: external (non-UR) wallet, partner-side or the user's own
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 lives in an external (non-UR) wallet, partner-side or the user's own; the UR-managed account holds fiat only. 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.
Consumer FinTech app, exchange, or neobank
Managed Custody Mode
DApp, Web3 wallet, or DeFi aggregator
External Wallet Access Mode
Managed Custody Mode
Your backend orchestrates the user's fiat account (managed by UR). The user's crypto sits in an external (non-UR) wallet, partner-side or the user's own; the UR-managed account holds fiat only. 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 (coming soon), 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 the external (non-UR) wallet that holds it (partner-side or the user's own).
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.
Integration SOP
Beyond the common setup in Before you start, Managed Custody Mode adds the following checklist:
Register your mainnet signing key through your integration channel so your backend can make API calls.
Implement account access authorization in your user onboarding. It has two mandatory parts: an in-app authorization confirmation the user accepts before you enable any banking function, and a confirmation email you send with
legal@ur.appon BCC. The BCC is mandatory; it is UR's compliance record. See account access authorization.Read the Managed Custody Mode API reference for account creation, profile, pay-in details, payout, FX, off-ramp quote, and card.
Subscribe to the settlement and status webhooks.
Map each user ID in your system to the URID issued at user onboarding.
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.
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.
Integration SOP
In this mode the URID and the user's fiat balances live in the user's own wallet, and the user signs their own transactions. Fiat transactions settle on Mantle Network, so make sure your users' wallets can interact with Mantle.
Beyond the common setup in Before you start, the mode-specific steps are the following:
Register your mainnet signing key through your integration channel so your backend can make API calls.
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 Mode or Managed Custody Mode).
Integration SOP
Fiat Only is the lightest card option to set up. The setup is the following checklist:
Complete the co-branded card artwork submission if you brand the card.
Use the standard Card endpoints in your Account Mode API reference: create card, get card info, set default currency, and card history. There is no card-specific settlement surface to build. See the card sections for Managed Custody Mode and External Wallet Access 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 keep your Prefund Account topped up by off-ramping USDC into it, 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 call the UR off-ramp contract on a supported off-ramp chain, converting USDC into your Prefund Account; the Prefund Account is the target account of the off-ramp. Schedule recurring off-ramp calls in your backend to keep the account above the minimum balance agreed with UR, so card authorization capacity stays continuous.
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. You must respond within 500 ms so UR can return an APPROVE / DECLINE to Mastercard within its 1-second total authorization window; your 500 ms sits inside that 1 second.
Your response picks the funding source:
Settle against your Prefund Account, and debit the user's crypto yourself after the swipe.
Settle against the user's UR fiat balance, the same path as a Fiat Only card.
The exact field contract for the authorization callback lives in the Card Mode: Crypto Backed API reference.
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 recurring off-ramp calls that top up your Prefund Account 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.
Integration SOP
Crypto Backed takes the most setup of the three card options, and the order matters. Work through the following steps:
UR provisions your Prefund Account
UR provisions your Prefund Account. It is one account per partner, and it can hold a balance in more than one settlement currency.
Choose your settlement mode
Your settlement mode decides who picks the debit currency on each swipe, and whether UR can pre-compute the amount for you:
Fixed (the default) means UR pre-computes the exact amount it will debit, including FX and interchange, and sends it in the authorization request. You approve or decline against that amount and run no conversion. You do not pick the debit currency per swipe.
Partner controlled means you pick which of your settlement currencies to debit on each swipe. UR cannot pre-compute the amount, because it does not know your choice in advance, so you size the debit yourself.
Start with Fixed unless you need per-swipe currency control. See the settlement modes reference.
Agree the funding parameters and minimum balances
Agree the off-ramp chain and the deposit currency (USDC only today) with UR.
Agree a minimum balance for each settlement currency. Thresholds are per currency, not per account, and UR emits a prefund.balance.alert when a currency reaches or falls below its threshold. Set each one above the float you need to absorb a normal day of swipes; when a currency runs dry, authorizations in that currency start to decline.
Register your card authorization callback URL
Register your card authorization callback URL with UR. UR calls it on every card authorization. Changing the URL later is coordinated with UR and paired with signature validation; there is no self-serve endpoint.
No card
Choose No card if your platform does not issue cards. Every other service in your integration (pay-in, payout, FX, off-ramp) works the same without one.
Integration SOP
There is nothing to set up and nothing to build. The Card endpoints, the card authorization callback, and the card artwork submission do not apply.
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 a method
Identity verification uses an NFC scan, so the user needs an NFC-capable mobile device; on the UR-hosted webview, UR runs that scan for you.
Which method fits you
UR-hosted webview if you have no KYC vendor and no mobile app of your own. UR runs the identity scan for you inside its webview.
Sumsub SDK in your app if you want KYC inside your own app and you have a mobile app to run the identity scan.
Sumsub reuse (share token) if you already verify your users in your own Sumsub tenant.
Upsides and downsides
UR-hosted webview
Lowest effort; no KYC vendor of your own. UR runs the identity scan for you.
The user leaves your app for UR's webview, so you have less control over the experience. KYC data lands in UR's Sumsub, not yours.
Sumsub SDK in your app
KYC feels native in your app. Minimal setup: integrate the Sumsub SDK and run UR's verification workflow through it, with no Sumsub tenant of your own.
KYC data lands in UR's Sumsub, not yours.
Sumsub reuse (share token) (recommended if Sumsub already in place)
No re-verification for users you have already verified. The verification data already lives in your own Sumsub tenant.
You run your own Sumsub tenant and automate the share-token handoff. Works only for users you have already verified.
Where the KYC data lands
UR-hosted webview and Sumsub SDK in your app: the verification is created in UR's Sumsub tenant.
Sumsub reuse (share token): the data already lives in your own Sumsub tenant; you share it to UR.
UR-hosted webview
Your platform redirects the user to a UR-hosted webview, where the full KYC flow runs end to end. You need no KYC vendor of your own; UR delivers outcomes via the kyc_status webhook.
Happy path
You redirect the user to UR's webview after partner-side authentication.
The user completes the questionnaire, the domicile (device location) check, and Form A signing in the UR webview.
For identity verification, the user completes the passport/national-ID NFC scan, the document scan, and the selfie in ReadID, opened as the ReadID app on Android or as an App Clip on iOS. UR orchestrates this handoff for you.
UR notifies you via the
kyc_statuswebhook when KYC reachesLive.
When to use it: Choose this path if you have no KYC vendor, or no mobile app of your own. You do not build the NFC scan; UR orchestrates the identity-verification handoff to ReadID for you. The user still completes the scan in ReadID on an NFC-capable mobile device.
Integration SOP
This method has no off-code setup beyond the common steps in Before you start. Build the redirect and consume the kyc_status webhook; there is nothing extra to request, sign, or configure.
Sumsub SDK in your app
You integrate the Sumsub SDK in your app and run UR's verification workflow through it; you do not run a Sumsub tenant of your own. UR's backend issues the token that starts the SDK. Setup is minimal: the SDK integration plus one backend call.
Happy path
Your backend calls
POST /api/v1/sumsub/create-access-tokenfor 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_statuswebhook on completion.
The NFC scan runs in the Sumsub mobile SDK, so this method needs a mobile app. If your platform is web only, use the UR-hosted webview instead, where UR runs the NFC scan for you. Penny transfer is an alternative for users who cannot complete an NFC scan (FATF jurisdictions); see KYC & compliance.
When to use it: You want KYC to feel native inside your app, you have a mobile app for the NFC scan, and you have the engineering capacity to integrate Sumsub.
Integration SOP
This method has no off-code setup beyond the common steps in Before you start. Integrate the Sumsub SDK, call the token endpoint, and consume the kyc_status webhook; there is nothing extra to request, sign, or configure.
Sumsub reuse (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 KYC flow presents the required data-sharing declaration to the user and captures their agreement before identity verification. Your privacy notice also discloses the share to UR.
Required KYC disclosure for data sharing. This option shares the user's verified KYC profile with UR through Sumsub's Reusable KYC network. This is a KYC requirement: your KYC flow must present the following declaration to the user and capture their agreement before they start identity verification. Surface it in your own KYC steps; UR does not show it for you on this path. Use this exact wording:
By proceeding with identity verification, I acknowledge and agree that my KYC information and verification results may be shared by us and/or Sumsub with Participating Verification Partners within Sumsub's Reusable KYC network for identity verification, anti-money laundering compliance, sanctions screening, regulatory compliance, fraud prevention, and other legal or regulatory purposes, including compliance requirements applicable to such Participating Verification Partners that may be independent from the specific products or services offered on our platform. For the purpose of this declaration, "Participating Verification Partners" means any third-party that participates in Sumsub's Reusable KYC network.
This declaration is the user-facing basis for the Sumsub share-token reuse below. It complements the Data Processing Agreement (DPA), which governs the share between your company and UR.
Happy path
Your backend listens for Sumsub's
applicantReviewedwebhook 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
reuseagainst UR's verification level. Selfie/liveness is reused from the donor profile.UR notifies you via the
kyc_statuswebhook 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.
Integration SOP
This method shares verification data between two companies, so it carries real off-code prerequisites. Complete the following before the first user flows through:
Coordinate the setup with UR through your dedicated integration channel.
Run your own Sumsub tenant.
Configure UR and your platform as Donor / Recipient Partners in the Sumsub dashboard.
Sign a Data Processing Agreement (DPA) with UR.
Present the required data-sharing declaration to the user verbatim and capture their agreement before identity verification starts. UR does not show it for you on this path.
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.
API signing key
UR authenticates every API call with an EIP-191 signature. There are no API keys and no OAuth tokens. Your partnerId is bound to a single EVM address, the public address of your signing key. You sign each request with the matching private key; UR recovers the address from the signature and compares it to the address on file for your partnerId. If they match, the request is authenticated.
UR never stores your private key. UR stores only your public EVM address. Keep the private key in a secure store such as a hardware security module (HSM) or a key management service (KMS). If you lose it, UR cannot recover it; you must register a new address.
You get your signing key and partnerId in one of two ways. Both end with the same credential: a partnerId plus an EVM key pair whose private key never leaves your side.
Option 1: create it in the API sandbox (recommended)
The API sandbox generates everything for you, so UR takes no manual action. Your partnerId and public address are registered the moment they are created.
Sign in to the sandbox
Sign in at partner.ur.app/api-sandbox. On your first sign-in, the sandbox creates your partnerId, public address, and private key, and ties them to your account.
Option 2: bring your own EVM address
Generate the key pair yourself with any standard tool and send UR only the public address. Use this path when you want the key to originate in your own infrastructure (for example, a script, a browser wallet such as MetaMask, or a hardware wallet).
After setup: sign, verify, and rotate
Once you hold a partnerId and key pair from either option, the runtime rules are the same:
Sign every request. Sign each API request with your private key using EIP-191. UR verifies the signature on every call.
Verify webhooks. For webhooks the direction reverses: UR signs the payload, and you verify it against UR's published server address.
Rotate when needed. To rotate keys, register a new address and deregister the old one through your integration channel.
See Signature and verify for the signing algorithm, the canonical payload format, and code samples.
Co-branded card artwork
Skip this section if you do not brand the card. The card is virtual, so users add it to Apple Pay or Google Pay. You produce and submit the following through your dedicated integration channel:
Your card artwork, exported as a flattened PNG at 1536 × 969 pixels, including the debit mark.
The Copyright Registration for your logo.
A signed Trademark License Agreement granting UR the right to reproduce your mark.
UR reviews your submission against Mastercard brand standards. Approval takes time, so start early. The full specification, the template download, and the submission steps live on Co-branded debit card design.
Next steps
Once you have chosen one option from each, proceed to the detailed integration guide for your Account Mode:
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.
Last updated