Managed Custody Mode

API-driven integration where UR manages fiat accounts and the partner manages crypto.

In Managed Custody Mode, the partner backend is the single orchestrator for all user banking actions. UR manages a fiat account per user (tokenized deposits, IBAN, card). For compliance, the UR-managed account holds fiat only; the user's crypto is always held in an external (non-UR) wallet, either partner-side or the user's own. The user never interacts with a wallet for fiat actions.

This mode is designed for consumer fintechs, exchanges, and neobanks that want to offer banking features behind their own UX without exposing blockchain mechanics to end users.

Architecture

In Managed Custody Mode the user's fiat account is always UR-managed and holds fiat only. The user's crypto is always held in a separate external (non-UR) wallet:

Account	Managed by	Holds
User Fiat Account	UR	Tokenized deposits (EUR, USD, CHF, etc.), IBAN, card
User Crypto	A separate external (non-UR) wallet (partner-side or the user's own)	Crypto assets on supported chains

The partner backend calls the UR API for all fiat actions (pay-in, payout, FX, on-ramp (coming soon), card). A crypto action (e.g., off-ramp) is authorized on the external wallet that holds the crypto: the user signs when it is their own wallet, or the partner signs when it is a partner-side wallet.

Who signs what

Operation	Who authenticates	Notes
Pay-in	Partner signs	Partner fetches IBAN details via API; user sends wire from their bank
Payout	Partner signs	Partner submits payout request; UR dispatches SEPA/SWIFT
On-ramp (coming soon)	Partner signs	UR debits fiat from UR Account; crypto delivered to the user's external (non-UR) wallet
Off-ramp	Signed by the external wallet holding the crypto	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); fiat credited to UR Account
FX	Partner signs	Partner submits FX swap; UR executes atomically
Card setup	Partner signs	UR issues card; details revealed in secure UR-hosted view
Card spend	Automatic	Settlement governed by Card Mode (Fiat Only or Crypto Backed)

User onboarding

• The user's URID is minted into a UR-managed wallet during account creation.

• KYC has two supported paths. Pick one based on whether your platform already runs a Sumsub tenant.

  • Sumsub reuse (share token). Your platform completes KYC in your own Sumsub tenant and shares the approved applicant with UR. Because this path shares the user's KYC profile with UR, your KYC steps must present the required data-sharing declaration and capture the user's agreement before verification (see the required KYC disclosure). See API reference: Managed Custody Mode.

  • Sumsub SDK in your app. Your backend requests a UR-issued Sumsub access token and the Sumsub SDK in your app drives KYC against UR's Sumsub tenant. See API reference: Managed Custody SDK KYC.

• There is no on-chain delegation contract step (that is Delegated Mode). Your backend acts on the user's fiat account through authenticated API calls, after the user grants account access authorization (see Account access authorization).

• Once KYC reaches Live status and the user has authorized account access, all banking functions are unlocked.

Account access authorization

Managed Custody Mode lets your backend view a user's IBAN details and initiate transactions on their behalf through the UR API. Because of this access, you must obtain each user's explicit authorization during onboarding. The authorization has two parts: an in-app confirmation the user accepts, and a confirmation email you send afterward. Both are required for every Managed Custody Mode user.

In-app authorization confirmation

Show the following confirmation in your onboarding flow and record the user's acceptance before you enable banking functions. Replace [Partner Name] with your platform's name.

By confirming, you expressly authorize [Partner Name] to access your IBAN account. [Partner Name] will be able to view your IBAN information and initiate transactions. This authorization is effective until withdrawn by you.

Authorization confirmation email

After the user accepts, send a confirmation email to the user's registered address. Replace [Partner Name] with your platform's name.

BCC [e-mail] on every authorization confirmation email. This BCC is mandatory; it gives UR a compliance record that the user authorized account access.

Subject: Your [Partner Name] IBAN Account Access Has Been Authorized

Dear Customer,

Your IBAN account with [Partner Name], powered by UR, has been successfully created.

By completing the registration and using the related services, you authorize [Partner Name] to:
- view your IBAN information
- initiate transactions

You may revoke this authorization at any time by contacting [Partner Name]'s Customer Service. If you did not initiate this account opening or do not consent to this arrangement, please immediately notify [e-mail].

Best regards,
The [Partner Name] Team

Core banking functions

Pay-in

The user sends a bank transfer (SEPA or SWIFT) from their external bank to their UR IBAN. The partner fetches the user's deposit details via the Profile API, displays them, and UR credits the fiat balance when the wire settles. UR notifies the partner via webhook.

Payout

The partner submits a payout request on behalf of the user. UR debits the fiat balance and dispatches the bank transfer. The user does not sign; the partner backend authorizes the action.

Off-ramp (crypto to fiat)

The user initiates an off-ramp from the partner UI. The partner fetches a quote from UR, then the 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). Fiat is credited to the user's UR Account. The off-ramp contract is agnostic to the source wallet; the _targetAccount parameter names the UR Account that receives the fiat (see API reference §7.2). UR notifies the partner via webhook.

On-ramp (fiat to crypto)

Available soon. On-ramp (fiat-to-crypto) is not yet available for integration and will be enabled in a future release. The reference below is provided for preview only.

The partner fetches a quote and the user confirms. The partner submits the on-ramp request; UR debits the user's fiat balance and delivers the crypto to the user's external (non-UR) wallet. The user does not sign for the fiat debit.

FX (fiat to fiat)

The partner fetches a quote, the user confirms, and the partner submits the swap. UR executes the conversion atomically (burn one tokenized deposit, mint another). The user does not sign.

Card

The partner requests card issuance via API. UR issues the card; the card number and CVV are revealed only inside a secure UR-hosted view. Card spend behavior is governed by Card Mode (Fiat Only or Crypto Backed), which is chosen independently of the integration mode.

API reference

See API reference: Managed Custody Mode for endpoints, request/response formats, and webhook definitions.