> For the complete documentation index, see [llms.txt](https://docs.ur.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ur.app/integration-methods/managed-custody-mode.md). # Managed Custody Mode 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). The user's crypto can be held in the same UR-managed account, or in a separate non-UR wallet (partner-side or the user's own). UR supports both. 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. The user's crypto can sit in that same UR-managed account, or in a separate non-UR wallet: | Account | Managed by | Holds | | --------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------- | | **User Fiat Account** | UR | Tokenized deposits (EUR, USD, CHF, etc.), IBAN, card | | **User Crypto** | The UR-managed account itself, **or** a separate non-UR wallet (partner-side / 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, card). The user only signs when a crypto action must be authorized on a non-UR wallet they control (e.g., off-ramp from the user's own wallet); when the crypto sits in the UR-managed account, the partner backend signs instead. ```mermaid flowchart LR subgraph User["End User"] U["User"] end subgraph Partner["Partner Platform"] PB["Partner Backend"] end subgraph UR["UR"] API["UR API"] end subgraph Accounts["User Accounts"] FIAT["User Fiat Account\n(UR-managed)\nTokenized deposits, IBAN"] CRYPTO["User Crypto\n(UR-managed account or\nseparate non-UR wallet)\nCrypto assets"] end subgraph Settlement["Settlement"] CHAIN["On-chain Settlement"] end U --> PB PB -->|"API calls\n(partner signs)"| API API --> FIAT PB -.->|"Direct management\n(only if crypto is in a non-UR wallet)"| CRYPTO FIAT --> CHAIN CRYPTO --> CHAIN ``` ## 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 | Partner signs | UR debits fiat from UR Account; crypto credited to the user's crypto wallet (the UR-managed account or a non-UR wallet) | | Off-ramp | Signed by the wallet holding the crypto | Crypto is submitted to the UR off-ramp contract from whichever wallet holds it: the UR-managed account (partner backend signs) or a non-UR wallet (the user signs); 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](/getting-started/integration-guide.md#kyc-data-sharing-disclosure)). See [API reference: Managed Custody Mode](/developer-resources/api-reference-managed-custody-mode.md). * **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](/developer-resources/api-reference-managed-custody-sdk-kyc.md). * 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](#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. {% hint style="warning" %} BCC `legal@ur.app` on every authorization confirmation email. This BCC is mandatory; it gives UR a compliance record that the user authorized account access. {% endhint %} ``` 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 support@ur.app. 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 whichever wallet holds it: the UR-managed account itself, or a separate non-UR wallet (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](https://docs.ur.app/integration-methods/pages/vKjz7ekaylj2VXHMZtAb#id-7.2-initiate-off-ramp)). UR notifies the partner via webhook. ### On-ramp (fiat to crypto) The partner fetches a quote and the user confirms. The partner submits the on-ramp request; UR debits the user's fiat balance. Crypto is credited to the user's crypto wallet: the UR-managed account or a separate 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](/developer-resources/api-reference-managed-custody-mode.md) for endpoints, request/response formats, and webhook definitions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ur.app/integration-methods/managed-custody-mode.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.