# Welcome
UR is the financial infrastructure for the open economy: manage and move stablecoins and fiat from a single account.
This site documents the UR Platform, the account layer that wallets, developers, and financial platforms build on. Through one integration, you give your users real accounts, co-branded Mastercards, and global money movement, without building the infrastructure yourself. It is written for the engineering, design, and product teams who integrate with UR.
Looking for UR's retail or corporate banking products instead? Visit [UR Support](https://support.ur.app).
### Jump right in
# What is UR?
UR is the financial infrastructure for the open economy. The UR Platform is the account layer that wallets, developers, and financial platforms build on.
A wallet stores value. An account lets you live financially.
UR is the financial infrastructure for the open economy: manage and move stablecoins and fiat from a single account. The infrastructure to turn on-chain value into a real financial life (identity, compliance, fiat rails, card, multi-currency) does not exist inside wallets. Building it yourself means banking licenses, card issuing partnerships, and years of compliance work.
The UR Platform is the account layer. It gives wallets, developers, and financial platforms the ability to offer real accounts through one integration, without building the infrastructure themselves.
## What your users get
When you integrate UR, your users receive:
* **Swiss IBAN**: a personal Swiss IBAN account in their name
* **On-chain identity (**[**URID**](/concepts/urid)**)**: a verified, portable identity issued to every user or business that has been KYCed or KYBed respectively
* [**Tokenized deposit**](/concepts/tokenized-deposits) **currencies**: EUR, USD, CHF, CNH, SGD, JPY, HKD, each backed 1:1 by fiat reserves
* **Mastercard debit card**: co-branded with your platform
* **Global bank transfers**: SEPA Instant (EUR), SWIFT (multi-currency)
* **Crypto off-ramp**: convert USDC, USDT, USDe, or ETH to fiat
* **FX conversion**: atomic burn-and-mint between currencies
## The stack
The account layer is built in four layers, each on top of the last:
| Layer | Traditional finance | UR: the account layer |
| ------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Identity** | KYC/KYB paperwork | URID, an on-chain identity issued after verification. Portable, programmable, and verifiable. |
| **Money** | Fiat held in bank accounts | Tokenized deposits on-chain, each unit backed 1:1 by real deposits. Seven currencies, all composable. |
| **Rules** | Compliance enforced by operations teams | Smart contracts. Core banking is code, not process. |
| **Data** | Records in siloed databases | Core banking and settlement is done on-chain. Transaction records are verifiable publicly. |
## Core concepts
* [URID](/concepts/urid): the on-chain identity that unlocks UR accounts
* [Tokenized deposits](/concepts/tokenized-deposits): 1:1 fiat-backed tokens on Mantle Network
* [UR Account](/concepts/ur-account): a Swiss IBAN account issued by UR's regulated entity, connected to a URID
* [On-chain ledger](/concepts/on-chain-ledger): every transaction recorded on Mantle Network
## Platforms
* Web app: [get.ur.app](https://get.ur.app)
* [iOS App Store](https://apps.apple.com/app/ur-fiat-crypto-unified/id6748420070)
* [Google Play](https://play.google.com/store/apps/details?id=com.mantle.ur)
# Partner integration flow concepts
Partner-facing concept overview. For API references and technical integration details, see docs.ur.app.
UR acts as the financial infrastructure layer for neobank partners. Partners integrate via a single REST API; UR handles KYC compliance, user account custody, and the underlying banking rails. Partners choose from a menu of modular services to build their product.
### How partners integrate with UR
Partners connect to UR as a financial infrastructure provider. UR sits between the partner's product and the global banking rails, managing identity, user accounts, and regulated financial services behind a clean API surface.
**Modular services partners can enable:**
* Multi-currency fiat balance (EUR, USD, CHF, SGD, HKD, JPY)
* Fiat Pay-in via bank transfer
* Fiat Payout via bank transfer
* Card spending via co-branded Mastercard debit
```mermaid
flowchart TD
User(["End User"]) -->|Uses| App
subgraph Partner["Partner Platform"]
App["Partner App & UX"]
Backend["Partner Backend"]
App --> Backend
end
Backend -->|REST API| UR
subgraph UR["UR: Financial Infrastructure"]
KYC["KYC & Compliance\nAll users verified by UR\nPartners may assist data collection"]
subgraph Services["Modular Financial Services (partner selects)"]
direction LR
Bal["Multi-Currency\nFiat Balance"]
PayIn["Fiat Pay-in\n(Bank Transfer)"]
PayOut["Fiat Payout\n(Bank Transfer)"]
Cards["Card Spending\n(Co-branded Mastercard)"]
end
KYC -->|"User verified: Live"| Services
end
subgraph Rails["Banking Rails (managed by UR)"]
direction LR
SEPA["SEPA · SWIFT\nGlobal Transfers"]
MC["Mastercard Network\nGlobal Acceptance"]
end
PayIn <--> SEPA
PayOut <--> SEPA
Cards <--> MC
```
**Reference docs:**
* [Fiat Pay-in (Bank Transfer)](https://docs.ur.app/concepts/deposits)
* [Fiat Payout (Bank Transfer)](https://docs.ur.app/concepts/withdrawals)
* [Core Banking Overview](https://docs.ur.app/concepts/core-banking-overview)
### Card spending: Buffer Pool model
> Suited for partners who hold significant crypto assets on behalf of their users (e.g. a crypto exchange or a neobank).
In this model, the partner pre-funds a fiat/USDC-based buffer pool held at UR. Card spending draws from this pool instantly; no per-user offramp is required at the moment of spend. The pool is replenished periodically by the partner, entirely invisible to end users.
**Phase 1: Prefund (partner-initiated)**
The partner periodically tops up their buffer pool at UR. UR maintains a minimum balance to ensure continuous card authorization capacity.
**Phase 2: Card Spend (user-initiated)**
When a user taps their card, UR routes the authorization and checks with the partner in real time. Upon approval, the spend is drawn from the buffer pool and routed through the user's linked card account.
**User experience:** Seamless; the user taps and pays. No manual conversion step required.
```mermaid
sequenceDiagram
participant Partner as Partner Platform
participant UR as UR
participant Pool as Partner Buffer Pool (held at UR)
participant MC as Mastercard Network
participant Merchant
Note over Partner, Pool: Phase 1: Prefund (automated · daily / weekly)
Partner->>UR: Sends USDC to UR buffer pool
UR-->>Pool: Credit fiat to Partner's buffer account (ops account)
Note over Pool: Minimum balance maintained for card spending capacity
Note over Partner, Merchant: Phase 2: Card Spending (user-initiated)
Merchant->>MC: Authorization request (user taps card)
MC->>UR: Route: Authorize €X for this card?
UR->>Partner: Webhook: "Approve spend for this user?"
Partner-->>UR: Approved
UR->>Pool: Debit from Partner's buffer pool
Pool-->>UR: Confirmed
UR->>UR: Fund user's linked card account
UR-->>MC: Approved
MC-->>Merchant: Transaction complete
```
### Card spending: off-ramp first
> Suited for partners where users hold their own crypto in self-custody, external wallets or for users wanting to spend non-stablecoin assets.
In this model, users must first convert their crypto to fiat before spending. Once fiat lands in their UR account, the card draws from that balance. No partner-side buffer pool is required.
**Step 1: Offramp (user-initiated)**
The user converts crypto to fiat via the partner app. UR executes the conversion at a quoted rate and credits the user's UR fiat balance.
**Step 2: Card spend**
The user taps their card. UR authorizes against the available fiat balance.
**User experience:** Users need to convert before they can spend.
```mermaid
sequenceDiagram
participant User as End User
participant Partner as Partner Platform
participant UR as UR
participant MC as Mastercard Network
participant Merchant
Note over User, UR: Step 1: Convert crypto to fiat (user-initiated)
User->>Partner: Initiate cash-out (e.g. 500 USDC)
Partner->>UR: Request conversion quote (USDC → EUR)
UR-->>Partner: Quote returned (e.g. €431 · valid 30s)
User->>Partner: Confirm
Partner->>UR: Execute conversion
UR-->>User: €431 credited to UR fiat balance
Note over User, Merchant: Step 2: Card spending (draws from fiat balance)
User->>Merchant: Tap UR co-branded card
Merchant->>MC: Authorization request
MC->>UR: Route: Authorize €50?
UR->>UR: Verify user fiat balance
UR-->>MC: Approved
MC-->>Merchant: Transaction complete
```
**Reference docs:**
* [Crypto-to-Fiat Offramp flow](https://docs.ur.app/concepts/deposits#crypto-to-fiat-conversion-offramp)
* [Card Spending flow](https://docs.ur.app/concepts/what-is-ur#the-spending-flow-from-fiat-balance-to-a-real-world-purchase)
* [External Wallet Access Mode](/integration-methods/external-wallet-access-mode)
# Quickstart
Get API credentials and start integrating with UR in minutes.
## Get access
The fastest way to start is the [API sandbox](https://partner.ur.app/api-sandbox). On your first sign-in it creates your `partnerId` and signing key, so you can begin calling UR APIs without waiting on UR. Store your private key; UR does not keep it. See [API signing key](/getting-started/integration-guide#api-signing-key) for this path and for bringing your own EVM address instead.
You also get a dedicated integration channel with the UR team for anything the sandbox does not cover, such as production configuration. Email **** to set it up.
{% hint style="info" %}
Creating your sandbox credentials is self-serve. Moving a test account to `Live` status still runs through the UR team, because testnet KYC results are mocked.
{% endhint %}
## Access the sandbox environment
UR provides a sandbox environment for integration development and testing. You generate your own credentials in the [API sandbox](https://partner.ur.app/api-sandbox); the UR team promotes test accounts to `Live` status, because testnet KYC results are mocked.
See [Sandbox environment](/getting-started/sandbox-environment) for the base URL and testnet notes.
## Authenticate your API requests
All API requests are authenticated using EIP-191 signatures. You'll sign requests with your partner wallet, and UR verifies the signature on every call.
See [Signature and Verify](https://docs.ur.app/api-reference/signature-and-verify) for how it works, including code examples.
## Next steps
* [Choose your approach](/getting-started/integration-guide): compare Managed Custody Mode and External Wallet Access Mode
* [OpenAPIs](https://docs.ur.app/api-reference): understand the API surfaces
# 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**](#account-mode) | Managed Custody Mode · External Wallet Access Mode (+ legacy Delegated Mode) | How your platform connects to UR and who signs transactions |
| [**Card Mode**](#card-mode) | Fiat Only · Crypto Backed · No card | Where card spend draws funds from |
| [**KYC Mode**](#kyc-mode) | 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.
{% hint style="info" %}
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.
{% endhint %}
## Before you start
Every integration starts with the same setup, whichever options you pick. Work through the following steps with UR once:
{% stepper %}
{% step %}
### Contact UR
Contact UR at . UR opens your dedicated integration channel, runs due diligence, and starts your onboarding.
{% endstep %}
{% step %}
### Confirm your integration options
Confirm your integration options with UR: your Account Mode, your Card Mode, your KYC Mode, and the services you want.
{% endstep %}
{% step %}
### 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](/getting-started/supported-regions).
* **Monthly limit.** Every `Live` user 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 the `monthly_limit_exceeded` webhook so you can surface it. See [Fetch UR Account information](https://docs.ur.app/api-reference#fetch-ur-account-information) and [Webhooks](/developer-resources/webhook).
Raising a user's limit is a compliance review with UR, not an API call.
{% endstep %}
{% step %}
### Generate and register your signing key
Get your signing key and `partnerId`. You have two options: create them in the [API sandbox](https://partner.ur.app/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](#api-signing-key) on this page for both paths and the full key lifecycle.
{% endstep %}
{% step %}
### Register your webhook URL
Register your webhook URL with UR so you receive events.
{% endstep %}
{% step %}
### Request sandbox access
Request sandbox access from the UR team. Integrate against sandbox before production.
{% endstep %}
{% step %}
### Go live
Confirm your production configuration with UR, then go live.
{% endstep %}
{% endstepper %}
## 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: 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) |
{% hint style="warning" %}
Delegated Mode is a legacy integration. New partners should use Managed Custody Mode or External Wallet Access Mode. See [Delegated Mode](/integration-methods/delegated-mode) for existing partners.
{% endhint %}
### 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.
| 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
{% hint style="info" %}
**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 an external (non-UR) wallet, partner-side (managed by your backend) or the user's own. The UR-managed account holds fiat only.
{% endhint %}
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
```mermaid
flowchart LR
subgraph Partner["Partner Platform"]
PB["Partner Backend"]
end
subgraph UR["UR"]
API["UR API"]
FIAT["User Fiat Account
(UR-managed)
Tokenized deposits, IBAN, Card"]
end
CRYPTO["User Crypto
(external non-UR wallet:
partner-side or user's own)"]
subgraph Settlement["Settlement"]
CHAIN["On-chain Settlement"]
end
PB -->|"API calls\n(partner signs)"| API
API --> FIAT
PB -.->|"Direct management\n(when the wallet is partner-side)"| CRYPTO
FIAT --> CHAIN
CRYPTO --> CHAIN
```
#### 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](/integration-methods/managed-custody-mode) for detailed integration steps and the [API reference](https://docs.ur.app/api-reference/account/managed-custody-mode) for endpoints.
#### Integration SOP
Beyond the common setup in [Before you start](#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.app` on BCC. The BCC is mandatory; it is UR's compliance record. See [account access authorization](/integration-methods/managed-custody-mode#account-access-authorization).
* Read the [Managed Custody Mode API reference](https://docs.ur.app/api-reference/account/managed-custody-mode) 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.
{% hint style="info" %}
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.
{% endhint %}
#### Architecture
```mermaid
flowchart LR
subgraph PartnerScope["Partner Platform"]
PFE["Partner Frontend / DApp"]
PBE["Partner Backend"]
end
subgraph UserScope["User"]
ActorUser(("User"))
UW["External Wallet"]
end
subgraph URScope["UR Backend"]
API["Partner API"]
VAL["Compliance / Risk & Quote Service"]
WH["Event Listener / Webhooks"]
end
subgraph ContractScope["UR Smart Contracts"]
SC["Token / Deposit / Router Contracts"]
CHAIN["Fiat Balance / Assets"]
end
%% Flow Logic
ActorUser -- Controls --> UW
UW -- Connects to --> PFE
%% 1. Preparation
PFE -- "1. Request Action" --> PBE
PBE -- "2. Get Quote/Params" --> API
API --> VAL
VAL -- "3. Return Tx Data" --> PBE
PBE -- "4. Pass Data" --> PFE
%% 2. Execution (The key difference: User signs & submits)
PFE -- "5. Request Signature" --> UW
UW -- "6. Sign & Submit Tx" --> SC
%% 3. Settlement
SC --> CHAIN
%% 4. Notification
SC -.-> WH
WH -. "7. Notify Status" .-> PBE
```
#### 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](/integration-methods/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](#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.
* Read the [External Wallet Access Mode API reference](https://docs.ur.app/api-reference/account/external-wallet-access-mode).
## 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.
```mermaid
sequenceDiagram
participant User as End User
participant Partner as Partner Platform
participant UR as UR
participant MC as Mastercard Network
participant Merchant
Note over User, UR: Step 1 (optional): Convert crypto to fiat
User->>Partner: Initiate off-ramp (e.g. 500 USDC)
Partner->>UR: Request conversion quote (USDC → EUR)
UR-->>Partner: Quote returned (e.g. €431 · valid 30s)
User->>Partner: Confirm
Partner->>UR: Execute conversion
UR-->>User: €431 credited to UR fiat balance
Note over User, Merchant: Step 2: Card spending (draws from UR fiat balance)
User->>Merchant: Tap UR co-branded card
Merchant->>MC: Authorization request
MC->>UR: Route: Authorize €50?
UR->>UR: Verify user fiat balance
UR-->>MC: Approved
MC-->>Merchant: Transaction complete
```
**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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3-card) or [Managed Custody Mode](https://docs.ur.app/api-reference/account/managed-custody-mode#id-11-card)).
#### Integration SOP
Fiat Only is the lightest card option to set up. The setup is the following checklist:
* Complete the [co-branded card artwork](#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](https://docs.ur.app/api-reference/account/managed-custody-mode#id-11-card) and [External Wallet Access Mode](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3-card).
### 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](https://docs.ur.app/api-reference/cards/crypto-backed-card).
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.
```mermaid
sequenceDiagram
participant Partner as Partner Platform
participant ORC as UR Off-ramp Contract
participant UR as UR
participant Pool as Prefund Account (UR Managed Fiat Account)
participant MC as Mastercard Network
participant Merchant
Note over Partner, Pool: Phase 1: Prefund (scheduled, recurring)
Partner->>ORC: Call off-ramp contract with USDC
ORC-->>Pool: Credit Prefund Account
Note over Pool: Minimum balance maintained for card spending capacity
Note over Partner, Merchant: Phase 2: Card spending (user-initiated)
Merchant->>MC: Authorization request (user taps card)
MC->>UR: Route: Authorize €X?
UR->>Partner: Webhook: "Approve? CRYPTO or FIAT?" (respond within 500 ms)
Partner-->>UR: APPROVE (settle from Prefund Account)
UR->>Pool: Book spend against Prefund Account
UR-->>MC: Approved (within 1 s window)
MC-->>Merchant: Transaction complete
UR->>Partner: Webhook: authorization.result
Partner->>Partner: Debit equivalent crypto from user's wallet
```
**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](https://docs.ur.app/api-reference/cards/crypto-backed-card) plugs into either Account Mode. Three integration surfaces: [Prefund account](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-3-prefund-account), [Card authorization callback](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-4-card-authorization-callback-ur-greater-than-partner), [Card Mode webhooks](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-5-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:
{% stepper %}
{% step %}
### Request Crypto Backed
Tell UR through your dedicated integration channel that you want Card Mode: Crypto Backed. There is no API to enable it.
{% endstep %}
{% step %}
### Complete KYB
Complete KYB (Know Your Business) with UR. UR requires KYB before it provisions your Prefund Account.
{% endstep %}
{% step %}
### UR provisions your Prefund Account
UR provisions your [Prefund Account](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-3-prefund-account). It is one account per partner, and it can hold a balance in more than one settlement currency.
{% endstep %}
{% step %}
### Agree your settlement currencies
Tell UR which settlement currencies your Prefund Account should hold. It defaults to USD. Your settlement currency affects your off-ramp pricing, so agree it before onboarding rather than after you go live.
{% endstep %}
{% step %}
### 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](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-4.1-settlement-modes).
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### Receive your Prefund Account details
UR gives you your Prefund Account details. You use the Prefund Account as the target account when you off-ramp.
{% endstep %}
{% step %}
### Register your card authorization callback URL
Register your [card authorization callback](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-4-card-authorization-callback-ur-greater-than-partner) 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.
{% endstep %}
{% step %}
### Seed and maintain the Prefund Account
At mainnet launch, call the off-ramp contract to convert USDC into your Prefund Account and seed card spending capacity. Schedule recurring off-ramps in your backend to keep the Prefund Account topped up.
{% endstep %}
{% endstepper %}
### 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](/concepts/kyc-and-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.
```mermaid
flowchart TD
Start([Choosing how KYC runs])
Q1{Already verify users in your own Sumsub tenant?}
M3[Sumsub reuse share token]
Q2{Run KYC inside your own app?}
M1[UR-hosted webview]
M2[Sumsub SDK in your app]
Start --> Q1
Q1 -- Yes --> M3
Q1 -- No --> Q2
Q2 -- No --> M1
Q2 -- Yes --> M2
style M3 fill:#f0fff4,stroke:#38a169
```
**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**
| Method | Upsides | 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](/developer-resources/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](https://developer.apple.com/app-clips/) on iOS. UR orchestrates this handoff for you.
* UR notifies you via the `kyc_status` webhook when KYC reaches `Live`.
**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](#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-token` for the user. See [Section 2.1.5 in the API reference](https://docs.ur.app/api-reference/account/external-wallet-access-mode).
* 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.
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](/concepts/kyc-and-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](#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](#kyc-data-sharing-disclosure) to the user and captures their agreement before identity verification. Your privacy notice also discloses the share to UR.
{% hint style="warning" %}
**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.
{% endhint %}
**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.
#### 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](#kyc-data-sharing-disclosure) 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](/concepts/kyc-and-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.
{% hint style="warning" %}
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.
{% endhint %}
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](https://partner.ur.app/api-sandbox) generates everything for you, so UR takes no manual action. Your `partnerId` and public address are registered the moment they are created.
{% stepper %}
{% step %}
### Sign in to the sandbox
Sign in at [partner.ur.app/api-sandbox](https://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.
{% endstep %}
{% step %}
### Store your private key
Copy your private key and store it in a secure store (HSM or KMS). UR does not store it and cannot show it again later.
{% endstep %}
{% step %}
### Start signing
Use the private key to sign your API requests. Your `partnerId` and public address are already registered, so no further setup is needed from UR.
{% endstep %}
{% endstepper %}
### 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).
{% stepper %}
{% step %}
### Generate the key pair
Generate an ECDSA key pair (an EVM wallet) on your side. Keep the private key in a secure store (HSM or KMS).
{% endstep %}
{% step %}
### Send UR the public address
Send your public EVM address to UR through your integration channel. UR registers the address and issues your `partnerId`. You never send UR the private key.
{% endstep %}
{% step %}
### Start signing
Sign your API requests with the private key. UR verifies each signature against the address you registered.
{% endstep %}
{% endstepper %}
### 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](https://docs.ur.app/api-reference/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](https://docs.ur.app/design/cards/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:
* [Managed Custody Mode integration guide](/integration-methods/managed-custody-mode)
* [External Wallet Access Mode integration guide](/integration-methods/external-wallet-access-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](https://docs.ur.app/api-reference/cards/crypto-backed-card) that plugs into either Account Mode.
For KYC details beyond integration mechanics:
* [KYC & compliance](/concepts/kyc-and-compliance) covers the full verification process, data collected, and status outcomes.
# What UR configures for you
The settings UR provisions for you out of band, and which ones you can read back through an API.
Some of your integration is controlled by the APIs you call. The rest is configured by UR when you onboard, through your dedicated integration channel, and is not exposed as a self-serve API. This page lists every setting in that second group in one place, says who decides it and how it is set, and tells you whether you can read it back through an API.
UR is a regulated financial product. The settings on this page carry compliance, custody, and settlement consequences, so UR provisions them per partner during onboarding rather than exposing them as runtime API calls. That keeps the boundary auditable on both sides.
The practical takeaway: record every option you confirm during onboarding and treat your own record as the source of truth. You can read a few of these settings back from an API (see [Reading your configuration back](#reading-your-configuration-back)); most you cannot, so do not rely on discovering them at runtime.
This page is a boundary reference. It does not repeat how each mode works; each row links to the page that owns the detail. For how to pick your options in the first place, see [Choose your integration options](/getting-started/integration-guide).
## The boundary at a glance
| You control at runtime via API | UR configures out of band |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create accounts and URIDs; create and freeze cards; set a card's default currency; pay-in, payout, FX, off-ramp; per-swipe authorization decisions (Crypto Backed) | Which Account Mode, Card Mode, and KYC Mode you run; your `partnerId` and signing key; your webhook and authorization callback URLs; Prefund Account setup and settlement rules; spending limits and regional eligibility |
## What UR configures
### Account and identity
| Setting | Who decides | When and how it is set | Readable via API? |
| ---------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| **Account Mode** (Managed Custody, External Wallet Access, legacy Delegated) | You, confirmed with UR | Fixed at onboarding; it determines which API surface and signing model you use | No. Record it yourself |
| `partnerId` | UR issues it | Created with your key in the API sandbox, or issued when you register your own address with UR; it scopes every API call | You hold it (issued to you) |
| API signing key and rotation | You hold the key; UR registers the address | Create it in the API sandbox (self-serve), or generate it yourself and register the address through your integration channel; rotate by registering a new address and deregistering the old one | You hold it |
| Webhook URL | You, registered by UR | Registered during setup; changes are coordinated with UR, with no self-serve endpoint | No |
| Sandbox access and test-to-live promotion | UR team | Requested through the UR team before production | Not applicable (environment state) |
See [Choose your integration options](/getting-started/integration-guide#account-mode) for the Account Mode comparison, [API signing key](/getting-started/integration-guide#api-signing-key) for the key lifecycle, and [API authentication](/getting-started/api-authentication) for the signing algorithm.
### Card
| Setting | Who decides | When and how it is set | Readable via API? |
| ------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- | --------------------------- |
| **Card Mode** (Fiat Only, Crypto Backed, No card) | You, confirmed with UR | Fixed at onboarding and configured onto the account by UR; there is no API to enable it | No. Record it yourself |
| Co-branded card artwork | You submit; UR approves | Submitted through your integration channel; UR reviews against Mastercard brand standards | Not applicable (submission) |
See [Card Mode](/getting-started/integration-guide#card-mode) and [Co-branded card artwork](/getting-started/integration-guide#co-branded-card-artwork). The runtime card endpoints (create card, get card info, set default currency, freeze) live in your Account Mode reference, for example [Managed Custody Mode](https://docs.ur.app/api-reference/account/managed-custody-mode#id-11-card).
### Crypto Backed card
These apply only if your Card Mode is Crypto Backed.
| Setting | Who decides | When and how it is set | Readable via API? |
| ------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| Prefund Account provisioning | UR provisions | After you complete KYB; one account per partner | Balance is readable via `GET /api/fma/v1/prefund-balance` |
| Settlement currency | You, agreed with UR | Agreed before onboarding; defaults to USD | Yes; the Prefund Balance response exposes a single `currency` |
| Settlement mode (`fixed` or `partner_controlled`) | You, agreed with UR | Chosen during onboarding | No; the Prefund Balance response does not include a `settleMode` field; record it from onboarding |
| Minimum balance | You, agreed with UR | Agreed during onboarding | Yes, as `minBalance` in the Prefund Balance response |
| Off-ramp chain and deposit currency | You, agreed with UR | Agreed during onboarding; USDC is the only deposit currency today | No |
| Card authorization callback URL | You, registered by UR | Registered during onboarding; changes are coordinated with UR, with no self-serve endpoint | No |
See the [Crypto Backed card reference](https://docs.ur.app/api-reference/cards/crypto-backed-card), the [Prefund Balance endpoint](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-3.3-get-prefund-balance), and [settlement modes](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-4.1-settlement-modes).
### KYC
| Setting | Who decides | When and how it is set | Readable via API? |
| ---------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| **KYC Mode** (UR-hosted webview, Sumsub SDK in your app, Sumsub reuse) | You, confirmed with UR | Confirmed at onboarding | No. Record it yourself |
| Sumsub reuse setup (Donor / Recipient partners, DPA) | You and UR | Configured in the Sumsub dashboard, plus a Data Processing Agreement, before the first user flows through | Not applicable (legal and dashboard setup) |
See [KYC Mode](/getting-started/integration-guide#kyc-mode) for the integration contract and [KYC & compliance](/concepts/kyc-and-compliance) for what UR verifies.
### Compliance and limits
| Setting | Who decides | When and how it is set | Readable via API? |
| ---------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Monthly spending limit | UR sets it | Set per compliance tier when the account goes Live; the default for KYC-verified users is 30,000 CHF. A higher limit requires additional verification (Enhanced Due Diligence) and is coordinated with UR | Yes, via the on-chain `limit` query and the `monthly_limit_exceeded` webhook |
| Supported regions, restricted nationalities, account eligibility | UR maintains and enforces | Enforced during the account opening flow; you do not enforce it on your side | UR enforces at account opening; the list is published |
See [Supported regions](/getting-started/supported-regions) for the country and nationality lists, [Smart contracts](https://docs.ur.app/api-reference/smart-contracts) for the on-chain `limit` query, and [Webhooks](/developer-resources/webhook) for limit events.
## Reading your configuration back
Only some of the settings above can be read back through an API. Plan your integration around that split.
**Readable via API**
* **Prefund Account state:** `GET /api/fma/v1/prefund-balance` returns the account's `currency`, `balance`, `minBalance`, `level`, and `allowance` (a single settlement currency; it does **not** return `settleMode`). Treat it as the source of truth for balance and threshold rather than hardcoding them. See the [Prefund Balance endpoint](https://docs.ur.app/api-reference/cards/crypto-backed-card#id-3.3-get-prefund-balance).
* **Spending limit:** read the on-chain `limit` query for a user (returns used and total limit and the cycle start), and subscribe to the `monthly_limit_exceeded` webhook. See [Smart contracts](https://docs.ur.app/api-reference/smart-contracts) and [Webhooks](/developer-resources/webhook).
**Not exposed; record it yourself**
Your Account Mode, your per-account Card Mode, your webhook URL, your authorization callback URL, and your KYC Mode are not returned by any API. Account and card creation calls do not echo them back. Keep your own record of what you confirmed at onboarding, and treat that record as authoritative.
## Changing a setting after go-live
Every setting on this page changes through your dedicated integration channel. There are no self-serve endpoints for them, by design, so the change stays auditable. Confirm any change with UR before you rely on it in production; for URL changes (webhook or authorization callback), the switch is paired with signature validation so events keep verifying.
## Where to read more
* [Choose your integration options](/getting-started/integration-guide) for the three decisions and their setup steps.
* [Crypto Backed card reference](https://docs.ur.app/api-reference/cards/crypto-backed-card) for Prefund, settlement modes, and the authorization callback.
* [KYC & compliance](/concepts/kyc-and-compliance) for the verification process and data collected.
* [Supported regions](/getting-started/supported-regions) for eligibility gates.
* [API authentication](/getting-started/api-authentication) for signing, and [Webhooks](/developer-resources/webhook) for events.
# Sandbox environment
The sandbox is an isolated environment for testing and development, without affecting production.
## Testnet
UR provides a sandbox environment for integration development and testing.
**Base URL:** `https://urapi2-qa.ur-inc.xyz`
{% hint style="warning" %}
**KYC data on testnet is mocked.** Identity verification results are simulated and do not reflect real compliance outcomes. After completing the KYC flow on testnet, your test users will not be automatically approved; contact **** or your dedicated integration channel to have test accounts manually moved to `Live` status.
{% endhint %}
# API authentication
How authentication works when integrating with UR APIs.
UR uses [**Ethereum Personal Sign (EIP-191)**](https://eips.ethereum.org/EIPS/eip-191) for all API authentication. While there are no API keys or OAuth tokens, the concept is fundamentally the same: you register a key with UR, sign your requests with it, and UR verifies the signature on every call.
## Registering and deregistering keys
During onboarding you get an ECDSA key pair whose public address (an Ethereum address) is registered with UR. This is your authentication credential. You have two ways to obtain it: create it in the [API sandbox](https://partner.ur.app/api-sandbox), which generates the key pair and registers it for you, or generate the key pair yourself and send UR only the public address. Either way, UR stores only the public address and never your private key. You can rotate keys by registering a new address and deregistering the old one through your dedicated integration channel. For both paths and the full lifecycle, see [API signing key](/getting-started/integration-guide#api-signing-key).
## Two authentication methods
| Method | Used for | Who signs |
| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------- |
| Partner authentication (server-to-server) | UR-OPEN-API and Webhooks | Your backend's registered key pair |
| User authentication (wallet-to-server) | UR-API (sensitive user operations like FX, transfers) | The user's wallet |
## How it works
```mermaid
flowchart LR
A[Generate key pair] --> B[Register public address with UR]
B --> C[Sign API requests with private key]
C --> D[UR verifies signature]
D --> E[Request authenticated]
```
{% hint style="info" %}
For webhook verification, the flow is reversed: UR signs the response body, and your backend verifies the signature against UR's known server address.
{% endhint %}
For the full signing logic, code examples, and environment addresses, see [Signature and Verify](https://docs.ur.app/api-reference/signature-and-verify).
# Supported regions
Countries and territories where UR accounts can be opened.
As UR provides account issuance services, we handle regulatory obligations on our end. This includes complying with AML/CFT regulations, which means we can only open accounts for users in supported countries and territories.
UR accounts are issued by a regulated entity. Users in supported regions get access to Swiss IBAN accounts, SEPA Instant (EUR), SWIFT transfers, and Mastercard spending.
## Unsupported countries and territories
UR determines account eligibility by the user's country of residence. UR cannot open accounts for users who reside in the following countries and territories:
| Code | Country or territory | Code | Country or territory |
| ---- | ------------------------------------- | ---- | -------------------------------------------- |
| AFG | Afghanistan | MAC | Macao |
| ALB | Albania | MDG | Madagascar |
| DZA | Algeria | MWI | Malawi |
| ASM | American Samoa | MDV | Maldives |
| AND | Andorra | MLI | Mali |
| AGO | Angola | MLT | Malta |
| AIA | Anguilla | MHL | Marshall Islands |
| ATA | Antarctica | MTQ | Martinique |
| ATG | Antigua and Barbuda | MRT | Mauritania |
| ARG | Argentina | MUS | Mauritius |
| ARM | Armenia | MYT | Mayotte |
| ABW | Aruba | MEX | Mexico |
| AZE | Azerbaijan | FSM | Micronesia, Federated States of |
| BHS | Bahamas | MDA | Moldova |
| BHR | Bahrain | MCO | Monaco |
| BGD | Bangladesh | MNG | Mongolia |
| BRB | Barbados | MNE | Montenegro |
| BLR | Belarus | MSR | Montserrat |
| BLZ | Belize | MAR | Morocco |
| BEN | Benin | MOZ | Mozambique |
| BMU | Bermuda | MMR | Myanmar |
| BTN | Bhutan | NAM | Namibia |
| BOL | Bolivia | NRU | Nauru |
| BES | Bonaire, Sint Eustatius and Saba | NPL | Nepal |
| BIH | Bosnia and Herzegovina | NCL | New Caledonia |
| BWA | Botswana | NIC | Nicaragua |
| BVT | Bouvet Island | NER | Niger |
| IOT | British Indian Ocean Territory | NGA | Nigeria |
| BRN | Brunei Darussalam | NIU | Niue |
| BFA | Burkina Faso | NFK | Norfolk Island |
| BDI | Burundi | PRK | North Korea |
| CPV | Cabo Verde | MKD | North Macedonia |
| KHM | Cambodia | MNP | Northern Mariana Islands |
| CMR | Cameroon | OMN | Oman |
| CYM | Cayman Islands | PAK | Pakistan |
| CAF | Central African Republic | PLW | Palau |
| TCD | Chad | PSE | Palestine, State of |
| CHL | Chile | PAN | Panama |
| CHN | China | PNG | Papua New Guinea |
| CXR | Christmas Island | PRY | Paraguay |
| CCK | Cocos (Keeling) Islands | PER | Peru |
| COL | Colombia | PHL | Philippines |
| COM | Comoros | PCN | Pitcairn |
| COG | Congo | PRI | Puerto Rico |
| COD | Congo, The Democratic Republic of the | QAT | Qatar |
| COK | Cook Islands | RUS | Russian Federation |
| CRI | Costa Rica | RWA | Rwanda |
| CUB | Cuba | BLM | Saint Barthélemy |
| CUW | Curaçao | SHN | Saint Helena, Ascension and Tristan da Cunha |
| CIV | Côte d'Ivoire | KNA | Saint Kitts and Nevis |
| DJI | Djibouti | LCA | Saint Lucia |
| DMA | Dominica | MAF | Saint Martin (French part) |
| DOM | Dominican Republic | SPM | Saint Pierre and Miquelon |
| ECU | Ecuador | VCT | Saint Vincent and the Grenadines |
| EGY | Egypt | WSM | Samoa |
| SLV | El Salvador | SMR | San Marino |
| GNQ | Equatorial Guinea | STP | Sao Tome and Principe |
| ERI | Eritrea | SAU | Saudi Arabia |
| SWZ | Eswatini | SEN | Senegal |
| ETH | Ethiopia | SRB | Serbia |
| FLK | Falkland Islands (Malvinas) | SYC | Seychelles |
| FJI | Fiji | SLE | Sierra Leone |
| GUF | French Guiana | SXM | Sint Maarten (Dutch part) |
| PYF | French Polynesia | SLB | Solomon Islands |
| ATF | French Southern Territories | SOM | Somalia |
| GAB | Gabon | ZAF | South Africa |
| GMB | Gambia | SGS | South Georgia and the South Sandwich Islands |
| GEO | Georgia | SSD | South Sudan |
| GHA | Ghana | LKA | Sri Lanka |
| GIB | Gibraltar | SDN | Sudan |
| GRL | Greenland | SUR | Suriname |
| GRD | Grenada | SYR | Syria |
| GLP | Guadeloupe | TJK | Tajikistan |
| GUM | Guam | TZA | Tanzania |
| GTM | Guatemala | THA | Thailand |
| GGY | Guernsey | TLS | Timor-Leste |
| GIN | Guinea | TGO | Togo |
| GNB | Guinea-Bissau | TKL | Tokelau |
| GUY | Guyana | TON | Tonga |
| HTI | Haiti | TTO | Trinidad and Tobago |
| HMD | Heard Island and McDonald Islands | TUN | Tunisia |
| VAT | Holy See (Vatican City State) | TKM | Turkmenistan |
| HND | Honduras | TCA | Turks and Caicos Islands |
| IND | India | TUV | Tuvalu |
| IDN | Indonesia | TUR | Türkiye |
| IRN | Iran | UGA | Uganda |
| IRQ | Iraq | UKR | Ukraine |
| IMN | Isle of Man | USA | United States |
| ISR | Israel | UMI | United States Minor Outlying Islands |
| JAM | Jamaica | URY | Uruguay |
| JEY | Jersey | UZB | Uzbekistan |
| JOR | Jordan | VUT | Vanuatu |
| KAZ | Kazakhstan | VEN | Venezuela |
| KEN | Kenya | VNM | Vietnam |
| KIR | Kiribati | VGB | Virgin Islands, British |
| KWT | Kuwait | VIR | Virgin Islands, U.S. |
| KGZ | Kyrgyzstan | WLF | Wallis and Futuna |
| LAO | Laos | ESH | Western Sahara |
| LBN | Lebanon | YEM | Yemen |
| LSO | Lesotho | ZMB | Zambia |
| LBR | Liberia | ZWE | Zimbabwe |
| LBY | Libya | | |
This list is maintained in UR's support center. If this page and the [Unsupported Countries and Territories support article](https://support.ur.app/hc/en-us/articles/16480035022991-Unsupported-Countries-and-Territories) ever differ, the support article is the authoritative source.
A small set of nationalities is also excluded regardless of country of residence; see [Restricted nationalities](#restricted-nationalities) below. UR enforces both gates during the account opening flow.
## What this means for partners
As a partner, you integrate using a `partnerId` issued by UR; the wallet holding your signing key signs requests as your credential to call UR's APIs. Partner integration does not require KYB. You get the `partnerId` either from the [API sandbox](https://partner.ur.app/api-sandbox) or by registering your own EVM address with UR; see [API signing key](/getting-started/integration-guide#api-signing-key). Your users complete KYC verification, which UR runs through your app.
Users in unsupported or sanctioned jurisdictions will not be able to open a [UR Account](/concepts/ur-account). You do not need to enforce this on your side; UR handles eligibility checks during the account opening flow.
## Restricted nationalities
Due to international regulatory requirements, UR cannot currently provide services to users with certain nationalities. If your nationality is on the restricted list, you cannot complete KYC verification even if you live in a supported country. UR currently restricts the following nationalities:
| Nationality | Code |
| ------------------------------------ | ---- |
| American Samoa | ASM |
| Guam | GUM |
| Iran | IRN |
| North Korea | PRK |
| Northern Mariana Islands | MNP |
| Puerto Rico | PRI |
| Russia | RUS |
| United States Minor Outlying Islands | UMI |
| United States of America | USA |
{% hint style="info" %}
Guam, American Samoa, Northern Mariana Islands, United States Minor Outlying Islands, Puerto Rico, and the United States are listed as separate ISO 3166-1 codes. They all fall under US nationality, which is currently restricted for KYC.
{% endhint %}
## Staying safe
{% hint style="warning" %}
**For your security.** UR contacts you only from official `@ur.app` email addresses or through in-app notifications. UR never asks for your password, private keys, or any sensitive credentials by email. If you receive a suspicious message claiming to be from UR, do not respond and contact immediately.
{% endhint %}
# 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.
```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(external non-UR wallet:\npartner-side or user's own)\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(when the wallet is partner-side)"| 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 (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](/getting-started/integration-guide#kyc-data-sharing-disclosure)). See [API reference: Managed Custody Mode](https://docs.ur.app/api-reference/account/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](https://docs.ur.app/api-reference/kyc-and-kyb/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](#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 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](https://docs.ur.app/api-reference/account/managed-custody-mode#id-7.2-initiate-off-ramp)). UR notifies the partner via webhook.
### On-ramp (fiat to crypto)
{% hint style="warning" %}
**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.
{% endhint %}
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](https://docs.ur.app/api-reference/account/managed-custody-mode) for endpoints, request/response formats, and webhook definitions.
# 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.
```mermaid
sequenceDiagram
autonumber
actor User
participant App as Partner App
participant UR as UR Backend
participant Contract as UR Contract (Mantle)
participant RegEntity as UR Regulated Entity
rect rgb(240, 248, 255)
note right of User: Phase 1: Identity Initialization (Tourist)
User->>App: Request Fiat Account (IBAN)
App->>User: Require email for registration
User->>App: Input email
App->>UR: POST /kyc/emailStatus (validate email)
note right of App: Invalid if email already exists on system User must provide different email
alt Email Valid & Available
App->>UR: POST /mint (walletAddress, email, partnerId)
note right of UR: UR validates & prepares mint transaction
UR->>Contract: Mint URID NFT (Status: Tourist)
Contract-->>UR: Tx Hash & Confirmation
UR-->>App: Return URID, Status (Tourist), Tx Hash
note right of App: Store URID locally for session
else Email Invalid or Taken
UR-->>App: Error: Email unavailable
App->>User: Display error & request new email
end
end
rect rgb(255, 250, 240)
note right of User: Phase 2: KYC Data Collection
App->>UR: POST /kyc/token (URID)
UR-->>App: Return Sumsub Token
note right of UR: Token scoped to user URID
App->>User: Launch Sumsub SDK (Face + ID Verification)
User-->>App: Complete KYC verification flow
note right of User: User submits documents directly to Sumsub
UR->>App: Webhook: /kyc/completion (URID, status)
note right of UR: Triggered when Sumsub data collection completes Does NOT mean approval: just data received
end
rect rgb(240, 255, 240)
note right of User: Phase 3: Document Signature & On-Chain Submission
UR->>App: Webhook: /kyc/signatureRequest
note right of UR: Payload contains: - Full formatted legal text (documentText) - Structured user data (documentData) - Document hash to sign - EIP-712 typed data structure
App->>User: Display Form A with formatted text + signature prompt
note right of User: User reviews legal declaration Partner must display documentText verbatim User signs with their wallet (EIP-712)
User-->>App: Return wallet signature (v, r, s)
App->>UR: POST /kyc/submit (URID, signature, documentHash)
note right of UR: UR validates: - Signature matches documentHash - Signer is URID owner - Hash hasn't been used before
UR->>RegEntity: Submit KYC package for compliance review
note right of RegEntity: Asynchronous approval process Duration: 1-5 business days typical
UR-->>App: Return 202 Accepted (pending review)
App->>User: Display "Under Review" status
end
rect rgb(230, 230, 250)
note right of User: Phase 4: Approval & Finalization
alt Regulated entity approves account
RegEntity-->>UR: Webhook: Account Approved + IBAN details
UR->>Contract: Update URID Status → Live
Contract-->>UR: Tx Hash & Confirmation
UR->>App: Webhook: /kyc/result (status: LIVE, URID)
App->>UR: GET /kyc/document (URID)
note right of UR: Returns finalized, stamped PDF
UR-->>App: Return final signed KYC PDF
App->>UR: GET /profile (URID, signature)
UR-->>App: Return account details (IBAN, account number, address)
App->>User: Display account active + IBAN details
else Regulated entity rejects account
RegEntity-->>UR: Webhook: Account Rejected + reason code
UR->>Contract: Update URID Status → Rejected
Contract-->>UR: Tx Hash & Confirmation
UR->>App: Webhook: /kyc/result (status: REJECTED, reason)
App->>User: Display rejection reason + next steps
end
end
```
**Flow Description:**
* Identity Initialization: The Partner App first[ validates the user's email availability](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-2.1.2-email-verification) and, upon success, triggers the [minting](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-2.1.4-mint-create-tokenid) 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-2.1.5-get-sumsub-sdk-token) scoped to the user's URID and launches the SDK to collect identity documents and biometric data. A [webhook notifies the Partner](/developer-resources/webhook#event-sumsub_kyc_result) when data collection is complete.
{% hint style="warning" %}
**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, email or use your dedicated integration channel to discuss alternatives.
{% endhint %}
* 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-2.1.8-get-user-kyc-document-form-a) 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-2.1.9-submit-user-signature) for compliance validation.
* Approval & Finalization: Once the asynchronous compliance review is completed, UR updates the on-chain status to "Live" and[ notifies the Partner](/developer-resources/webhook#event-kyc_status). The Partner can then [retrieve the user's profile details ](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3.1.1-get-user-profile)(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.
```mermaid
sequenceDiagram
autonumber
actor User
participant App as Partner App
participant UR as UR Backend
participant Contract as UR Contract
participant Webview as Secure Webview
rect rgb(240, 248, 255)
note right of User: Phase 1: Check Card Status
User->>App: Access Card Section
App->>UR: API: GET /card
UR-->>App: Return Card Info OR Empty/404
end
alt User has NO Card (Activation Flow)
rect rgb(255, 250, 240)
note right of User: Phase 2: Activation & Permit
User->>App: Request for a card
App->>User: Request a signature
App->>UR: API: POST /card (API request includes signature)
UR-->>App: Return Basic Card Info
App->>User: Prompt: Select Currency to Enable
User-->>App: Select Currency (e.g. USD)
App->>User: Request Offline Signature (Permit)
note right of User: User signs EIP-2612 Message (No Gas Fee)
User-->>App: Return Signature
App->>UR: API: POST /token-permit (with Signature)
note right of UR: UR pays Gas to submit authorization to chain
UR->>Contract: Execute Permit & Approve
Contract-->>UR: Success
UR-->>App: Return: Authorization Enabled
end
else User HAS Card
note right of App: Skip Activation
end
rect rgb(240, 255, 240)
note right of User: Phase 3: Display & Sensitive Data
App->>User: Show Basic Info (Masked PAN, Limit, Design)
User->>App: Click "Show Card Details"
App->>Webview: Load UR card display script
Note over Webview: PCI DSS Scope (Secure Zone)
Webview->>User: Render Full Card Details
end
```
* Status Check: The Partner App [queries the current card status](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3.1.1-get-user-profile) to determine if the user needs to activate a new card or view an existing one.
* [Activation](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3.1.2-create-card) (If applicable): If no card exists, the user initiates an activation request. This involves signing a request to create the card.
* [Set Allowance](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3.1.8-permit-token-approval): 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3.1.3-get-card-info). The response includes a `cardToken` alongside basic card details. The Partner Frontend loads UR's card display script and passes the token into [`window.fiat24card.bootstrap(...)`](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3.1.4-get-card-details) 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](https://docs.ur.app/api-reference/smart-contracts#contract-addresses) via their EVM wallet. See [§4.1 Offramp API for EVM](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-4.1.1-get-quote).
* **Solana**: the user deposits USDC via a Solana wallet. The Partner calls [§4.2 Offramp API for Solana](https://docs.ur.app/api-reference/account/external-wallet-access-mode#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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#4.2-offramp-api-for-solana) in the API Reference.
```mermaid
sequenceDiagram
autonumber
actor User
participant App as Partner App
participant UR as UR Backend
participant Contract as UR Contract
rect rgb(240, 248, 255)
note right of User: Phase 1: Quotation
User->>App: Input USDC Amount (e.g. 100 USDC)
App->>UR: POST /quote/deposit (Amount, Chain)
UR-->>App: Return Quote (Exchange Rate, Fees, Est. Fiat Output, Error code)
App-->>User: Display Estimated Fiat Received
end
rect rgb(255, 250, 240)
note right of User: Phase 2: Permit & Execution
User->>App: Confirm Transaction
App->>User: Request Wallet Signature (requires gas fee)
User->>Contract: Sign the offramp transaction
Contract-->>App: Return txHash
App-->>User: Show "Status: Pending / Processing"
end
rect rgb(240, 255, 240)
note right of User: Phase 3: Settlement
App->>Contract: Start Monitoring (Listening for Event)
alt Event Received (Within 5 mins)
Contract-->>App: Event: DepositSuccess
par Update UI
App-->>User: Show "Deposit Successful"
end
else Timeout (No Event > 5 mins)
Note right of App: Monitoring exceeded time limit
App->>UR: API: Report Timeout
UR->>Ops: 🚨 Alert: Deposit Stuck (TxHash)
Ops->>UR: Fix status
UR->>App: Fix status
end
end
```
* Quotation: The user requests a conversion amount (e.g., USDC), and the Partner frontend[ fetches a quote](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-4.1.1-get-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)
{% hint style="warning" %}
**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.
{% endhint %}
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) ](https://eips.ethereum.org/EIPS/eip-2612)authorizing the trade, which the Partner submits to onchain via API to help users to abstract gas fees from the transaction.
```mermaid
sequenceDiagram
autonumber
actor User
participant App as Partner App
participant Webview as Liveness Webview
participant UR as UR Backend
participant Contract as UR Contract
rect rgb(240, 248, 255)
note right of User: Phase 1: Quotation & Risk Check
User->>App: Input Onramp Request (e.g., 1000 EUR to ETH)
App->>UR: API: GET /quote/onramp (User, Amount)
UR->>UR: Check Risk Rules
note right of UR: 1. Monthly Quota(will failed if a TX used the limit up) 2. Min/Max Limit(Unacceptable input) 3. Liveness Status(user have to pass a check if this is true)
UR-->>App: Return Quote + Risk Flags {rate, fee, needsLiveness: T/F}
end
alt If Liveness Check Required (Risk Triggered)
rect rgb(255, 230, 230)
note right of User: Phase 1.5: Step-up Verification
App->>User: Prompt "Verification Needed"
User->>App: Confirm
App->>Webview: Initialize Liveness URL
User->>Webview: Perform Face Scan
Webview->>UR: Verify Biometrics
UR->>UR: Update User Risk Profile
UR-->>App: Webhook/Callback: Verification Success
App->>UR: GET /quote/onramp (Re-fetch)
note right of App: Refresh Quote with new permissions
UR-->>App: Return Final Quote (Allowed)
end
else Liveness Not Required
note right of App: Proceed with existing Quote
end
rect rgb(255, 250, 240)
note right of User: Phase 2: Execution (Gasless)
User->>App: Accept Quote & Confirm
App->>User: Request Offline Signature (Permit)
User-->>App: Return Signature
App->>UR: API: POST /onramp (Signature, QuoteID)
UR->>UR: Validate Sig & Quote Expiry
UR->>Contract: Execute permitOnramp()
note right of UR: UR pays Gas Fee
UR-->>App: Return txHash
end
rect rgb(240, 255, 240)
note right of User: Phase 3: Settlement
App->>Contract: Monitor txHash
alt Transaction Confirmed (Within 5 mins)
Contract-->>App: Event: Success
par Notify User
App-->>User: Show "Onramp Successful"
end
else Timeout (No Confirmation > 5 mins)
Note right of App: Monitoring exceeded limit
par User Feedback
App-->>User: Show "Status: Pending / Processing"
Note right of User: "Transaction submitted. Waiting for network confirmation."
and Escalation
App->>UR: Report Timeout Status
UR->>Ops: 🚨 Alert: Onramp Stuck (TxHash)
Note right of Ops: Re-trigger
Ops->>UR: Fixing status
UR->>App: Return the estimated processing time.
end
end
end
```
* Quotation & Risk: The Partner App requests an [onramp quote](https://docs.ur.app/api-reference/account/external-wallet-access-mode#onramp). 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#onramp) 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#onramp). 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.
```mermaid
sequenceDiagram
autonumber
actor User
participant App as Partner App
participant UR as UR Backend
participant Contract as UR Contract
rect rgb(240, 248, 255)
note right of User: Phase 1: Quotation
User->>App: Input Fiat Amount (e.g., 100 EUR24 to USD24)
App->>UR: POST /fx/quote
UR-->>App: Return Quote (rate, fee, estimated output, errors)
App-->>User: Display Estimated Output
end
rect rgb(255, 250, 240)
note right of User: Phase 2: Permit & Execution
User->>App: Confirm Transaction
App->>User: Request Wallet Signature
User-->>App: Sign permit payload
App->>UR: POST /fx-permit
UR->>Contract: Execute FX using user permit
Contract-->>UR: Return txHash
UR-->>App: Return txHash
App-->>User: Show "Status: Pending / Processing"
end
rect rgb(240, 255, 240)
note right of User: Phase 3: Status Update
alt FX Executed
UR-->>App: Webhook /webhook/fx.approved
App-->>User: Show "Status: Completed"
else FX Rejected
UR-->>App: Webhook /webhook/fx.rejected
App-->>User: Show "Status: Rejected"
end
end
```
**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. EUR and CHF transfers must come from a same-name account and use the user's default Swiss IBAN, which UR issues automatically when the user reaches `Live`. USD uses a separate USD IBAN, which UR issues only on request: call `POST /v1/apply-usd-payin` when the user wants to receive USD. The call is synchronous, and UR issues the USD IBAN immediately if the user is `Live`, with no manual review. For how UR handles USD deposits, including transfers from a third-party account, see [Deposits](/money-movement/deposits#usd-deposits-from-a-third-party-account).
## Cash pay-out (bank transfer)
This flow covers direct bank transfer payouts with recipient verification, signed authorization, and asynchronous transfer/refund webhooks.
```mermaid
sequenceDiagram
autonumber
actor User
participant App as Partner App
participant UR as UR Backend
participant Contract as UR Contract
rect rgb(240, 248, 255)
note right of User: Phase 1: Create/Select Recipient
User->>App: Select transfer currency
App->>UR: GET /banks/payout/fees
UR-->>App: Return payout fee metadata by currency
App->>UR: GET /profile (contact list)
App->>UR: GET /payment-purposes
alt Existing recipient
User->>App: Select contact + purpose + reference
App->>UR: POST /verify-reference
UR-->>App: Return refId
else New recipient
User->>App: Create new transfer
App->>UR: GET /banks
User->>App: Select recipient bank country
alt Country supports IBAN metadata
User->>App: Input IBAN
App->>UR: GET /banks/iban/{ibanNo}
UR-->>App: Return bank details
else Country requires full bank details
User->>App: Select bank and input bank account info
end
App->>UR: GET /country-cities
User->>App: Input recipient details + purpose + reference
App->>UR: POST /verify-contact (bankPaymentRequest)
UR-->>App: Return contactId, purposeId, refId
end
end
rect rgb(255, 250, 240)
note right of User: Phase 2: Permit & Transfer
User->>App: Input amount and confirm transfer
App->>User: Request wallet signature
User-->>App: Sign permit (refId, contactId, purposeId)
App->>UR: POST /payout-with-permit
UR->>Contract: Execute client payout
Contract-->>UR: Return txHash
UR-->>App: Return txHash
App-->>User: Show "Status: Pending / Processing"
end
rect rgb(240, 255, 240)
note right of User: Phase 3: Review & Status
alt Transfer approved
UR-->>App: Webhook /webhook/transfer.approved
App-->>User: Show "Funds sent"
else Transfer rejected then refunded
UR-->>App: Webhook /webhook/transfer.rejected
App-->>User: Show "Transfer failed, refunding..."
UR-->>App: Webhook /webhook/transfer.refunded
App-->>User: Show "Refund completed"
end
end
```
**Flow Description:**
* Recipient Setup: The user either [selects an existing contact or creates a new recipient](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.1-create-select-recipient).
* Create a contact:
* Get the supported bank\&country list from the [bank country API](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.1.1-get-supported-banks). 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.1.2-get-bank-by-iban) 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.1.3-get-supported-recipient-countries-and-cities), select [payout purpose](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.1.4-get-payment-purpose-list), inout address and and reference.
* All the info should be [verified by this API](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.1.6-verify-contact-bank-payment-request), 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-3.1.1-get-user-profile). 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode) 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](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.2.1-get-fees) early and uses the selected currency's `fee` and `minimalPayoutAmount` when presenting the transfer form. It then [collects a wallet signature](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.2.2-create-payout-permit-request) tied to `refId`, `contactId`, and `purposeId` before calling the [payout API](https://docs.ur.app/api-reference/account/external-wallet-access-mode#id-6.2.2-create-payout-permit-request).
* 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.
# Delegated Mode
API-driven integration where UR manages blockchain complexity on your behalf.
{% hint style="warning" %}
**Will be deprecated soon.** Delegated Mode is no longer available for new integrations. Existing partners on this mode continue to be supported. New partners should use [Managed Custody Mode](/integration-methods/managed-custody-mode), which provides the same API-driven experience without the delegation ceremony.
{% endhint %}
In Delegated Mode, your platform interacts with UR through REST APIs. Users authenticate once via the UR Webview to complete KYC and grant delegation permissions. After that, your platform can operate their UR Account via API without requiring further user wallet signatures.
This mode is designed for partners who want a Web2-style integration with minimal blockchain exposure for their users.
## User onboarding
You redirect the user to a secure UR Webview. Within this Webview, the user completes identity verification (KYC), creates their UR Account and URID, and signs an approval to delegate access to your platform. Once complete, UR redirects the user back to your app with an authorization code.
Unlike External Wallet Access Mode, the user does not sign every action with a personal wallet; they perform a one-time delegation setup here.
**Authorization Flow Diagram**
```mermaid
sequenceDiagram
participant User as User Browser
participant Partner as Partner Server
participant UR as UR Authorization Server
participant MiniDapp as UR Mini Dapp
Partner->>Partner: 1. Construct authorization URL
Partner->>User: 2. Display authorization link
User->>MiniDapp: 3. Click to visit authorization page
Note over MiniDapp: 4. Parse URL parameters (client_id, redirect_uri, scope, state)
User->>MiniDapp: 5. Complete KYC and authorization
Note over UR: 6. Generate authorization code
UR->>User: 7. Redirect to redirect_uri
Note over User: redirect_uri?code=xxx&state=xxx
User->>Partner: 8. Browser redirects to Partner
Partner->>UR: 9. Call API to exchange code for user info (with signature verification)
UR->>Partner: 10. Return user info and authorization details
Partner->>User: 11. Complete business flow
```
**Flow Description:**
* **Initialization**: The user initiates the process on the Partner App. The Partner [constructs a standard OAuth-style Authorization URL](https://docs.ur.app/api-reference/account/delegated-contract-mode#authorization-url-construction) and redirects the user to UR.
* **Onboarding** (UR Side): The user lands on the secure UR Webview and authenticates via social login (Google or Email OTP, managed by the UR account system). A UR account is automatically created along with a unique URID. The user completes the KYC process (Liveness/ID scan) directly within the UR Webview. The initial status of the URID is set to "Tourist".
* **Delegation (Critical Step):** Upon submitting KYC data for review, UR prompts the user to grant permissions to the Delegated Contract that is dedicated to the Partner. This authorization enables the Partner to execute future actions (such as offramps) via API without requiring blockchain interaction for every transaction.
* **Account creation**: UR redirects the user back to the Partner's `redirect_uri` with an Authorization Code. The Partner App [to retrieve the user's `URID`, `ETH Address`, and status](https://docs.ur.app/api-reference/account/delegated-contract-mode#partner-to-fetch-user-onboarding-information), completing the binding process.
* **Finalization**: Once KYC has been approved, the URID status will become live. Follow up functions will be then unlocked for the user.
* **KYC retry**: This step is an **exception handling mechanism** and is not part of the standard workflow. Following the initial KYC submission, UR may occasionally flag specific verification steps for retry (e.g., due to document quality issues). This status is updated dynamically via the [profile](https://docs.ur.app/api-reference/account/delegated-contract-mode#fetch-ur-account-information) API. Best Practice: We recommend performing a status check on this field before the user initiates any UR-related features. The user should be redirected to [get.ur.app](https://get.ur.app) to complete the retry process if and only if the `kycRetryVerificationLevel` field returns a non-zero value.
## Card
Once the user completes onboarding and their URID status becomes **'Live'**, they are eligible for card issuance. Critical operations, such as card activation, revealing card details (PAN/CVV), and managing card settings, are performed by redirecting the user to the **UR Card Webview**. [`Refer to this document`](https://docs.ur.app/api-reference/account/delegated-contract-mode#card) for details of integrating the Card webview integration.
## Profile
Some users may need to view their IBAN information, so we provide an integration for the **Profile Webview**. Partners can integrate this webview into their app as either a webview or a dialog. For detailed integration instructions, please refer to [`this document`](https://docs.ur.app/api-reference/account/delegated-contract-mode#profile).
## Bank transfer
For users who need to move funds between their UR account and external bank accounts, we provide an integration for the **Bank Transfer Webview**. Partners can integrate this webview into their app as either a webview or a dialog. For detailed integration instructions, please refer to [`this document`](https://docs.ur.app/api-reference/account/delegated-contract-mode#bank-transfer).
## Core banking functions
### Crypto-to-fiat (off-ramp)
```mermaid
sequenceDiagram
autonumber
actor User
participant App as Partner App
participant UR as UR Backend
participant Delegator as UR Delegator Contract
participant Chain as UR Chain
rect rgb(240, 248, 255)
note right of User: Phase 1: Quotation
User->>App: Request USDC offramp in my UR account (e.g. 100 USDC)
App->>UR: POST /quote/deposit (Amount, Chain)
UR-->>App: Return Quote (Exchange Rate, Fees, Est. Fiat Output, Error code)
App-->>User: Display Estimated Fiat Received
end
rect rgb(255, 250, 240)
note right of User: Phase 2: Permit & Execution
User->>App: Confirm Transaction
App->> Chain: Transfer USDC to User's UR account
Chain->> App: Event: Transfer confirmed
App->>UR: API: Create Offramp Request
UR->>Delegator: request offramp for the user's UR account
UR->>App: API response: TX hash
App-->>User: Show "Status: Processing"
end
rect rgb(240, 255, 240)
note right of User: Phase 3: Settlement
UR->>Delegator: Start Monitoring (Listening for Event)
alt Event Offramp Done (Within 5 mins)
Delegator->>Chain: Done the offramp and send fiat to user's UR account
Delegator-->>UR: Event: DepositSuccess
UR->>App: Webhook: Offramp final status
App-->>User: Show "Status: Success"
else Timeout (No Webhook report > 5 mins)
Note right of App: Monitoring exceeded time limit
App->>UR: API: Report Timeout
UR->>Ops: 🚨 Alert: Deposit Stuck (TxHash)
Ops->>UR: Fix status
UR->>App: Fix status
end
end
```
**Core Mechanism**
* **Quotation & Pricing**: The Partner requests a real-time exchange rate and fee structure via the [Offramp quote API](https://docs.ur.app/api-reference/account/delegated-contract-mode#fetch-offramp-quote). This ensures the user sees the exact estimated fiat output before confirming.
* **API-Driven Execution**: Once the user confirms the trade on the Partner's UI, the Partner triggers the transaction by calling the [Offramp API](https://docs.ur.app/api-reference/account/delegated-contract-mode#create-offramp-request). Critically, this step does not require a user wallet signature. The [Partner signs the API request](https://docs.ur.app/api-reference/signature-and-verify) using their [own key](https://docs.ur.app/api-reference/signature-and-verify#id-1.-generate-key-pair).
* **On-Chain Settlement**: UR's backend validates the request and triggers the Delegated Contract on the Mantle Network. The contract verifies the user's pre-authorized allowance, transfers the authorized crypto assets (e.g., USDC), and credits the user's UR account with the corresponding fiat balance (e.g., USD).
* **Asynchronous Notification**: Upon successful on-chain settlement, UR notifies the Partner via a [webhook](/developer-resources/webhook#event-transaction), allowing the Partner to update the user's UI to reflect the completed transaction.
### Fiat-to-crypto (on-ramp)
{% hint style="warning" %}
**Available soon.** On-ramp (fiat-to-crypto) is not yet available for integration and will be enabled in a future release. See [External Wallet Access Mode](/integration-methods/external-wallet-access-mode#on-ramp-flow-fiat-to-crypto) for the on-ramp implementation reference.
{% endhint %}
### Fiat-to-fiat (FX)
{% hint style="info" %}
Coming soon. See the [External Wallet Access Mode](/integration-methods/external-wallet-access-mode#fiat-to-fiat-fx) for the current FX implementation.
{% endhint %}
### Cash pay-in
{% hint style="info" %}
Coming soon. 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.
{% endhint %}
### Cash pay-out (bank transfer)
{% hint style="info" %}
Coming soon. See the [External Wallet Access Mode](/integration-methods/external-wallet-access-mode#cash-pay-out-bank-transfer) for the current bank transfer implementation.
{% endhint %}
# Core banking overview
An overview of money movement on UR.
This guide provides a high-level overview of the core products that power all money movement on the UR platform. These modules are the engine that connects your platform to the global banking system and creates a seamless, closed-loop financial ecosystem for your users.
You can use these products individually or combine them to create sophisticated applications, from simple "cash-out" features to a fully embedded banking experience.
#### Key capabilities
The core banking suite is built on two primary pillars:
* **Fiat money movement:** Moving fiat (e.g., EUR, CHF) between a user's UR account and the traditional banking system.
* **Asset conversions:** Instantly converting assets between crypto (held on your platform) and fiat (held in the user's UR account).
### Fiat money movement (bank transfers)
This pillar connects your user's account to the traditional banking world, allowing them to move funds to and from any external bank account. These features are generally reserved for fully verified, `Live` status users.
#### Fiat deposits (external)
* **What it is:** This flow allows a user to fund their UR account by sending a bank transfer *from* an external source (e.g., their salary, another bank account).
* **How it works:** After a user is fully verified (`Live`), you can call our API to retrieve their personal Swiss IBAN. The user then uses this IBAN to send a SEPA or SWIFT transfer. When the funds arrive, we send you a `payment.received` webhook so you can update their balance in your app.
* **Use case:** Enabling users to "cash in" to the ecosystem or receive payments from third parties.
#### Fiat payouts (external)
* **What it is:** This flow allows a user to withdraw fiat from their UR account and send it *to* an external bank account.
* **How it works:** This is a high-security action. Your platform initiates the request, and we provide a secure webview for the user to authenticate (via Email/SSO) and authorize the on-chain transfer. This provides a seamless UX while ensuring the user is the only one who can move their money out.
* **Use case:** Enabling users to "cash out" to the traditional financial world, such as sending funds to their primary bank or paying a bill.
### Asset conversions (on/off-ramps)
This pillar creates a powerful, "closed-loop" economy *within* your platform. It allows users to move seamlessly between their crypto assets (managed by you) and their new fiat balance (managed by UR), all without the friction of external bank transfers.
#### Crypto-to-fiat (off-ramp)
* **What it is:** This is the core "cash out" flow. It allows a user to sell crypto from their balance on your platform and instantly receive fiat in their UR account.
* **How it works:** Your platform requests a quote, the user confirms, and you execute the trade. Our backend performs an atomic settlement: depending on integration mode, UR debits crypto from either the user's wallet (External Wallet Access Mode) or the partner's corporate omnibus account (Managed Custody Mode), and simultaneously credits the corresponding fiat to the end-user's personal UR account.
* **Use case:** This is the primary feature for `Tourist` users, allowing them to off-ramp and see immediate value before completing full KYC.
#### Fiat-to-crypto (on-ramp)
{% hint style="warning" %}
**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.
{% endhint %}
* **What it is:** This is the "closed-loop" on-ramp. It allows a user to buy crypto from you by *using the fiat balance they already hold* in their UR account.
* **How it works:** The user confirms a quote, and your platform calls our API to execute an instant, internal fiat transfer from the user's account to your corporate omnibus account. Once you receive our "success" webhook, you can release the crypto to the user's wallet.
* **Use case:** Creating a frictionless experience, increasing your platform's volume and user engagement by removing the wait time for bank transfers.
### FX (fiat-to-fiat)
Users can convert between fiat currencies they hold (e.g., USD to EUR). UR executes an atomic burn-and-mint operation on-chain, burning one tokenized deposit and minting another in a single transaction.
See [FX conversion](/money-movement/fx) for the detailed flow.
### Internal transfers (P2P)
Instant fiat transfers between two UR users. Because balances are [tokenized deposits](/concepts/tokenized-deposits) on Mantle Network, transfers settle in milliseconds.
### Card programs
Issue co-branded Mastercard debit cards for users to spend their fiat balance. Settlement happens atomically on-chain at point of sale.
See [Tokenized deposits: spending flow](/concepts/tokenized-deposits#the-spending-flow-from-fiat-balance-to-a-real-world-purchase) for how card spending works under the hood.
# Deposits
Fiat bank transfers and crypto-to-fiat offramp flows.
### Fiat deposit via bank transfer
{% hint style="info" %}
This flow also applies to UR Peer Transfers: fiat transfers between 2 `Live` UR accounts.
{% endhint %}
This flow enables a fully verified (`Live`) user to fund their UR account from an external, third-party bank account (e.g., their primary bank).
{% hint style="info" %}
EUR and CHF deposits must come from a bank account in the user's own name (same-name). USD deposits may also come from a third-party account, with additional review; see [USD deposits from a third-party account](#usd-deposits-from-a-third-party-account).
{% endhint %}
Flow
Details
Responsibility of
Prerequisite: User is Live
The user's status must be Live to access this feature. Your UI should only show the "Deposit" option to Live users.
Partner
User Clicks "Deposit"
The user selects "Deposit" and chooses "Bank Transfer" from within your app.
Partner
Partner Fetches Account Details
Your backend, which must be authorized, calls UR's API to retrieve the user's personal bank account details (IBAN, BIC, Bank Name).
Partner
Partner Displays Account Details
Your app's frontend displays the user's unique IBAN and transfer instructions (e.g., "Only send EUR or CHF to this account").
Partner
User Initiates External Transfer
The user leaves your app, logs into their external bank app (e.g., UBS, Revolut), and initiates a SEPA/SWIFT transfer to the IBAN provided.
User
UR Receives Funds & Notifies Partner
When the funds arrive (hours or days later), UR's banking core identifies the receiving IBAN, credits the user's account balance, and sends a payment.received webhook to your backend.
Alternatively, you may monitor on-chain transactions specific to said user.
UR -> Partner
Partner Updates User
Your backend receives the webhook, verifies the details, and updates the user's balance in your system.
You should send a push notification or in-app update to inform the user (e.g., "Your €100.00 deposit has arrived.").
Partner
{% hint style="warning" %}
**EUR and CHF use the default IBAN; USD uses a separate one on request.** When a user reaches `Live`, UR automatically issues a personal Swiss IBAN for **EUR and CHF** transfers. UR does not issue a **USD IBAN** by default; you request one when the user wants to receive USD. The EUR/CHF IBAN does not receive USD; show the USD IBAN for USD transfers.
The EUR/CHF IBAN is ready as soon as the user is `Live`, with no request and no prerequisite pay-in. To get the user a USD IBAN, call `POST /v1/apply-usd-payin`. The call is synchronous: if the user is `Live`, UR creates the USD IBAN and returns success, with no manual review and no prior EUR or CHF pay-in required. After a successful call, the USD IBAN appears under the `USD` key of `depositBank` in the user profile; read it from there before showing it to the user. USD deposits from an account not in the user's own name are subject to additional review (see [USD deposits from a third-party account](#usd-deposits-from-a-third-party-account)).
Fetch deposit details from the BR profile (`GET /api/fma/v1/br`), where `depositBank` is keyed by currency. Show the user the IBAN whose currency matches the transfer they will send. Do not show the EUR/CHF IBAN for a USD transfer, or the USD IBAN for a EUR or CHF transfer.
{% endhint %}
```mermaid
sequenceDiagram
participant User (on Partner App)
participant Partner (Frontend)
participant Partner (Backend)
participant UR (Backend)
participant User (at External Bank)
participant UR (Banking Core)
Note over User (on Partner App), UR (Banking Core): Prerequisite: User status is "Live"
User (on Partner App)->>Partner (Frontend): 1. Clicks "Deposit"
Partner (Frontend)->>Partner (Backend): 2. Request Account Details
Partner (Backend)->>UR (Backend): 3. GET /v1/users/{id}/accounts (using auth_token)
UR (Backend)-->>Partner (Backend): 4. Return {"iban": "CH...", "bic": "...", ...}
Partner (Backend)-->>Partner (Frontend): 5. Send Account Details
Partner (Frontend)->>User (on Partner App): 6. Display IBAN & Bank Details
User (on Partner App)-->>User (at External Bank): 7. (User goes to their other bank's app)
User (at External Bank)->>UR (Banking Core): 8. Initiates SEPA/SWIFT transfer
Note over User (at External Bank), UR (Banking Core): ...Hours or days later...
UR (Banking Core)->>UR (Backend): 9. Funds received for user's IBAN
UR (Backend)->>UR (Backend): 10. Credit User's Account Balance
UR (Backend)->>Partner (Backend): 11. Webhook: payment.received (amount, currency, user_id)
Partner (Backend)-->>Partner (Frontend): 12. Update UI (e.g., via WebSocket)
Partner (Frontend)->>User (on Partner App): 13. Show "Deposit Received" & Updated Balance
```
### USD deposits from a third-party account
UR screens inbound USD by who sent it:
* **Same-name sender:** the deposit comes from an account in the user's own name. UR credits it to the user's UR account with no hold.
* **Any other sender:** UR holds the deposit for up to 7 days for review. On release, UR deducts a fixed **USD 50** fee and credits the remainder to the user's UR account; UR does not return the funds to the sending bank. If the review does not pass, UR does not release the funds.
This review applies to USD only; EUR and CHF deposits must always come from a same-name account. Tell your users to send USD from an account in their own name to avoid the hold and the fee.
### Crypto-to-fiat conversion (off-ramp)
Flow
Details
Responsibility of
1. Initiate Off-ramp
The user taps "Cash Out" for 1 ETH on your app.
Partner
2. Internal Debit
Your backend deducts 1 ETH from the user's custodial balance.
Partner
3. Request Quote
Your backend calls the liquidity provider API to request a real-time conversion quote for 1 ETH to EUR.
Partner
4. Source Liquidity
The liquidity provider API gets a live, executable price.
UR / Partner
5. Provide Quote
The liquidity provider API returns a firm, time-limited quote (e.g., "€1900.00, valid for 30s") to your backend.
UR -> Partner
6. Confirm Quote
Your frontend displays the quote, and the user taps "Confirm."
Partner
7. Execute Trade
Your backend calls the liquidity provider API with the unique quote_id to execute the trade.
Partner
8. Settle Trade
UR performs an atomic sequence:a. Debits 1 ETH from Partner's corporate crypto account.b. Sells 1 ETH via the liquidity provider.c. Credits the resulting €1900.00 to the end-user's UR account.
UR
9. Notify User
UR sends a payment.received webhook. Your backend updates the user's UI and sends a push notification.
UR -> Partner -> User
```mermaid
sequenceDiagram
participant User on Partner Platform
participant Partner Platform Backend
participant UR API
participant Liquidity Provider API
User on Partner Platform->> Partner Platform Backend: 1. Initiates "Cash Out" (e.g., 1,000 USDC)
activate Partner Platform Backend
Partner Platform Backend->> Partner Platform Backend: 2. Debits User's Custodial Balance
Partner Platform Backend->>UR API: 3. Requests Quote for 1,000 USDC -> EUR
activate UR API
UR API->>Liquidity Provider API: 4. Gets Live Price
activate Liquidity Provider API
Liquidity Provider API-->>UR API: 5. Returns Price
deactivate Liquidity Provider API
UR API-->> Partner Platform Backend: 6. Returns Firm Quote (Expires in 30s)
deactivate UR API
deactivate Partner Platform Backend
User on Partner Platform->> Partner Platform Backend: 7. Confirms Quote in UI
activate Partner Platform Backend
Partner Platform Backend->>UR API: 8. Executes Trade with Quote ID
activate UR API
note right of UR API: 9. Executes Atomic Sequence
UR API->>UR API: a) Debits Partner Platform's USDC Acct
UR API->>Liquidity Provider API: b) Sells USDC for EUR
UR API->>UR API: c) Credits User's UR EUR Acct
UR API-->>User on Partner Platform: 10. Sends Notification: "€863.00 deposited"
deactivate UR API
deactivate Partner Platform Backend
```
# Withdrawals
Bank payouts and fiat-to-crypto onramp flows.
### Fiat payout
{% hint style="info" %}
This flow also applies to UR Peer Transfers: fiat transfers between 2 `Live` UR accounts.
{% endhint %}
This flow enables a fully verified (`Live`) user to send funds from their UR account to an external bank account. This is a high-security action that requires the user to authenticate and sign the transaction.
Flow
Details
Responsibility of
1. Prerequisite
The user's status must be Live.
Partner
2. Initiate Payout
The user clicks "Withdraw" or "Send to Bank" from within your app.
Partner
3. Request Payout URL
Your backend calls GET /v1/payouts/url to get a one-time URL for the UR Payout Webview.
Partner
4. Open Payout Webview
Your app opens the UR Payout Webview with the URL provided by UR.
Partner
5. User Authenticates
Inside the UR Webview, the user must re-authenticate (via Email/Google SSO) to securely access their private key.
UR
6. Complete & Confirm
The user fills in the payout details (amount, destination IBAN, reference) and confirms the transaction.
UR
7. Authorize & Process
The user's confirmation, combined with their authentication, authorizes UR's backend to execute the on-chain payout.
UR
8. Notify Partner
UR's backend executes the on-chain payout, and the funds are sent. UR sends a payment.sent webhook to your backend.
UR -> Partner
9. Update User
Your backend receives the webhook and updates the user's balance and transaction history in your app.
Partner
```mermaid
sequenceDiagram
participant User (on Partner App)
participant Partner (Frontend)
participant Partner (Backend)
participant UR (Webview - Payout)
participant UR (Backend)
participant UR (Embedded Wallet)
participant UR (Banking Core)
Note over User (on Partner App), UR (Banking Core): Prerequisite: User status is "Live"
User (on Partner App)->>Partner (Frontend): 1. Clicks "Withdraw"
Partner (Frontend)->>Partner (Backend): 2. Request Payout URL
Partner (Backend)->>UR (Backend): 3. GET /v1/payouts/url
UR (Backend)-->>Partner (Backend): 4. Return one-time Payout URL
Partner (Backend)-->>Partner (Frontend): 5. Send URL
Partner (Frontend)->>User (on Partner App): 6. Open UR Payout Webview
User (on Partner App)->>UR (Webview - Payout): 7. Authenticate (Email/Google SSO)
UR (Webview - Payout)->>UR (Embedded Wallet): 8. Securely unlock private key
User (on Partner App)->>UR (Webview - Payout): 9. Enters Payout Details (Amount, IBAN)
UR (Webview - Payout)->>User (on Partner App): 10. Show Confirmation Screen
User (on Partner App)->>UR (Webview - Payout): 11. Clicks "Confirm & Send"
UR (Webview - Payout)->>UR (Backend): 12. Submit Payout Request
note right of UR (Backend): 13. User's auth (Step 7) authorizes this
UR (Backend)->>UR (Embedded Wallet): 14. Generate Signed Transaction
UR (Embedded Wallet)-->>UR (Backend): 15. Return Signed Tx
UR (Backend)->>UR (Banking Core): 16. Execute SEPA/SWIFT Transfer (submits tx)
UR (Banking Core)-->>UR (Backend): 17. Payout Successful
UR (Backend)->>Partner (Backend): 18. Webhook: payment.sent (user_id, amount)
Partner (Backend)-->>Partner (Frontend): 19. Update UI (e.g., via WebSocket)
Partner (Frontend)->>User (on Partner App): 20. Show "Withdrawal Sent" & Updated Balance
```
### Fiat-to-crypto conversion (on-ramp)
{% hint style="warning" %}
**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.
{% endhint %}
{% hint style="info" %}
This flow allows a user to instantly purchase crypto from your platform using the fiat balance held in their UR account.
{% endhint %}
**Scenario:** A user has $1,000 in their embedded UR account and wants to on-ramp $500 to buy USDC.
Flow
Details
Responsibility of
1. Initiate On-Ramp
The user goes to the "Buy Crypto" section and chooses to pay using their available fiat balance in the embedded UR account.
Partner
2. Confirm Transaction
Partner's trading engine provides a real-time quote for the crypto purchase. The user confirms the amount.
Partner
3. Instant Fiat Settlement
Partner execute an internal transfer of $500 from the user's individual UR account to Partner's corporate UR account, enabled by the Transfer Assets flow. The settlement is instant.
Partner -> UR
4. Crypto Delivery
Upon confirmation of the instant fiat settlement, Partner's trading engine is triggered to purchase the crypto and deliver it to the user's connected wallet.
Partner
```mermaid
sequenceDiagram
participant User
participant Partner
participant UR
User->>Partner: 1. Initiate On-Ramp (e.g., $500 to USDC)
Note over User, Partner: User selects their existing fiat balance as the payment source.
Partner ->>Partner : 2. Get Crypto Quote & User Confirms
Partner ->>UR: 3. Call `Payments API` (Debit $500 from the User)
UR ->>UR: 4. Settle Fiat Instantly (Internal Transfer)
UR -->>Partner: 5. Fiat Settlement Confirmed
Partner ->>Partner: 6. Execute Crypto Purchase
Partner -->>User: 7. Deliver Crypto to User's Wallet
```
# FX conversion
Convert between currencies using atomic burn-and-mint operations.
{% hint style="warning" %}
Detailed integration guides for FX will be added as the Managed Custody Mode FX API becomes available.
{% endhint %}
## What this will cover
* How FX conversion works (atomic burn-and-mint on Mantle Network)
* Supported currency pairs across 7 tokenized deposit currencies
* Rate calculation and fees
* Step-by-step integration guide with code samples
{% hint style="info" %}
FX is already available for **External Wallet Access Mode** integrations. See the [External Wallet Access Mode FX flow](/integration-methods/external-wallet-access-mode#fiat-to-fiat-fx) for the current implementation with sequence diagrams.
{% endhint %}
## How FX works
Users can instantly convert between fiat currencies they hold (e.g., USD to EUR). Behind the scenes, UR executes an atomic burn-and-mint operation on the user's tokenized deposits.
```mermaid
sequenceDiagram
participant U as User
participant App as UR App
participant UR as UR (System)
participant MN as Mantle Network
U->>App: 1. Taps 'Convert'
activate App
U->>App: 2. Enters "100 USD to EUR"
App->>UR: 3. Request FX Quote (USD/EUR)
activate UR
UR-->>App: 4. Provide Live Rate (e.g., 1 USD = 0.92 EUR)
App->>U: 5. Display Quote: "Convert 100 USD to ~92.00 EUR?"
U->>App: 6. Confirms Conversion
App->>UR: 7. Execute Confirmed FX Trade
UR-->>MN: 8. Initiate Atomic Swap
activate MN
Note over UR, MN: The following is a single atomic transaction
UR->>MN: 8a. BURN 100 USD24 from User's Wallet
UR->>MN: 8b. MINT 92.00 EUR24 to User's Wallet
MN-->>UR: 9. Transaction Confirmed
deactivate MN
UR-->>App: 10. Conversion Successful
deactivate UR
App->>U: 11. Show success screen & updated balances
deactivate App
```
# Transfer assets to partner platform
Move funds between user UR accounts and your platform.
If the user has granted write access to the Partner, the Partner will be able to allow users to natively trigger transfers (e.g. "Transfer from UR to \ account") natively within the partner's UI.
Use case: When users want to transfer fiat from their UR account to their custodial fiat balance within the Partner's platform.
# URID
The on-chain identity that unlocks UR accounts.
The URID is UR's on-chain identity system. Think of it as a user ID, but represented as an NFT on Mantle Network. Every user and corporate entity that passes KYC/KYB verification receives a URID minted to their wallet address.
## What a URID does
A URID binds a verified real-world identity to an on-chain address. It links together:
| Component | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| Compliance status | KYC/KYB verification result, so the system knows this address belongs to a verified person or entity |
| Account permissions | What the holder can do (e.g., transact, hold specific currencies, grant write access to partners) |
| IBAN assignment | The personal Swiss IBAN associated with this identity |
| Partner relationships | Which platforms have been granted delegated access |
A valid URID is required before a user can access any UR Account functionality, including deposits, withdrawals, card spending, and FX conversions.
## Corporate vs personal URIDs
| Type | Issued after | Purpose |
| -------------- | ------------ | --------------------------------------------------------------------------------------------------- |
| Personal URID | KYC | Unlocks the user's [UR Account](/concepts/ur-account) |
| Corporate URID | KYB | Required for managing fund flows between your platform and funds on UR held on behalf of your users |
## Key properties
| Property | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| Non-transferable | A URID is soulbound to the wallet it was minted to. It cannot be sold or moved. |
| Revocable | If compliance status changes, the URID can be deactivated, immediately freezing account access. |
| On-chain verifiability | Any smart contract can check whether an address holds a valid URID before executing a transaction. |
# UR Account
A hybrid financial account bridging the regulated financial system with on-chain settlement.
The UR Account is a hybrid financial infrastructure that bridges the regulated financial system (via UR's regulated entity) with Web3 settlement rails. It functions as the user's regulated fiat account linked to an active [URID](/concepts/urid).
Fiat balances are issued as [tokenized deposits](/concepts/tokenized-deposits) (e.g., USD24, EUR24) on Mantle Network, backed 1:1 by fiat reserves held by UR's regulated entity. This architecture provides users with a fully compliant account interface (including personal Swiss IBANs and Mastercard debit card capabilities) while enabling instant, atomic on-chain settlement for crypto-to-fiat conversions, card spending, and cross-border transfers.
## How a UR Account holds assets
Every UR Account is backed by an on-chain wallet address on Mantle Network. Tokenized deposits (e.g., USD24, EUR24) are ERC-20 tokens held at this address.
How assets are split depends on the integration mode:
* **Managed Custody Mode**: UR manages the user's fiat account (tokenized deposits, IBAN, card). The UR-managed account holds fiat only; the user's crypto is always held in a separate external (non-UR) wallet (partner-side or the user's own). Crypto enters the UR Account only via off-ramp, which credits fiat.
* **External Wallet Access Mode**: Both fiat (tokenized deposits) and crypto live in the user's single external wallet. The UR Account and the user's wallet are the same address.
* **Delegated Mode**: Similar to Managed Custody Mode; UR manages the wallet via delegated smart contracts. The user performs a one-time delegation during onboarding.
{% hint style="warning" %}
Delegated Mode will be deprecated soon and is being replaced by Managed Custody Mode. New partners should use Managed Custody Mode or External Wallet Access Mode.
{% endhint %}
In all three modes, the UR Account provides a regulated Swiss IBAN account issued by UR's regulated entity (for fiat rails, IBAN, and card), with on-chain settlement for all operations.
## What a UR Account includes
* **Personal Swiss IBAN**: receive SEPA Instant and SWIFT transfers directly
* **Multi-currency balances**: hold EUR, USD, CHF, CNH, SGD, JPY, and HKD as tokenized deposits
* **Mastercard debit card**: spend fiat balances anywhere Mastercard is accepted; settlement happens on-chain in milliseconds
* **Instant FX**: convert between supported currencies atomically (burn one token, mint another in a single transaction)
* **On-chain transparency**: balances and transactions are recorded on Mantle Network, fully auditable
## Account structure by integration mode
How the account is provisioned depends on how your platform integrates with UR:
* [**Managed Custody Mode**](/integration-methods/managed-custody-mode) (recommended): UR manages a fiat account per user (tokenized deposits, IBAN, card). The UR-managed account holds fiat only; the user's crypto is always held in a separate external (non-UR) wallet (partner-side or the user's own). The partner backend orchestrates all fiat actions via API.
* [**External Wallet Access Mode**](/integration-methods/external-wallet-access-mode): Users connect their own wallet (e.g., MetaMask, SafePal). The URID is minted directly to their address, and they interact with UR through your UI or directly on-chain.
* [**Delegated Mode**](/integration-methods/delegated-mode): Legacy API-driven integration via delegated smart contracts. Existing partners on this mode continue to be supported, but the mode will be deprecated soon (see the note above).
# Tokenized deposits
1:1 fiat-backed tokens on Mantle Network.
The core that powers UR is the concept of tokenized deposits. A tokenized deposit is a one-to-one, fully-backed digital representation of fiat money held by UR's regulated entity, recorded on the Mantle Network.
For example, when a user holds 100 USD24 tokens in their UR wallet, they have a legal claim to $100 USD. The token is not a stablecoin or a synthetic asset. It is a deposit receipt issued by UR's regulated entity: a direct, one-to-one claim on fiat that the entity holds in full reserve.
## Why tokenize deposits?
Representing fiat balances as on-chain tokens unlocks capabilities that traditional banking infrastructure cannot offer:
* **Instant settlement**: transfers, FX conversions, and card spending settle in milliseconds, not days. When a user taps their Mastercard, UR burns the corresponding tokens and approves the transaction atomically.
* **Atomic operations**: FX conversion is a single on-chain transaction (burn one currency token, mint another). No intermediary holding accounts, no T+1 settlement.
* **Composability**: because balances are standard tokens on Mantle Network, they can interact with smart contracts, enabling programmable finance (e.g., automated savings, partner-triggered pull payments).
* **Transparency**: balances and transaction history are on-chain and auditable. No reconciliation lag between what the user sees and what the system records.
## Supported currencies
UR issues tokenized deposits in seven currencies:
| Token | Currency |
| ----- | ----------------------- |
| EUR24 | Euro |
| USD24 | US Dollar |
| CHF24 | Swiss Franc |
| CNH24 | Chinese Yuan (offshore) |
| SGD24 | Singapore Dollar |
| JPY24 | Japanese Yen |
| HKD24 | Hong Kong Dollar |
Each token is minted when fiat is deposited and burned when fiat is withdrawn. The token is not backed by a separate reserve; it *is* the deposit, a direct liability on the issuing entity's balance sheet.
## User experience
On the UI, tokenized deposits are displayed as fiat balances. Users see "€100.00" rather than "100 EUR24". The on-chain mechanics are invisible unless the user chooses to inspect their wallet directly.
## The off-ramping flow: from crypto to fiat balance
This is the process of a user converting their digital assets (e.g., USDC) into spendable fiat balance in UR.
## The spending flow: from fiat balance to a real-world purchase
This is how a user spends their tokenized deposit balance using the UR Mastercard. UR instantly burns the corresponding tokens and approves the transaction, and we manage the settlement with Mastercard rails later on.
```mermaid
sequenceDiagram
participant C as Cardholder
participant M as Merchant POS
participant AB as Acquiring Bank
participant MC as Mastercard Network
participant UR as UR
participant MN as Mantle Network
C->>M: 1. Taps UR Mastercard to pay $50
activate M
M->>AB: 2. Authorization Request
activate AB
AB->>MC: 3. Forward Request
activate MC
MC->>UR: 4. Route Request: "Authorize $50 for Card XYZ?"
activate UR
UR->>MN: 5. Query Balance of User's Wallet
activate MN
MN-->>UR: 6. Return Balance (e.g., 1000 USD24)
deactivate MN
UR-->>UR: 7. Verify Funds & Perform Fraud Checks
alt Sufficient Funds & Checks Pass
UR->>MN: 8. Instruct: "BURN 50 USD24 from User's Wallet"
activate MN
MN-->>UR: 9. Burn Confirmed. New Balance: 950 USD24
deactivate MN
UR-->>MC: 10. Send Response: APPROVED
else Insufficient Funds or Fraud Flag
UR-->>MC: 10. Send Response: DECLINED
end
deactivate UR
MC-->>AB: 11. Forward Response
deactivate MC
AB-->>M: 12. Send Final Response
deactivate AB
M-->>C: 13. Transaction Result
deactivate M
Note right of M: Displays "Approved" / "Declined" on screen
```
# On-chain ledger
How UR records every transaction on Mantle Network, and why it matters for partners.
Every UR transaction (deposits, withdrawals, FX conversions, card spending, transfers) is recorded on the Mantle Network. This on-chain ledger is UR's core infrastructure layer: it replaces the traditional bank ledger with a transparent, real-time, programmable record of all account activity.
## How it works
When a user performs any financial action in UR, the system executes it as an on-chain transaction:
* **Deposit**: fiat arrives via SEPA/SWIFT → UR mints the corresponding tokenized deposit (e.g., 100 EUR24) to the user's wallet
* **Withdrawal**: UR burns the tokens → fiat is sent out via SEPA/SWIFT
* **FX conversion**: burn one currency token, mint another in a single atomic transaction
* **Card spend**: burn tokens instantly at point of sale, settle with Mastercard later
* **Transfer**: move tokens between wallets on-chain
Each operation is a verifiable, immutable record on Mantle Network.
## Comparison to traditional bank ledgers
Traditional banks maintain internal databases that only they can read. Reconciliation between systems (bank, card processor, partner) takes hours or days, and discrepancies are common.
| | Traditional bank ledger | UR on-chain ledger |
| ------------------- | ------------------------- | ----------------------------------- |
| **Visibility** | Bank-internal only | Public, auditable by anyone |
| **Settlement** | T+1 to T+3 | Instant (block confirmation) |
| **Reconciliation** | Manual, periodic batches | Unnecessary; single source of truth |
| **Auditability** | Requires bank cooperation | Read directly from chain |
| **Programmability** | None | Smart contract composability |
## Reading on-chain state
Partners can query the Mantle Network directly to:
| Action | What you can do |
| ------------------------ | ----------------------------------------------------------------- |
| **Verify balances** | Read token balances for any UR wallet without calling the UR API |
| **Monitor transactions** | Subscribe to on-chain events for real-time notifications |
| **Build reports** | Pull historical transaction data for compliance or reconciliation |
| **Audit** | Independently verify that user balances match expected state |
This works with any EVM-compatible tooling (ethers.js, viem, Foundry, block explorers).
## Why this matters
The on-chain ledger is UR's key differentiator:
| Benefit | Detail |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **No reconciliation lag** | What the user sees, what the partner queries, and what the regulator audits is the same data, in real time |
| **Partner independence** | You don't need to trust UR's reporting; you can verify on-chain |
| **Composability** | Balances are standard ERC-20 tokens. Partners can build programmable finance on top (automated sweeps, conditional payments, DeFi integrations) |
| **Regulatory transparency** | Regulators can audit the ledger directly, reducing compliance overhead for everyone in the chain |
# The user lifecycle
The URID account states and how a single KYC flow moves a user from Tourist to Live.
To access the full range of core banking operations, a user must hold a [URID](/concepts/urid) in the `Live` state. Onboarding is a single KYC flow that takes a newly minted URID from `Tourist` (minted, before KYC) to `Live` (KYC passed). This page describes the account states, how a user moves between them, and what your platform is responsible for along the way.
For what UR verifies during KYC and the methods it uses (questionnaire, proof of address, NFC scan, liveness, AML screening), see [KYC & compliance](/concepts/kyc-and-compliance).
## User states
Every URID carries an on-chain account status, and that status controls what the user can do. The values are the `AccountStatusV2` enum; for the on-chain mapping, see [Smart contracts](https://docs.ur.app/api-reference/smart-contracts). The states are the following:
| Status | Value | How the user reaches it | What the user can do |
| ------------- | ----- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `Na` | 0 | New user; URID not yet minted | Nothing yet |
| `Tourist` | 2 | URID is minted, before KYC | Receive partner off-ramp and inbound P2P (up to 250 USD/EUR); cannot move funds externally, hold an IBAN, or send |
| `Live` | 5 | Completes KYC and passes compliance review | All banking features: external deposits (IBAN), external payouts, send and receive P2P, FX, card |
| `SoftBlocked` | 1 | An ongoing task (CRS, ongoing KYC, or EDD) passed its deadline | Money features locked until the open task is completed; recoverable to `Live` |
| `Blocked` | 3 | A compliance action freezes the account | Account frozen |
| `Closed` | 4 | The account is closed | Terminal; no access |
{% hint style="info" %}
`Tourist` is not a KYC stage the user completes. It is the state a URID is minted into before KYC. There is one KYC flow, and passing it moves the user straight to `Live`. Functions for any non-`Live` status are restricted on-chain.
{% endhint %}
## State transitions
A URID is always minted in `Tourist` and promoted to `Live` once KYC passes; there is no direct path from `Na` to `Live`.
```mermaid
flowchart LR
Na["Na (0)"] -->|mint URID| Tourist["Tourist (2)"]
Tourist -->|KYC passed| Live["Live (5)"]
Live -->|ongoing task overdue| SoftBlocked["SoftBlocked (1)"]
SoftBlocked -->|task completed| Live
Live -->|compliance action| Blocked["Blocked (3)"]
Blocked --> Closed["Closed (4)"]
```
A user whose KYC is rejected stays in `Tourist` and cannot access core banking features. `Blocked` and `Closed` can also be reached from other states by a compliance action.
## What you handle vs UR
Onboarding responsibilities split as follows:
| Step | UR handles | You handle |
| ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| KYC verification | Identity checks, screening, compliance review | Presenting KYC components in your app (UR webview or Sumsub SDK) |
| Wallet creation | Minting the URID NFT, provisioning the wallet (Managed Custody Mode) | Mapping your user ID to their URID |
| State changes | Transitioning the URID between statuses | Listening for webhooks, updating your UI accordingly |
| KYC prompt | Nothing; you decide when | Prompting the user to complete KYC when they attempt an action that requires `Live` |
## The onboarding flow
A URID moves from `Tourist` to `Live` through a single KYC flow. The steps run in this order:
{% stepper %}
{% step %}
### URID is minted (Tourist)
The user authenticates, and UR mints the URID NFT in `Tourist` status. The user can receive partner off-ramp and inbound P2P (up to 250 USD/EUR), but cannot move funds externally.
{% endstep %}
{% step %}
### Proof of address
The user confirms their residential address through the Sumsub flow (GPS method).
{% endstep %}
{% step %}
### Questionnaire
The user answers the questionnaire (eligibility, source of funds, declarations) through the Sumsub flow.
{% endstep %}
{% step %}
### Proof of identity
The user completes the passport or national ID NFC scan and a liveness check through the Sumsub flow. See [KYC components](#kyc-components) for the mobile NFC requirement.
{% endstep %}
{% step %}
### Form A signing
Outside Sumsub, the user signs the Beneficial Ownership Declaration (Form A) with the embedded wallet that holds their URID.
{% endstep %}
{% step %}
### Compliance review
UR screens the user (sanctions, PEP, adverse media) and reviews the submitted data. On pass, the URID moves to `Live` and all account restrictions are lifted automatically. On failure, the attempt is rejected and the user stays in `Tourist`.
{% endstep %}
{% endstepper %}
Your backend tracks progress through a KYC status field whose exact values depend on the integration path: `kycFlow.currentStep` on the UR main stack (see the [External Wallet Access Mode API reference](https://docs.ur.app/api-reference/account/external-wallet-access-mode)), or the session `state` in the partner-managed SDK path (see the [Managed Custody SDK KYC reference](https://docs.ur.app/api-reference/kyc-and-kyb/managed-custody-sdk-kyc)).
### Webhooks you receive
You receive the following onboarding webhooks. For money-movement and other events, see the full [event catalog](/developer-resources/webhook#6-event-catalog).
| Webhook event | When | Applies to |
| ------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------ |
| `sumsub_kyc_result` | A Sumsub review completes (`Pass` or `Rejected`) | All KYC paths |
| `kyc_status` | UR returns the compliance decision (`Pending`, `Pass`, `Rejected`, `ManualReview`, or `Error`) | All KYC paths |
| `fma.account.result` | Partner-managed onboarding ends (`activated` or `rejected`) | Partner-managed (FMA) KYC only |
| `fma.penny_drop.result` | A penny-drop attempt resolves (`verified` or `failed`) | Partner-managed (FMA) KYC only |
| `fma.additional_kyc.required` | UR ops request a partner-driven retry of part or all of a user's KYC | Partner-managed (FMA) KYC only |
| `fma.additional_kyc.completed` | A retry session reaches its last step | Partner-managed (FMA) KYC only |
{% hint style="info" %}
The definitive `Tourist → Live` signal is `kyc_status` with `status: "Pass"` on the UR main stack, or `fma.account.result` with `status: "activated"` for partner-managed KYC. Only raise the user's access level on that signal.
{% endhint %}
## KYC components
The KYC flow collects four components, presented in the order shown in [The onboarding flow](#the-onboarding-flow). Depending on your integration mode, you present them through the UR webview or the Sumsub SDK.
**Proof of address.** UR uses the GPS method to confirm the user's residential address. UR can show this through a webview or iFrame pointing to the UR web app (get.ur.app). The user must be signed in.
**Questionnaire.** Questions about the user, including eligibility screening, source of income, and monthly income. For a lightweight integration, UR can show the questionnaire through a webview or iFrame pointing to get.ur.app. The user must be signed in.
**Proof of identity (passport or national ID NFC scan).**
{% hint style="warning" %}
**NFC scanning is only available on a mobile app.** If your platform uses the Sumsub SDK directly (External Wallet Access Mode), the NFC scan step is only supported in the Sumsub mobile SDK (iOS/Android); it is not available in the Sumsub web SDK. You must expose this step through your mobile app. Web-only platforms cannot complete this step through the Sumsub SDK. If your platform has no mobile app, email to discuss alternatives.
{% endhint %}
* Scenario A1 (iOS): UR returns a QR code and link to its NFC scanning provider. When the user taps it, an iOS App Clip opens, the user completes the NFC scan, then returns to your app.
* Scenario A2 (Android): UR returns a QR code and link to its NFC scanning provider. The user downloads a separate app to perform the NFC scan, then returns to your app.
**Agreement (Form A) signing.** Form A contains the information the user filled in during KYC, so the user must complete the proof of address and questionnaire first and the data must exist in UR's database before UR can generate the form. The user signs Form A with the embedded wallet that holds their URID. UR can show Form A through a webview pointing to get.ur.app. The user must be signed in.
# KYC & compliance
What UR verifies during KYC, the data we collect, and the methods we use.
UR is a regulated financial product. Every end user must complete **Know Your Customer (KYC)** checks before they can access core banking features such as external transfers, IBANs, debit cards, and FX. This page explains **what** UR verifies, the data UR collects, and **how** each check works. It lists the data fields and the options behind each check, but not the exact user-facing question wording, which UR's compliance team configures and shows to users at runtime through the Sumsub SDK.
For the user-journey view of when each step happens, see [The User Lifecycle](/concepts/overview-the-user-lifecycle). For implementation details, including endpoints, status enums, and webhooks, see the [Developer Resources](https://docs.ur.app/api-reference/account/external-wallet-access-mode) section.
## What UR verifies
UR verifies five core areas: **identity**, **domicile**, **account purpose and source of funds**, **beneficial ownership**, and **sanctions exposure**. Each area is collected through a dedicated check described below.
### Data conventions
UR applies the following conventions to all KYC data:
* **Eligibility basis:** UR determines eligibility by the user's country of residence (domicile). A small set of restricted nationalities (US persons, North Korea, Iran, Russia) is excluded regardless of residence. See [Supported regions](/getting-started/supported-regions) for the unsupported-residence list and the restricted nationalities.
* **Language:** all data shared with compliance must be in English. For users from non-English-speaking countries, personal-data fields such as name and address are collected in both native script and Latin transliteration.
* **Country codes:** ISO 3166-1 alpha-3 (for example, `POL`, `CHN`, `DEU`, `CHE`).
* **Dates:** `YYYY-MM-DD`.
### Identity verification
UR offers three identity-verification methods. NFC is the primary path. Penny transfer and video verification support users who cannot complete an NFC scan.
| Method | Role | User device |
| ---------------------- | -------------------------- | --------------------------- |
| **NFC + liveness** | Primary | NFC-capable mobile device |
| **Penny transfer** | Fallback for EU/FATF users | Any (bank account required) |
| **Video verification** | Reserved fallback | Any (camera required) |
#### NFC scan + liveness check *(primary)*
The user scans the electronic chip in their biometric passport or national ID through the Sumsub mobile SDK. UR validates the chip data against the document's certificate chain and reads the identity details directly from the chip, including document number, issuing country, name, date of birth, gender, expiry date, MRZ, and photo. The document must be valid for at least 3 months from the date of submission; UR blocks a document that expires sooner or has already expired. The extracted name, date of birth, and nationality must match the questionnaire responses.
The user then completes a **liveness check**, a short selfie capture in the SDK that confirms the person is physically present. The live photo is matched against the photo retrieved from the NFC chip. Verification only passes when both the liveness check and the photo match succeed.
NFC scanning requires an NFC-capable mobile device. Web-only platforms cannot complete this step through the Sumsub web SDK. See the note in [The User Lifecycle](/concepts/overview-the-user-lifecycle).
In the **UR-hosted webview** integration path, the NFC chip scan, document scan, and selfie are completed in **ReadID** (the ReadID app on Android, or an [App Clip](https://developer.apple.com/app-clips/) on iOS), which UR orchestrates for you. The questionnaire and the domicile (device location) check run in the webview itself. An NFC-capable mobile device is still required for the ReadID step; the webview path removes the partner's need to build the NFC handoff, not the NFC scan itself.
#### Penny transfer *(fallback for FATF-jurisdiction users)*
For users who cannot complete an NFC scan, UR supports a **penny transfer**. The user sends a small bank transfer from their personal bank account to their UR IBAN. UR validates the inbound transfer details and uses them as proof of identity, together with the standard liveness check.
**Constraints**
| Constraint | Detail |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Same name | Sender name must match the UR account holder. Family-member or business accounts are not accepted. |
| FATF country | The sender's bank must be in one of the 37 active FATF member jurisdictions, determined from the BIC/SWIFT country code. |
| Currency | The inbound penny remittance is EUR (primary) or CHF. (A USD virtual IBAN is not required beforehand: for eligible partners the USD vIBAN is provisioned for `Tourist` users **before** KYC completes, so a USD IBAN is not gated on finishing KYC.) |
| Amount | Approximately 50 CHF or EUR is recommended; amounts up to 500 CHF or EUR are accepted. There is no enforced minimum; any received amount can be used for validation. Larger transfers may be subject to post-activation account limits. |
| Processing time | Typically 1 to 2 business days. |
{% hint style="info" %}
**Eligibility.** Penny transfer is only available to users whose bank is in a FATF jurisdiction. Users outside that scope are routed to the NFC flow.
{% endhint %}
#### Video verification *(reserved fallback)*
For users who cannot complete either NFC or penny transfer, for example because they have no NFC-capable device and no FATF-jurisdiction bank account, UR offers a video-verification path coordinated case by case with the support team. Contact when a user reaches this state.
### Domicile verification (proof of address)
| Method | Role | How it works |
| ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GPS check** | Primary | The user confirms that they are at their declared home address. The device captures GPS coordinates, which UR reverse-geocodes and compares with the address provided in the questionnaire. |
| **Document upload** | Alternative | When GPS is not viable, the user uploads a document proving residential address. |
The GPS check passes when the device location is within the expected proximity of the declared address.
| Constraint | Accepted |
| ------------- | ------------------------------------------ |
| Document type | Government-issued documents, utility bills |
| Document age | Issued within the last 3 months |
| Languages | English, German, French, or Italian |
### Account questionnaire
The questionnaire collects the information UR needs to operate a regulated Swiss IBAN account. The categories are listed below. The canonical question set is configured in Sumsub and presented to the user at runtime.
* **Eligibility:** age (18+), citizenship in non-restricted jurisdictions, US Person status, PEP (politically exposed person) declaration, and acceptance of UR's Terms of Use, Privacy Policy, and Card Terms.
* **Personal information:** legal name, date of birth, gender, nationality, residential address, and verified email.
* **Employment:** employment status (employed, self-employed or freelancer, retired, student or trainee, unemployed); job category when employed (employee, manager, C-level or executive, director or board member); and business sector.
* **Account purpose:** the user's intended use of the UR account, such as crypto off-ramp, savings, or investment.
* **Source of funds:** gross annual income range (under 50,000; 50,000 to 100,000; 100,000 to 500,000; 500,000 to 1,000,000; over 1,000,000 USD), approximate total assets range (under 100,000; 100,000 to 500,000; 500,000 to 1,000,000; over 1,000,000 USD), and source-of-funds category (business income or salary, savings and pension, investments, inheritance, or other).
* **Declarations:** address-accuracy declaration, the FINMA-required acknowledgment that deposits are not covered by any depositor-protection scheme, and other regulator-required attestations. The user must confirm UR-specific declarations explicitly; they cannot be auto-filled.
### Beneficial ownership declaration (Form A)
A **Beneficial Ownership Declaration (Form A)** identifies the natural person or persons who ultimately own or benefit from the assets held in the UR account. UR generates the declaration from the user's KYC responses, and the user signs it as part of the KYC flow.
For most individual users, Form A confirms that the user is the beneficial owner of the assets. If another person is the beneficial owner, UR may need to collect that person's required identifying information. Depending on the partner UX, Form A can be handled inside the Sumsub process or integrated as a separate signing step. See [Component 4 in The User Lifecycle](/concepts/overview-the-user-lifecycle).
The declaration consolidates the user's confirmations into a single signed statement. It covers that the user is over 18, is not a national of North Korea, Iran, or Russia, and is not a US person; that the residential address and sole country of tax residence are accurate; that the user is the sole beneficial owner of the account assets; the declared source of funds; acceptance of the Terms of Use, Privacy Policy, and Card Terms; acceptance of the business risks of using UR; and the FINMA acknowledgment that deposits are not protected by any depositor-protection scheme. The statement also notes that deliberately providing false information is a criminal offense under article 251 of the Swiss Criminal Code. UR renders the exact text from the user's collected data and returns it for the user to read and sign; display it verbatim. For the fetch, sign, and submit endpoints, see the [Developer Resources](https://docs.ur.app/api-reference/account/managed-custody-mode).
### Tax self-certification (CRS)
Under the Common Reporting Standard (CRS), UR collects a tax-residency self-certification, either at onboarding or as an ongoing-KYC task. The user declares each country of tax residence as an ISO 3166-1 alpha-3 code, together with a Taxpayer Identification Number (TIN) whose format matches that country. A user with more than one tax residence provides one entry per residence. If a CRS task is due and the user misses its deadline, the account moves to `SoftBlocked` until the task is completed.
### AML & sanctions screening
UR runs automated AML (Anti-Money Laundering) screening throughout the user's lifecycle:
* **At onboarding:** the user is screened against international sanctions lists, PEP lists, and adverse media.
* **Continuously:** users are re-screened periodically to capture list changes after onboarding.
* **On transactions:** specific transactions may trigger additional risk-based checks, such as a step-up liveness check before high-value off-ramps. See `needLivenessCheck` in the [API reference](https://docs.ur.app/api-reference/account/managed-custody-mode).
A user who fails sanctions screening, is from an unsupported country, or has an unsupported nationality is rejected during compliance review. The user remains in `Tourist` status and cannot access core banking features.
## When KYC happens
UR runs KYC when a user opens a UR account and continues compliance monitoring throughout the user's lifecycle. After the initial KYC verification, UR may request additional information through ongoing KYC, client enhanced due diligence, or transaction enhanced due diligence depending on the user's profile, activity, and regulatory requirements.
| Review type | When it happens | What UR may collect |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Initial KYC verification | During account opening, before the user can access core banking features | Questionnaire, domicile verification, identity verification (NFC, penny transfer, or video), signed Beneficial Ownership Declaration (Form A), and AML/sanctions screening. |
| Ongoing KYC | Periodically, or when regulatory refresh rules require updated user information | Refreshed proof of address, updated questionnaire responses, refreshed identity documents, CRS self-certification, or a re-signed Form A. |
| Client enhanced due diligence | When the user's profile, country, occupation, source of funds, or other risk signals require deeper review | Additional information about account purpose, source of funds, source of wealth, expected activity, supporting documents, or compliance attestations. |
| Transaction enhanced due diligence | When a specific transaction or activity pattern triggers additional risk-based review | Transaction rationale, supporting documents, additional liveness checks, or other information needed to assess the transaction. |
## Verification outcomes
KYC results map directly to the user's URID status:
| Outcome | URID status | What the user can do |
| -------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
| URID minted, before KYC | `Tourist` | Receive partner off-ramp and inbound P2P (up to 250 USD/EUR); cannot move funds externally |
| KYC approved | `Live` | All banking features: external transfers, IBAN, debit card, FX |
| Compliance review failed or user rejected | `Tourist` | Core banking features unavailable |
| Pending ongoing KYC or enhanced due diligence, deadline missed | `SoftBlocked` | Money features locked until the open task is completed |
For the on-chain status mapping (`Tourist=2`, `Live=5`, etc.), see [Smart Contracts](https://docs.ur.app/api-reference/smart-contracts).
The KYC step machine depends on the path. Partner-managed (FMA) partners who push data or hand over a share token see the coarse sequence `PartnerDataIngestion` -> `IdentityVerification` -> `SignFormA` -> `Register`, while FMA partners on the Sumsub SDK see the fine-grained Sumsub steps ending `IdOrPassportOrOtherIdInformationScan` -> `IdAndLiveness` -> `SignFormA` -> `Register`. The UR-hosted flow runs the same fine-grained steps. See the state tables in [Managed Custody SDK KYC](https://docs.ur.app/api-reference/kyc-and-kyb/managed-custody-sdk-kyc) and [Managed Custody Mode](https://docs.ur.app/api-reference/account/managed-custody-mode).
## Vendors
* **Sumsub:** KYC provider for the questionnaire, the domicile (device location) check, document upload, and AML/sanctions screening. When you integrate the Sumsub SDK directly (External Wallet Access Mode), the document scan, NFC chip read, and liveness check also run in the Sumsub mobile SDK.
* **ReadID:** in the UR-hosted webview path, performs the passport/national-ID NFC chip read, document scan, and selfie/liveness capture. The user opens ReadID as a mobile app or via the iOS App Clip.
UR sends the final compliance decision (`Pass` / `Rejected`) to you via the [`kyc_status` webhook](/developer-resources/webhook).
## Additional KYC after a user goes live
KYC does not end at onboarding. After a user becomes `Live`, UR may request additional verification when regulatory refresh rules, risk signals, or compliance reviews require updated information. Examples include a proof-of-address refresh, passport re-scan, re-signed Form A, full re-verification, or CRS self-certification. These requests map to the ongoing KYC and enhanced due diligence reviews described in [When KYC happens](#when-kyc-happens).
How you integrate additional KYC depends on which KYC model your `partnerId` uses. The two models do not share endpoints or webhooks, so read only the one that applies to you.
### Partners on the UR-hosted KYC flow
This covers External Wallet Access Mode and other integrations where the user completes KYC through UR's own flow. The task is discovered by polling, and the outcome arrives on `kyc_status`.
| Step | What you do | Where it's documented |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Detect the required task** | Poll the account/status endpoints and read `kycRetryVerificationLevel`, `kycCurrentStep`, and `crsInfo` (`needCrs`, `restrictDate`, `url`) to see what the user must complete and by when. | [Fetch UR Account information](https://docs.ur.app/api-reference#fetch-ur-account-information), including the **KycRetryVerificationLevel** and **kycCurrentStep** enum tables; per-mode account status with `kycFlow` and `crsInfo` in the [External Wallet Access Mode API reference](https://docs.ur.app/api-reference/account/external-wallet-access-mode) |
| **2. Collect and submit the update** | Re-initiate the Sumsub flow for the required retry level using `isRetryVerification=true` and the matching `retryLevel`, with optional `stepType` when needed. The user then completes the requested step in the Sumsub SDK. For CRS, direct the user to the `crsInfo.url` link returned by the status endpoint. | Get Sumsub SDK Token (`/api/v1/sumsub/create-access-token`) in the [External Wallet Access Mode API reference](https://docs.ur.app/api-reference/account/external-wallet-access-mode) |
| **3. Receive the decision** | UR sends the compliance decision (`Pass` / `Rejected`) to your webhook. You can also query status again to confirm the latest result. | [`kyc_status` webhook](/developer-resources/webhook); [Query Sumsub status by network](https://docs.ur.app/api-reference#query-sumsub-status-by-network) |
The retry level in `kycRetryVerificationLevel`, such as `ResetAll`, `ResetSign`, `ResetGPS`, or `RetryVerificationPassport`, tells you which data points the user must provide again. See the enum tables in [OpenAPIs](https://docs.ur.app/api-reference#fetch-ur-account-information) for the full mapping.
{% hint style="warning" %}
The retry parameters above apply to `/api/v1/sumsub/create-access-token`. The by-network variant, [Create Sumsub access token by network](https://docs.ur.app/api-reference#create-sumsub-access-token-by-network), takes only `tokenId` and `network` and always issues a token at the flow's start level, so it cannot drive a specific retry level. If your users are on an external (non-Mantle) network, confirm the path for additional KYC through your dedicated integration channel.
{% endhint %}
If the user misses the deadline for an open task on this model, the user moves to `SoftBlocked` and money features stay locked until the task is completed.
### Partner-managed (FMA) partners
Partners who own the KYC user experience do not poll for these tasks. UR operations issue a retry directive, and your platform is notified over webhook. There is no polling step and no `kyc_status` event.
| Step | What you do | Where it's documented |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **1. Receive the directive** | Handle the `fma.additional_kyc.required` webhook. Its `taskType` says what the user must redo, and `dataChannel` says which of your integration paths applies. Neither your platform nor the user can start a retry. | [Retry KYC](https://docs.ur.app/api-reference/kyc-and-kyb/retry-kyc); payload contract in [Webhooks](/developer-resources/webhook) |
| **2. Claim a session and collect the data** | Call `POST /api/fma/v1/kyc/session/create` to claim the session UR created, then run only the steps `taskType` names, through the same endpoint your channel uses for onboarding. Re-sign Form A, and call `/kyc/submit` only when `fiat24Mode` is `auto_register`. | [Retry KYC](https://docs.ur.app/api-reference/kyc-and-kyb/retry-kyc), including a per-channel walkthrough and lifecycle diagram |
| **3. Record completion** | UR sends `fma.additional_kyc.completed` when the session reaches its last step. No further call is required. | [Retry KYC](https://docs.ur.app/api-reference/kyc-and-kyb/retry-kyc) |
On this model the directive's `deadlineAt` is informational: UR does not expire the directive or the session when it passes, and no event fires at the deadline. Compliance applies the consequences off-platform.
# Webhooks
How UR delivers business events to partner-registered HTTPS endpoints. Covers protocol, signatures, retries, idempotency, and the full event catalog.
This document is the canonical reference for partner backend engineers integrating with UR's webhook delivery service. It covers the wire protocol, signature verification, retry semantics, idempotency contract, and every event type currently in production.
If you only have a few minutes, read [§1 Overview](#1-overview) and [§4 Signature verification](#4-signature-verification). Everything else is reference material.
***
## 1. Overview
UR pushes asynchronous business events (transactions confirmed on-chain, KYC outcomes, allowance changes, card-authorization failures, partner-KYC session results) to an HTTPS endpoint you register in your partner contract.
The high-level contract:
| Aspect | Behavior |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| Transport | `HTTPS POST`, `Content-Type: application/json` |
| Body | JSON envelope `{event, data, timestamp}` |
| Authentication | EIP-191 ECDSA signature in HTTP headers (V1 legacy + V2 recommended, both delivered in parallel) |
| Delivery semantics | At-least-once, \~48 h retry window, ±20 %-jittered exponential backoff |
| Success criterion | Your endpoint returns HTTP 2xx within the configured timeout (default 30 s) |
| Idempotency | We send `X-Webhook-Request-Id` (UUID v4); partners **MUST** dedupe on this |
| Ordering | Sequential per-partner; across partners is unordered |
> User-Agent: `URBank-Webhook/2.0` (pre-v2.0 partners saw `URBank-Webhook/1.0`). Whitelist by domain, not UA. The `URBank-Webhook` string is a fixed wire-protocol constant retained for backward compatibility; it is not a product name.
***
## 2. Endpoint requirements
Your endpoint **MUST**:
1. Be reachable via HTTPS with a CA-issued certificate (no self-signed).
2. Accept `POST` with `Content-Type: application/json`.
3. Return HTTP 2xx on success within the configured timeout (default 30 s).
4. Return HTTP 4xx on **permanent** failure; we will NOT retry.
5. Return HTTP 5xx (or time out) on **transient** failure; we WILL retry.
6. Be idempotent: handle the same `X-Webhook-Request-Id` more than once gracefully (every retry reuses the same id).
Your endpoint **SHOULD**:
* Verify at least one of the two signatures (see [§4](#4-signature-verification)) before processing.
* Reject any request whose `X-Webhook-Timestamp` skews more than ±5 minutes from your clock (replay protection).
* Ack fast (< 1 s ideal) and process asynchronously. A queue + worker pattern works best because our delivery worker holds a TCP connection open until you respond.
***
## 3. HTTP headers
Every outbound request carries these headers. `X-Webhook-*` are envelope metadata; `X-Api-*` are signature material.
| Header | Example | Meaning |
| ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- |
| `Content-Type` | `application/json` | Always JSON |
| `User-Agent` | `URBank-Webhook/2.0` | Stable for the v2.0 generation of the delivery service |
| `X-Webhook-Request-Id` | `b3e8…-…` (UUID v4) | **Idempotency key.** Same value across the first delivery and every retry of the same message. Dedupe on this. |
| `X-Webhook-Timestamp` | `1735689600` | Unix seconds at the moment the HTTP request is assembled |
| `X-Webhook-Event-Type` | `transaction` | Canonical event name (see [§6 Event catalog](#6-event-catalog)) |
| `X-Webhook-Attempt` | `1`, `2`, … | **1-indexed delivery attempt.** First delivery is `1`, first retry is `2`. |
| `X-Api-Signature` | `0x…` | **V1 (legacy) signature.** Present whenever V1 is enabled in your contract. |
| `X-Api-PublicKey` | `0x…` | V1 signer Ethereum address. Same address as V2. |
| `X-Api-Signature-V2` | `0x…` | **V2 (recommended) signature.** Present whenever V2 is enabled. |
| `X-Api-PublicKey-V2` | `0x…` | V2 signer Ethereum address (= V1 address). |
### 3.1 Response headers you can send
| Header | When | Effect |
| -------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `X-Webhook-No-Retry: true` | On a 4xx or 5xx response when you've decided this message should never be retried | We move the message to `DEAD` immediately and stop retrying. |
Everything else in your response is ignored. Status code is what we key on (see [§5](#5-retry-policy)).
***
## 4. Signature verification
All webhooks are signed with the **EIP-191** "personal sign" scheme used by Ethereum wallets:
```
prefix = "\x19Ethereum Signed Message:\n" + len(message)
hash = Keccak256(prefix + message)
sig = ECDSA-secp256k1(server_private_key, hash) // 65 bytes, 0x-prefixed hex
recover = ecrecover(hash, sig) // → server address
```
The signing **key** is the same for V1 and V2; only the signed **message** differs.
### 4.1 V1 (legacy)
```
message = body // raw JSON bytes, byte-for-byte
header = X-Api-Signature: 0x{65-byte hex}
```
V1 is what legacy partners have always verified. It will remain on the wire indefinitely; a retirement announcement will run on a ≥3-month deprecation window if we ever do retire it.
### 4.2 V2 (recommended)
```
message = timestamp + "." + request_id + "." + body
= "1735689600.b3e8ffff-0000-4000-8000-000000000000.{...json...}"
header = X-Api-Signature-V2: 0x{65-byte hex}
```
V2 binds the timestamp and request id into the signature. Without that binding an attacker who captures a webhook can replay the body with a fresh timestamp; with V2 the recovered address won't match. **All new integrations should validate V2.**
### 4.3 Address pinning
The signer address is published in your partner contract. Pin it on your side; do **not** trust whatever `X-Api-PublicKey(-V2)` says without comparing to the pinned value. The header is a convenience; the contract is the source of truth.
### 4.4 Reference implementation (Node.js)
The verifier call moved namespace between ethers major versions. Both forms are shown below; the rest of the function is identical.
**ethers v6** (current; published 2023+):
```js
const { verifyMessage } = require("ethers");
function verifyV2(req, expectedSigner) {
const ts = req.headers["x-webhook-timestamp"];
const id = req.headers["x-webhook-request-id"];
const body = req.rawBody.toString("utf8"); // raw, before JSON.parse
const sig = req.headers["x-api-signature-v2"];
const message = `${ts}.${id}.${body}`;
const recovered = verifyMessage(message, sig); // v6: top-level export
return recovered.toLowerCase() === expectedSigner.toLowerCase();
}
```
**ethers v5** (legacy; for partners on the v5 line):
```js
const { ethers } = require("ethers");
function verifyV2(req, expectedSigner) {
// ... ts / id / body / sig / message identical to v6 above ...
const recovered = ethers.utils.verifyMessage(message, sig); // v5: under .utils
return recovered.toLowerCase() === expectedSigner.toLowerCase();
}
```
If you're not sure which version you're on, run `node -p "require('ethers').version"`. `6.x.x` is v6; `5.x.x` is v5. The hash + secp256k1 recovery underneath is the same EIP-191 algorithm in both versions, so the recovered address is byte-identical.
### 4.5 Reference implementation (Go)
```go
import (
"fmt"
"strings"
"github.com/ethereum/go-ethereum/common"
"github.com/ethereum/go-ethereum/crypto"
)
func verifyV2(ts, reqID, body, sigHex, expectedAddr string) (bool, error) {
msg := fmt.Sprintf("%s.%s.%s", ts, reqID, body)
prefixed := fmt.Sprintf("\x19Ethereum Signed Message:\n%d%s", len(msg), msg)
hash := crypto.Keccak256Hash([]byte(prefixed))
sig := common.FromHex(sigHex)
if sig[64] >= 27 { sig[64] -= 27 }
pub, err := crypto.SigToPub(hash.Bytes(), sig)
if err != nil {
return false, err
}
return strings.EqualFold(crypto.PubkeyToAddress(*pub).Hex(), expectedAddr), nil
}
```
### 4.6 Verifying both versions during the migration window
A partner who verifies V2 only and rejects on failure will break the day UR rotates a key (rare but planned). Defense-in-depth:
```
if X-Api-Signature-V2 present: verify V2 → 200 if OK
elif X-Api-Signature present: verify V1 → 200 if OK
else: 401 missing signature
```
A common partner-side bug is parsing JSON first and then re-serializing for signature verification. That breaks because Go's `encoding/json` does **not** preserve key order. **Read the raw request body byte-for-byte before deserializing.** The `req.rawBody` / `c.Request.GetBody()` pattern in most frameworks does this for you.
***
## 5. Retry policy
### 5.1 Classification by response
| Outcome | Class |
| ----------------------------------------------- | ---------------------------------------------------------------- |
| HTTP 2xx | Success (message marked `DELIVERED`). |
| HTTP 4xx (except 408, 429) | Non-retryable (message marked `DEAD`). |
| HTTP 408, 429 | Retryable (server-side hint that you were rate-limited or slow). |
| HTTP 5xx | Retryable. |
| Network error / timeout / DNS failure | Retryable. |
| HTTP response header `X-Webhook-No-Retry: true` | Treated as non-retryable regardless of status. |
### 5.2 Backoff schedule
±20 % jittered exponential backoff, base 30 s, cap 6 h, max **20 attempts** over roughly a **48-hour** window:
| Attempt | Approx. delay since previous |
| ------- | ---------------------------- |
| 1 | (initial) |
| 2 | \~30 s |
| 3 | \~1 min |
| 4 | \~2 min |
| 5 | \~4 min |
| … | doubling each step, jittered |
| 11 | \~4 h |
| 12 | \~6 h (cap) |
| 13 … 20 | \~6 h each |
After attempt 20 the message is moved to `DEAD` and persisted for 90 days. UR operations can manually re-queue a `DEAD` message on partner request.
### 5.3 Circuit breaker
If we observe 20 consecutive failures (5xx / timeout / connection-refused) for a given partner, a per-partner circuit opens for 60 s. Open-circuit attempts are not sent to your endpoint; they're requeued for the next backoff slot. Your retry count is **not** incremented while the circuit is open.
### 5.4 What `X-Webhook-Attempt` tells you
The header is 1-indexed:
* `Attempt: 1`: first delivery (fresh message)
* `Attempt: 2+`: retry
You can use this to bias logging (verbose on `1`, terse on retries) or to detect partner-side hot loops where retries keep failing for the same root cause.
***
## 6. Event catalog
Subscription is **per-partner, per-event-type**. You only receive event types your contract subscribes to. Asking for an event you're not subscribed to is the most common silent-fail in integrations; if you don't see events you expect, check your subscription before debugging anything else.
New event types may be added; existing event-type bodies are **append-only**. We may add new optional fields, never rename or remove existing ones.
### 6.0 Field-naming quirks (read this first)
The customer identifier appears under one of two field names depending on event type, and its JSON type also varies between events. These are **wire-fixed** across all delivered events; partners must handle both shapes.
| Event types | Field name | JSON type |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------- |
| `transaction`, `transaction_v2`, `card_spending_failed` | `urId` | string |
| `allowance` | `urId` | int64 (number, no quotes) |
| `fma.account.result`, `fma.penny_drop.result`, `fma.kyc.reuse_check.result`, `fma.kyc.result`, `fma.additional_kyc.required`, `fma.additional_kyc.completed` | `urId` | int64 (number, no quotes) |
| `kyc_status`, `sumsub_kyc_result`, `monthly_limit_exceeded` | `tokenId` | string |
All four shapes refer to the **same** UR NFT token id. The split is legacy: the `tokenId` family predates the unification on `urId`, and the int64/string split predates the unification on string. The wire shapes are frozen for backwards compatibility; do not assume future events will pick one canonical form.
Other quirks worth flagging up-front:
* **Subscription changes** (enable / disable an event type, rotate webhook URL) are coordinated with your UR technical liaison; there is no self-service API.
* **Token symbols** referenced in event bodies (`USD24`, `EUR24`, `CHF24`, `JPY24`, `CNH24`, `SGD24`, `HKD24`, `USDC`) are the UR-issued tokenized fiat assets; see [Tokenized deposits](/concepts/tokenized-deposits) for the catalogue and contract addresses.
* **Wire-fixed JSON keys** such as `deadLine` (capital `L`, in `card_spending_failed`) are preserved verbatim from legacy schemas. Where they appear, the field reference table for that event notes the quirk explicitly.
### 6.1 Money movement & on-chain events
#### `transaction` (legacy transaction event)
Emitted when a tracked transaction is confirmed on-chain (deposit, withdrawal, transfer, FX, card spend).
```json
{
"event": "transaction",
"timestamp": 1735689600,
"data": {
"urId": "1000001234",
"title": "Sent USD24",
"subtitle": "to 0xAbC…",
"amount": "100.00",
"type": "transfer_out",
"timestamp": 1735689599,
"currency": "USD24",
"direction": "out",
"txHash": "0xdead…beef",
"chainId": "eip155:5000",
"inputToken": "USD24",
"inputAmount": "100.00",
"inputTokenAddress": "0x…"
}
}
```
Bidirectional fan-out: for a P2P transfer between two of your customers (both bound to your `partner_id`) you receive **two** webhooks: one with `direction=out` and the sender's `urId`, and one with `direction=in` and the receiver's `urId`. For a self-transfer (same `urId` on both sides) business-key dedup collapses to a single webhook.
Field reference (see also [TransactionData in the API reference](https://docs.ur.app/api-reference/account/delegated-contract-mode#transactiondata)):
| Field | Type | Description |
| -------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------- |
| `urId` | string | Token ID of the customer this event belongs to |
| `title`, `subtitle`, `image` | string | UI strings; partner can ignore or display |
| `amount`, `currency` | string | Display amount (decimal string) and ticker; partner-visible |
| `type` | string | Business type (e.g. `transfer_in`, `transfer_out`, `card_spend`, `fx`) |
| `direction` | string | `in` or `out` from this customer's perspective |
| `txHash`, `chainId` | string | On-chain identifiers; `chainId` is CAIP-2 (e.g. `eip155:5000`) |
| `inputToken`, `inputAmount`, `inputTokenAddress` | string | Source asset |
| `outputAmount` | string (omitempty) | FX leg |
| `mcc` | uint64 (omitempty) | Merchant Category Code (card spend) |
| `reference`, `bankAccount`, `crdMultiToken`, `partnerRefId`, … | various (omitempty) | Channel-specific extras |
#### `transaction_v2` (current transaction event)
Same business event as `transaction`, but a normalized schema and lifecycle (`broadcastTimeE9`, `finalTimeE9`). New partners should subscribe to `transaction_v2` and ignore `transaction`.
```json
{
"event": "transaction_v2",
"timestamp": 1735689600,
"data": {
"id": 42,
"txHash": "0xdead…beef",
"txLogIndex": 0,
"blockNumber": 12345678,
"createTimeE9": 1735689500000000000,
"broadcastTimeE9": 1735689510000000000,
"finalTimeE9": 1735689600000000000,
"type": "transfer_out",
"chainId": "eip155:5000",
"chainName": "Mantle",
"urId": "1000001234",
"direction": "out",
"amount": "100.00",
"currency": "USD24",
"status": "CONFIRMED",
"detailsJson": "{…}",
"reqId": "…",
"refundType": ""
}
}
```
| Field | Type | Description |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `refundType` | string | Refund discriminator. `""` (not a refund), `BANK_REFUND` (bank transfer refund), `CARD_REFUND` (card spending refund), or `CARD_REVERSAL` (card authorization reversal). See [§12.4 Identifying refund transactions](https://docs.ur.app/api-reference/account/managed-custody-mode#id-12.4-identifying-refund-transactions) for details. |
`detailsJson` is a stringified JSON blob whose structure depends on `data.type`. See [detailsJson reference by transaction type](https://docs.ur.app/api-reference/account/managed-custody-mode#id-12.3-detailsjson-reference-by-transaction-type) for the full schema of each type.
#### `allowance` (ERC-20 allowance change)
Emitted when one of your customer's allowance flags flips (approve / revoke / transferFrom drains it).
```json
{
"event": "allowance",
"timestamp": 1735689600,
"data": {
"urId": 1000001234,
"allowances": [
{ "tokenSymbol": "USD24", "hasAllowance": true, "chainId": "eip155:5000" },
{ "tokenSymbol": "EUR24", "hasAllowance": false, "chainId": "eip155:5000" }
]
}
}
```
| Field | Type | Description |
| ------------------- | ------ | ---------------------------------------------------------------------------- |
| `data.urId` | int64 | Customer UR id (note: int64 here, not string; legacy quirk) |
| `data.allowances[]` | array | Updated allowance rows |
| `…tokenSymbol` | string | One of `USD24`, `EUR24`, `CHF24`, `JPY24`, `CNH24`, `SGD24`, `HKD24`, `USDC` |
| `…hasAllowance` | bool | True iff on-chain allowance > 0 for the UR contracts |
| `…chainId` | string | CAIP-2 chain id |
Only the **rows that changed** are present; never a full snapshot. Treat `allowances` as a patch, not a state dump.
#### `card_spending_failed` (card authorization rejected for user-caused reason)
Emitted when a customer's card spend fails because of insufficient balance / missing allowance / similar customer-actionable reason. Not for network or processor failures.
```json
{
"event": "card_spending_failed",
"timestamp": 1735689600,
"data": {
"urId": "1000001234",
"status": "FAILED",
"reason": "INSUFFICIENT_ALLOWANCE",
"transactionCurrency": "EUR",
"transactionAmount": "42.00",
"cardCurrency": "EUR",
"deadLine": "2025-12-31T23:59:59Z",
"authorizationToken": "…",
"txHash": "0x…",
"transactionTime": "2025-12-30T10:15:30Z"
}
}
```
| Field | Type | Description |
| ------------------------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `urId` | string | Customer UR id |
| `status` | string | Always `FAILED` for this event |
| `reason` | string (omitempty) | Machine-readable reason code |
| `transactionCurrency`, `transactionAmount` | string (omitempty) | Original authorization details |
| `cardCurrency` | string (omitempty) | Card's billing currency |
| `deadLine` | string (omitempty) | Customer-action deadline (ISO 8601). **Wire-fixed**: the JSON key is literally `deadLine` (capital `L`), not the more conventional `deadline`. Preserved verbatim for backwards-compat and will not change. |
| `authorizationToken` | string (omitempty) | Reference for the rejected authorization |
#### `monthly_limit_exceeded` (monthly spending limit hit)
Emitted when a customer's monthly spend in CHF would cross their configured limit.
```json
{
"event": "monthly_limit_exceeded",
"timestamp": 1735689600,
"data": {
"tokenId": "1000001234",
"txAmount": "150.00",
"txCurrency": "EUR",
"availableCHF": "0.00",
"usedCHF": "10000.00",
"maxCHF": "10000.00"
}
}
```
| Field | Type | Description |
| ----------------------------------- | ------ | ------------------------------------- |
| `tokenId` | string | Customer UR id |
| `txAmount`, `txCurrency` | string | Transaction that triggered the breach |
| `availableCHF`, `usedCHF`, `maxCHF` | string | Limit accounting in CHF |
### 6.2 KYC (generic)
#### `kyc_status` (KYC status change)
Emitted when UR returns an updated compliance status for a customer.
```json
{
"event": "kyc_status",
"timestamp": 1735689600,
"data": {
"tokenId": "1000001234",
"status": "Pass"
}
}
```
| Field | Type | Description |
| --------- | ------ | -------------------------------------------------------------- |
| `tokenId` | string | Customer UR id |
| `status` | string | One of: `Pending`, `Pass`, `Rejected`, `ManualReview`, `Error` |
#### `sumsub_kyc_result` (Sumsub review result)
Emitted when a Sumsub KYC review completes for one of your customers.
```json
{
"event": "sumsub_kyc_result",
"timestamp": 1735689600,
"data": {
"tokenId": "1000001234",
"kycResult": "Pass"
}
}
```
| Field | Type | Description |
| ----------- | ------ | -------------------- |
| `tokenId` | string | Customer UR id |
| `kycResult` | string | `Pass` or `Rejected` |
### 6.3 Partner-managed (FMA) KYC
These events fire only for partners using the **Fiat-Mediated Account (FMA)** integration model: partners who own the KYC user-experience and let UR run downstream compliance. They are **not** sent to non-FMA partners.
The FMA events share a common envelope shape (per-event exceptions are noted in each entry):
* `urId` (int64): UR token id (issued by UR-side mint after `create-account`)
* `sessionId` (string, UUID): the partner-KYC session this event belongs to (present on `fma.account.result`, `fma.penny_drop.result`, `fma.kyc.reuse_check.result`, `fma.additional_kyc.completed`; **absent** on `fma.kyc.result` and on `fma.additional_kyc.required`, which fires before the retry session exists)
* `partnerId` (string): your partner id (same string you sign requests with)
* `status` (string): a state discriminator inside one logical event family (the `fma.additional_kyc.*` pair does not carry it: the event name itself is the discriminator)
* `occurredAt` (int64): Unix seconds at emission (the `fma.additional_kyc.*` pair uses `createdAt` and `completedAt` instead)
#### `fma.account.result` (account onboarding outcome)
Single event that subsumes "account activated" and "session rejected" outcomes. Branch on `status`:
| `status` | Meaning | Extra fields |
| ----------- | ------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `activated` | KYC passed end-to-end. Customer is now Live on-chain with their CHF spending limit set. | (none) |
| `rejected` | The session ended in failure (compliance hard-rejected, KYC-rejected, draft expired, or retry expired). | `rejectCode`, `rejectReason` |
```json
{
"event": "fma.account.result",
"timestamp": 1735689600,
"data": {
"urId": 1000001234,
"sessionId": "b3e8ffff-0000-4000-8000-000000000000",
"partnerId": "partner_example",
"status": "activated",
"occurredAt": 1735689600
}
}
```
```json
{
"event": "fma.account.result",
"timestamp": 1735689700,
"data": {
"urId": 1000001234,
"sessionId": "b3e8ffff-0000-4000-8000-000000000000",
"partnerId": "partner_example",
"status": "rejected",
"rejectCode": "KYC_REJECTED",
"rejectReason": "KYC status=REJECTED (checkCount=3)",
"occurredAt": 1735689700
}
}
```
`rejectCode` enumeration (the values you will see in production, grouped by what caused the rejection):
| `rejectCode` | Meaning | Origin |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| `KYC_REJECTED` | Compliance review returned a hard reject. Partner should NOT retry. | KYC pipeline |
| `UPSTREAM_RETRY_EXHAUSTED` | We could not reach an upstream (Sumsub or the compliance backend, etc.) within the 48-hour retry budget. Partner may request ops re-queue. | KYC pipeline |
| `INTERNAL_ERROR` | Defensive catch-all for a bug on our side. Always paired with an incident on UR's side; contact ops. | KYC pipeline |
| `SUMSUB_REJECTED` | Sumsub returned a hard reject during identity verification. | KYC pipeline |
| `FORMA_NOT_SIGNED` | Customer never signed Form A within the session lifetime. | KYC pipeline |
| `SESSION_EXPIRED` | Draft session expired (never made it past the data-ingestion step within its TTL). | Maintenance job |
| `PENNY_TIMEOUT` | Session reached `IdentityVerification` but neither penny-drop nor NFC completed within 30 days. | Maintenance job |
| `STALE_ORPHAN_GC` | Garbage-collection of orphaned legacy session rows; should not appear for newly-onboarded partners. | Maintenance job |
Additional `Reject*` codes from the API-level error catalogue may appear if a partner-side API call triggers a session termination (rare). Treat any unknown code as "session ended; surface `rejectReason` to your support tooling and ask UR ops for translation". The set above covers >99 % of real production rejections.
When you receive `status=activated` you can trust:
* The customer's UR NFT is **Live** on-chain
* Their `setClientLimit` transaction has confirmed
* It is safe to allow card spends / withdrawals / etc.
#### `fma.penny_drop.result` (penny-drop verification)
Per-attempt verification result for the penny-drop flow (applies to partners whose KYC variant requires a micro-transfer match step; subscription is per partner). Branch on `status`:
| `status` | Meaning |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verified` | The customer's micro-transfer matched our expected amount; KYC advances to `IdentityVerification → SignFormA`. |
| `failed` | The most recent attempt did not match. The customer can retry up to a configured cap. When the last allowed attempt fails, the payload includes `exhausted: true` and no further attempts will be accepted. |
```json
{
"event": "fma.penny_drop.result",
"timestamp": 1735689600,
"data": {
"urId": 1000001234,
"sessionId": "b3e8ffff-…",
"partnerId": "partner_example",
"status": "verified",
"amount": { "value": "1.23", "currency": "EUR" },
"remitterCountryISO3": "CHE",
"transactionRecordId": 987654,
"txHash": "0xabc…def",
"txLogIndex": 0,
"occurredAt": 1735689600
}
}
```
```json
{
"event": "fma.penny_drop.result",
"timestamp": 1735689700,
"data": {
"urId": 1000001234,
"sessionId": "b3e8ffff-…",
"partnerId": "partner_example",
"status": "failed",
"amount": { "value": "0.50", "currency": "EUR" },
"remitterCountryISO3": "CHE",
"failReason": "AMOUNT_BELOW_MIN",
"attemptsRemaining": 0,
"exhausted": true,
"transactionRecordId": 987655,
"txHash": "0xabc…f01",
"txLogIndex": 0,
"occurredAt": 1735689700
}
}
```
Field reference (every field below is present on every delivery of this event type unless marked optional):
| Field | Type | Present when | Description |
| --------------------- | ------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `urId` | int64 | always | UR token id |
| `sessionId` | string (UUID) | always | Partner-KYC session id |
| `partnerId` | string | always | Your partner id |
| `status` | string | always | `verified` or `failed` |
| `amount` | object `{value: string, currency: string}` | always | The micro-transfer amount we observed (decimal string + 3-letter ISO currency) |
| `remitterCountryISO3` | string | always | The remitter person's country, ISO 3166-1 alpha-3. Used by partner UI for compliance display. |
| `failReason` | string | `status=failed` only | Machine-readable reason. Common values: `AMOUNT_MISMATCH`, `AMOUNT_BELOW_MIN`, `CURRENCY_MISMATCH`, `IBAN_MISMATCH`. Treat unknown values as "failed; ask UR ops for translation". |
| `attemptsRemaining` | int | `status=failed` only | How many additional attempts the customer has after this one. `0` means no more attempts will be accepted by `/kyc/penny-transfer`. |
| `exhausted` | bool | `status=failed` only | `true` iff `attemptsRemaining=0`. When `true`, the customer must switch to the NFC fallback path; the penny-drop endpoint will return `PENNY_DROP_MAX_ATTEMPTS_EXCEEDED` for any further calls. The session itself is **not** terminated; an `fma.account.result` may still follow after the NFC path completes. |
| `transactionRecordId` | int64 | always | `ur_transaction_records.id` of the evaluated on-chain fiat-deposit mint. Stable identity for the deposit this result refers to. |
| `txHash` | string | always | On-chain tx hash of the evaluated fiat-deposit mint. |
| `txLogIndex` | int64 | optional | Event ordinal inside the tx; disambiguates when a single tx hash carries multiple mint events. Omitted when not applicable. |
| `occurredAt` | int64 | always | Unix seconds at emission |
#### `fma.kyc.reuse_check.result` (shared-token handoff verdict)
Fires only for partners using the **shared-token (Copy Applicant) KYC reuse** model. It is the async mirror of a handoff attempt's conclusive verdict: emitted once per conclusive attempt for `status ∈ {passed, incomplete}`. **Terminal (non-remediable) verdicts are deliberately NOT webhooked**; the partner learns those from the synchronous handoff response / `POST /api/fma/v1/kyc/check` and UR ops. A lost delivery degrades to polling `/kyc/check`, so this event is fire-and-forget on our side.
```json
{
"event": "fma.kyc.reuse_check.result",
"timestamp": 1735689600,
"data": {
"urId": 1000001234,
"partnerId": "partner_example",
"sessionId": "b3e8ffff-0000-4000-8000-000000000000",
"attempt": 1,
"status": "incomplete",
"correlationId": "…",
"missingFields": ["identity.document", "liveness"],
"requiredLevels": ["id-and-liveness"],
"occurredAt": 1735689600
}
}
```
| Field | Type | Present when | Description |
| ---------------- | ------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `urId` | int64 | always | UR token id |
| `partnerId` | string | always | Your partner id |
| `sessionId` | string (UUID) | always | The handoff session this verdict belongs to |
| `attempt` | int | always | Session-scoped monotonic attempt counter (part of the business key, so redeliveries of the same attempt dedupe) |
| `status` | string | always | `passed` (import accepted) or `incomplete` (remediable; resubmit the missing data and re-handoff) |
| `correlationId` | string | always | Trace id for cross-referencing with UR ops |
| `missingFields` | string\[] | `status=incomplete` only | Dot-path identifiers of the data still required |
| `requiredLevels` | string\[] | optional | Cloned-workflow level names mapped from `missingFields`, when resolvable |
| `occurredAt` | int64 | always | Unix seconds at emission |
#### `fma.kyc.result` (Sumsub review outcome for shared-token flows)
Fires for shared-token / pull / SDK FMA flows when the underlying Sumsub review reaches an outcome. This is the **Sumsub-layer KYC verdict**, distinct from `fma.account.result` (which is the account-*activation* outcome). Branch on `status`.
| `status` | Meaning |
| ---------- | ------------------------------------------------------------------------------------ |
| `pass` | Identity data accepted; the flow has advanced past all Sumsub levels to `SignFormA`. |
| `rejected` | Sumsub returned a hard reject (`RED`). |
| `step_up` | Additional documents requested. (Reserved; not emitted by this path yet.) |
```json
{
"event": "fma.kyc.result",
"timestamp": 1735689600,
"data": {
"urId": 1000001234,
"partnerId": "partner_example",
"status": "rejected",
"rejectCode": "SUMSUB_REJECTED",
"rejectReason": "…",
"occurredAt": 1735689600
}
}
```
| Field | Type | Present when | Description |
| -------------- | ------ | ---------------------- | ----------------------------------------- |
| `urId` | int64 | always | UR token id |
| `partnerId` | string | always | Your partner id |
| `status` | string | always | `pass`, `rejected`, or `step_up` |
| `rejectCode` | string | `status=rejected` only | Machine-readable reject reason |
| `rejectReason` | string | optional | Free-form reason text for support tooling |
| `occurredAt` | int64 | always | Unix seconds at emission |
> Note: `fma.kyc.result` carries no `sessionId`; correlate on `urId` + `occurredAt`.
#### `fma.additional_kyc.required` (ops triggered a partner-driven retry)
Emitted when UR operations decide an already-onboarded customer must resubmit part or all of their KYC. UR seals the customer's current session as it emits this event, so any `sessionId` you still hold stops working. The new session is **not** in the payload: you create it by calling `POST /api/fma/v1/kyc/session/create`, which returns its id.
```json
{
"event": "fma.additional_kyc.required",
"timestamp": 1735689600,
"data": {
"directiveId": "62fb1d29-e584-448f-a770-9454c94dbe24",
"type": "retry",
"taskType": "passport",
"retryLevel": 6,
"fiat24Mode": "ops_offline",
"dataChannel": "sdk",
"partnerId": "partner_example",
"externalUserId": "partner-side-user-id-xyz",
"urId": 1000001234,
"retryOfSessionId": "b3e8ffff-0000-4000-8000-000000000000",
"retryReason": "Compliance review: document expired",
"requiredFields": [],
"deadlineAt": 0,
"createdAt": 1735689600
}
}
```
Field reference:
| Field | Type | Description |
| ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `directiveId` | string (UUID) | Identifies this retry request. Correlates with the `completed` event and with UR support tickets. |
| `type` | string | Always `retry` today; other values are reserved. |
| `taskType` | string | **What the customer must redo**, and the field to branch on: `full`, `passport`, `address_recheck`, or `redo_form_a`. |
| `retryLevel` | int | The retry category ops selected. Advisory; `taskType` is authoritative. Note this is a different quantity from the `retryLevel` returned by `/kyc/session/current`, which counts sessions. |
| `fiat24Mode` | string | `auto_register` or `ops_offline`. Decides whether you finish the session with `POST /kyc/submit`. |
| `dataChannel` | string | `push`, `sdk`, or `shared-token`. Matches your integration path. |
| `partnerId` | string | Your partner id |
| `externalUserId` | string | The partner-side user id you bound to this `urId` at `create-account` time |
| `urId` | int64 | UR token id (unchanged between the original and retry sessions) |
| `retryOfSessionId` | string (UUID) | The session this retry replaces. It is already sealed; calls against it return `SESSION_NOT_FOUND` (`30006`). |
| `retryReason` | string | Free-form reason text suitable for partner-side support tooling (not for direct end-user display) |
| `requiredFields` | string\[] | Push channel only: dot-path identifiers to correct, for example `registerRequest.address.street`. Empty on other channels. |
| `deadlineAt` | int64 | Unix seconds, or `0` when unset. Informational only: UR does not expire the directive or session when it passes, and no event fires at the deadline. |
| `createdAt` | int64 | Unix seconds when the retry was triggered |
Action on receipt: call `POST /api/fma/v1/kyc/session/create` to claim the new session, then drive the customer through the steps `taskType` names. See [Retry KYC](https://docs.ur.app/api-reference/kyc-and-kyb/retry-kyc) for the per-channel walkthrough.
#### `fma.additional_kyc.completed` (retry session finished)
Emitted when the retry session reaches its last step. No further call is required from you.
```json
{
"event": "fma.additional_kyc.completed",
"timestamp": 1735692800,
"data": {
"directiveId": "62fb1d29-e584-448f-a770-9454c94dbe24",
"type": "retry",
"taskType": "passport",
"retryLevel": 6,
"fiat24Mode": "ops_offline",
"dataChannel": "sdk",
"partnerId": "partner_example",
"externalUserId": "partner-side-user-id-xyz",
"urId": 1000001234,
"sessionId": "c0ffee00-0000-4000-8000-000000000000",
"retryOfSessionId": "b3e8ffff-0000-4000-8000-000000000000",
"completedAt": 1735692800
}
}
```
`directiveId`, `taskType`, `retryLevel`, and `fiat24Mode` repeat the values from the `required` event, so the pair matches without a lookup. Two fields differ:
| Field | Type | Description |
| ------------- | ------------- | ---------------------------------------------------------------------------------------- |
| `sessionId` | string (UUID) | The retry session that just completed, the same id `/kyc/session/create` returned to you |
| `completedAt` | int64 | Unix seconds when the session completed |
> Subscribe to **both** `fma.additional_kyc.required` and `fma.additional_kyc.completed`. An unsubscribed event is dropped, so a partner subscribed to only one of the pair silently sees half the flow.
***
## 7. Idempotency and ordering
### 7.1 What to dedupe on
**Dedupe on `X-Webhook-Request-Id`.** That UUID is fixed for the lifetime of a message: every retry sends the same id, and our database uniqueness constraint on `(event_type, partner_id, business_key)` guarantees the same logical event never gets two request ids.
Concretely on your side:
```
on_receive(req):
if already_processed(req.headers["X-Webhook-Request-Id"]):
return 200 OK
verify_signature(req); if !ok: return 401
process(req.body)
mark_processed(req.headers["X-Webhook-Request-Id"], ttl=7d)
return 200 OK
```
### 7.2 What NOT to dedupe on
* The HTTP body, or any subset of fields inside it. Two different business events (e.g. status `activated` and a later status `rejected` for the same session id after a retry flow) can share field values, and you do want to receive both.
* `X-Webhook-Timestamp`: that changes on every retry.
### 7.3 Ordering guarantees
* **Per-partner first-delivery order**: the **first delivery attempts** for messages belonging to one partner go out in the same order they were produced. The internal Kafka topic is partitioned by `partner_id` and a single consumer goroutine per partition processes strictly sequentially, advancing the Kafka offset as soon as each delivery attempt completes (whether success or failure).
* **Retries are out-of-band**: a failed message moves to `PENDING_RETRY` and is re-published to the same partition by a separate retry dispatcher after its backoff. The consumer **does not block on retries**; it proceeds to the next fresh message immediately. As a consequence, **a retry of message A may arrive after a later message B** if B's first delivery happens to succeed while A is still cycling. Build your handler so that re-applying message A after message B's effects is safe.
* **Across partners**: no ordering guarantee.
* **Within an FMA session**: the `fma.account.result` event for a `sessionId` is the **final word** for that session; once you've seen it, no further events for the same `sessionId` will arrive. Earlier `fma.penny_drop.result` events for the same `sessionId` are produced first, but the retry caveat above still applies (a delayed retry could theoretically arrive after `account.result`). If you order on the partner side by `occurredAt`, you'll get the intended chronology even on a delayed retry.
***
## 8. Operations
### 8.1 Rate limits
Per-partner default: 20 requests per second, burst 40. If you can sustain higher and need it, raise it with your UR technical liaison.
### 8.2 IP allowlists
Our outbound IP is stable per Kubernetes deployment but may shift on node rotation. **Allowlist by domain, not by IP.** If you must allowlist by IP, ask for the current allocation in writing and treat it as advisory; we won't notify before rotations.
### 8.3 TLS
Standard CA chain. We don't pin certificates on our side; you don't need to share anything for handshake.
### 8.4 Recovery probing
During incident response our system may re-drive delivery to your endpoint, but it does **not** send a synthetic probe event; there is no `__probe__` event type. Recovery reuses the actual business messages (replayed from the internal Kafka topic), so anything you receive is a real, dedupable event carrying its normal `X-Webhook-Request-Id`. Keep handling every delivery idempotently (see §7); there is no special probe body to special-case.
### 8.5 Cancellation
UR operations can cancel a `PENDING_RETRY` message via internal admin tooling (for example, if a refund / reversal makes an earlier event obsolete). Messages already in flight may still arrive at your endpoint for a few seconds after cancellation. **Treat late arrivals idempotently**; your business-side reconciliation should already handle this.
***
## 9. Troubleshooting
| Symptom | Likely cause | Fix |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Signature verification fails on every webhook | You're re-serializing the body after JSON-parse | Read `req.rawBody` (or framework equivalent); sign over raw bytes, not re-encoded |
| Some webhooks verify, others don't | Two different keys delivered (V1 vs V2 with different message composition); you're using one verifier for both | Implement both verifiers (see [§4.6](#46-verifying-both-versions-during-the-migration-window)) |
| Webhooks for one customer suddenly stop | Your endpoint is returning non-2xx and we hit the 20-attempt cap → `DEAD` | Check your logs at `X-Webhook-Request-Id`; ask UR ops to re-queue |
| Webhooks for ALL customers stop briefly, then resume | Circuit breaker opened on our side after 20 consecutive failures from your endpoint | Look at the 60 s before resumption for the failure mode |
| Same `X-Webhook-Request-Id` arrives 5× in a minute | Your endpoint is timing out (we keep retrying) or returning 5xx | Acknowledge fast; process asynchronously |
| Webhook count is roughly half what you expected | Subscription not enabled for the missing event type | Check your partner contract subscriptions |
| FMA `activated` arrives but customer is not Live on-chain | Should never happen; `activated` is only fired **after** the on-chain status flip and limit-set both confirm | Capture the `X-Webhook-Request-Id` and `sessionId`, contact UR ops |
For unresolved incidents, open a ticket via your UR technical liaison with at minimum:
* `X-Webhook-Request-Id`
* `X-Webhook-Timestamp`
* `X-Webhook-Event-Type`
* The full request body (raw bytes)
* The HTTP status you returned and the response body
***
## 10. Quick reference card
```
POST {your endpoint}
Host: {your domain}
Content-Type: application/json
User-Agent: URBank-Webhook/2.0
X-Webhook-Request-Id: b3e8ffff-0000-4000-8000-000000000000
X-Webhook-Timestamp: 1735689600
X-Webhook-Event-Type: transaction_v2
X-Webhook-Attempt: 1
X-Api-Signature: 0x… (V1, optional in V2-only mode)
X-Api-PublicKey: 0xServerAddress
X-Api-Signature-V2: 0x… (V2, recommended)
X-Api-PublicKey-V2: 0xServerAddress
{"event":"transaction_v2","data":{…},"timestamp":1735689600}
```
Verification message for V2:
```
"1735689600.b3e8ffff-0000-4000-8000-000000000000.{"event":"transaction_v2","data":{…},"timestamp":1735689600}"
```
Return `200 OK` to ack. Return `4xx` to fail permanently. Return `5xx` / time out to retry.
***
## See also
* [Signature and verify](https://docs.ur.app/api-reference/signature-and-verify): generic UR request-signing rules and the signature scheme for the **partner → UR** direction. Note: that doc currently documents only the V1 webhook signature (UR → partner direction); the V2 scheme defined in [§4.2](#42-v2-recommended) of this page is the authoritative webhook reference. The EIP-191 primitive is shared across both directions, but the message composition differs (request-body + deadline for partner → UR; timestamp + request-id + body for V2 webhooks).
* [OpenAPIs](https://docs.ur.app/api-reference): full reference for the partner REST API; `TransactionData` and friends are documented there.
* [Partner integration flow concepts](/welcome/partner-integration-flow-concepts): when each event fires in the customer lifecycle.
* [The user lifecycle](/concepts/overview-the-user-lifecycle): end-to-end customer journey, with webhook touchpoints.
# Build with AI coding agents
Use AI agents to query UR documentation and build integrations faster.
Use AI in your UR integration workflow. We provide tools that give AI agents direct access to our documentation, so you can ask questions, generate code, and build integrations without copy-pasting docs into prompts.
## Install the UR Docs MCP server
Our [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server gives any AI coding assistant direct access to UR documentation. Three tools are available to any connected client:
| Tool | What it does |
| ------------- | ------------------------------------ |
| `search_docs` | Search docs by keyword |
| `get_page` | Get full page content in markdown |
| `list_pages` | Browse all pages and their hierarchy |
### Claude Code
Run in your terminal:
```bash
claude mcp add ur-docs --transport http https://ur-docs-mcp-production.up.railway.app/mcp
```
### Claude Desktop
Add to your config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
```json
{
"mcpServers": {
"ur-docs": {
"url": "https://ur-docs-mcp-production.up.railway.app/mcp"
}
}
}
```
### Cursor
Open **Settings > MCP Servers > Add new server**:
* Name: `ur-docs`
* Type: `HTTP`
* URL: `https://ur-docs-mcp-production.up.railway.app/mcp`
### VS Code (Copilot)
Add to `.vscode/mcp.json` in your project:
```json
{
"servers": {
"ur-docs": {
"url": "https://ur-docs-mcp-production.up.railway.app/mcp"
}
}
}
```
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"ur-docs": {
"serverUrl": "https://ur-docs-mcp-production.up.railway.app/mcp"
}
}
}
```
## Plain text docs
You can access our documentation as plain text at [docs.ur.app/llms-full.txt](https://docs.ur.app/llms-full.txt). This helps AI tools consume our content directly and allows you to paste full documentation context into an LLM.
Plain text is preferable to scraping HTML because:
* Fewer formatting tokens
* LLMs parse and understand markdown hierarchy
* Content hidden in tabs or collapsed sections is included
## Try it
After setting up the MCP server, restart your AI client and try:
* "What is UR and how does the account layer work?"
* "How do I integrate with UR in Managed Custody Mode?"
* "What's the user lifecycle from KYC to card spending?"
* "Search UR docs for tokenized deposits"
Your assistant will search and read our docs to give you an accurate, up-to-date answer.
# Design for UR partners
Design and UX guidance for partners building on UR.
This section helps you present UR's account inside your product and design your co-branded card. It is written for designers and frontend developers.
UR provides a real financial account, not just a wallet: the account layer your users live financially on. The multi-currency card complements the account; it is not the primary product. These guidelines help you position UR correctly, structure your account screens, and design the flows your users will follow.
### User experience
How to position UR's account and card, structure your account screens, and design the account creation, KYC, card, and money movement flows. Start with [Introduction](/design/user-experience/introduction) for what UR provides and what it is not.
### Cards
The artwork specification for your physical and virtual card. See [Co-branded debit card design](/design/cards/co-branded-debit-card-design) to download the template, customize your card, and submit it for approval.
# Introduction
What UR provides, and what it is not.
This guide helps you integrate UR's account in a way that accurately represents the product and creates the best experience for your users.
UR provides a real financial account: a Swiss IBAN account that holds and moves stablecoins and fiat as one, not just a wallet. The multi-currency card is a valuable spending tool that complements the account; it is not the primary product. Following these guidelines helps your users understand the full value of the account and sets the right expectations from the start.
### What UR provides
UR offers a real financial account that lets your users:
* Hold and manage multi-currency balances
* Receive funds via incoming transfer to their Swiss IBAN
* Send funds to external accounts
* Convert digital assets to fiat (off-ramp)
* Convert fiat to digital assets (on-ramp)
* Spend their balance using a multi-currency card
The account is the foundation. The card is a convenient way to access and spend the funds held in that account.
### What UR is not
UR is not primarily a card product or a payment card service. The multi-currency card is a valuable feature, but position it as one of several ways your users can use their account, not as the main offering.
# Messaging hierarchy
What to lead with, what to support with, and what to avoid.
Order your messaging so the account leads and the card supports. This section lists what to emphasize first, what to introduce next, and what to avoid.
### Primary messaging
Lead with the account. Put the total account balance front and center, break it down by currency, and surface the actions that make the account useful: deposit, send, and convert.
### Secondary messaging
Once the account value is established, introduce spending. This is where the multi-currency debit card, card management, and transaction history belong; they round out the account rather than define it.
### What to avoid
Do not position UR primarily as a card. Framing such as "get your crypto card", a payment card service, a crypto card offering, or any card-first value proposition buries the account that funds it.
# Copy guidelines
Recommended terminology for account opening and feature descriptions.
Use account-first language everywhere your users read about UR. The tables below show the wording to use and the wording to avoid.
### Account opening and setup
| Use this | Not this |
| --------------------- | ------------------ |
| "Open your account" | "Apply for a card" |
| "Get started with UR" | "Card application" |
### Feature descriptions
| Use this | Not this |
| ------------------------------------------- | ------------------ |
| "Manage your balance" | "Top up your card" |
| "Deposit funds to your account" | "Card balance" |
| "Send money to any external account" | "Load your card" |
| "Convert crypto directly into your account" | |
| "Spend your balance with a debit card" | |
# Partner positioning of UR
How to introduce UR in banners and provide persistent account access.
Position UR as an embedded financial capability inside your product, not as an external service. This page covers how to introduce UR for acquisition and how to keep the account accessible afterward.
### Banner and marketing placement for introduction and acquisition
Use your introduction surfaces to acquire users into the account, in your brand's voice.
{% columns %}
{% column %}
Lead with the benefit to the user, whether that is faster payouts, better rates, or more control, and mention "real account with a Swiss IBAN" early for credibility. Position UR as an integrated part of your product rather than an external app, and write in your brand's voice, not UR's. Avoid "get the UR card" or "get the partner card" messaging, which sells the card instead of the account.
{% endcolumn %}
{% column %}
Banner example
{% endcolumn %}
{% endcolumns %}
### Fixed entry points for UR account access
Beyond the introduction banner, provide persistent access to UR account features through a fixed entry point on your home screen. A fixed entry point lets your users reach their UR account to check balances and transactions without searching through menus.
{% columns %}
{% column %}
**User benefits:**
* Instant access to account balance
* Quick actions without navigation
* Less friction for frequent actions
{% endcolumn %}
{% column %}
**Partner benefits:**
* Higher feature engagement
* Fewer support queries ("where's my account?")
* Better user retention
* A clear value proposition that stays visible
{% endcolumn %}
{% endcolumns %}
{% columns %}
{% column %}
Example of a fixed entry point
{% endcolumn %}
{% column %}
Another example of a fixed entry point
{% endcolumn %}
{% endcolumns %}
{% hint style="info" icon="figma" %}
Figma reference:\
[**Fixed entry point**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=1-3\&t=HrYv0jeJvqeSoQlT-1)
{% endhint %}
# Visual hierarchy
How much screen prominence to give the account, actions, and card.
Give the account the most visual weight, core account actions the next, and card features the least. Use the prominence split below as a starting point for your account screens.
{% columns %}
{% column %}
* **Account information (60% prominence)**
* Account balance (primary visual element)
* Currency balances
* Recent account activity
* **Core account actions (30% prominence)**
* Deposit funds
* Send funds
* Convert
* **Card features (10% prominence)**
* Card management
{% endcolumn %}
{% column %}
Account page example
{% endcolumn %}
{% endcolumns %}
{% hint style="info" icon="figma" %}
Figma reference:\
[**Account dashboard**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=1-5\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}
# Account creation
The authentication paths for creating a UR account, and the URID.
Your users must establish their UR identity and link it to their account on your platform before they can access account features. This process does two things: account creation mints the [on-chain credential](https://docs.ur.app/api-reference/smart-contracts#account) that represents the UR account and Know Your Customer (KYC) identity, and account linking connects your platform identity to that UR account.
### Two authentication paths
Offer one of two ways to authenticate during account creation.
#### Google Sign-In (recommended)
Google Sign-In is the fastest path. It leans on Google's own authentication and security, so your users skip the CAPTCHA and one-time password (OTP) and never fumble with a verification code.
```mermaid
flowchart LR
A[Continue with Google] --> B[Account created on UR]
```
#### Email authentication
Email authentication works for anyone, with no Google account needed. It takes a few more steps, where you might need to build a CAPTCHA to prevent bots and then an OTP screen to prove email ownership. In exchange, you get more control by not relying on Google Sign-In.
```mermaid
flowchart LR
A[Continue with email] --> B[CAPTCHA to prevent bots]
B --> C[Email OTP verification]
C --> D[Account created on UR]
```
{% hint style="info" icon="figma" %}
Figma reference:\
[**Account creation**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=55-6395\&t=4YF7ojkFUmbkiA7z-1)
{% endhint %}
### URID
The URID is the unique identifier generated when a user creates a UR account. It works like an account number, but it is the `tokenId` of the user's Account NFT on-chain, so anyone can verify it. This makes it the primary identifier for customer support and internal operations: support agents look users up by URID, and it cross-references partner systems against UR infrastructure. Because every URID is unique across all partners, it stays stable no matter which platform the user came through.
#### Technical background
Each UR user is represented on-chain by an Account NFT, and the URID is the `tokenId` of that NFT. That makes it the canonical on-chain identity for the user, not merely a database key: it is a verifiable, immutable identifier rooted in the blockchain.
To understand how Account NFTs are structured and managed, see the [Account section in Smart contracts](https://docs.ur.app/api-reference/smart-contracts#account).
#### Recommended placement
{% columns %}
{% column %}
Your users rarely need the URID in normal operations, but it must stay accessible for support scenarios.
Give it low visual priority so it does not compete with high-priority information or actions.
{% endcolumn %}
{% column valign="bottom" %}
Example of low-priority but always accessible placement of the URID
{% endcolumn %}
{% endcolumns %}
# KYC
The three-part KYC flow and how to show the URID throughout it.
Know Your Customer (KYC) verification lets your users activate their account and unlock full account functionality. The flow has three sequential parts that verify identity, collect required information, and meet regulatory requirements.
For the full account and KYC lifecycle, see [The user lifecycle](https://docs.ur.app/concepts/overview-the-user-lifecycle) in the main UR docs.
### Three-part KYC structure (5 to 10 minutes)
{% stepper %}
{% step %}
**Questionnaire**
Tool: Sumsub\
Purpose: collect user information and assess risk profile\
Duration: 2 to 3 minutes
{% endstep %}
{% step %}
**Biometric ID verification**
Tool: ReadID App Clip (iOS) or ReadID app (Android)\
Purpose: verify document authenticity via NFC chip scanning and a liveness check\
Duration: 2 to 3 minutes
{% endstep %}
{% step %}
**Form A signing**
Purpose: regulatory compliance and consent documentation\
Duration: 1 to 2 minutes
{% endstep %}
{% endstepper %}
### Design principles
#### Transparent expectations
Tell your users what is required before they start: "3 steps: answer questions, scan ID, sign form." Setting expectations reduces anxiety and abandonment.
#### Platform-appropriate tools
Different tools for iOS (App Clip) and Android (full app) optimize for each platform's capabilities while keeping functional parity.
#### Security through familiarity
Established third-party tools (Sumsub, ReadID) build on the trust your users already place in recognized verification providers.
#### Auto-save progress
If a user exits mid-questionnaire, they can resume without restarting.
### Pre-KYC entry point
#### Managed Custody Mode
After a successful UR account creation, your users see the KYC prompt. If they dismiss the prompt or stop midway, they can continue KYC from an account dashboard or equivalent surface on your site.
{% columns %}
{% column %}
After successful account creation and connection, users see the KYC prompt.
{% endcolumn %}
{% column %}
Account dashboard: a card showing "Verify your identity" in the pre-KYC state.
{% endcolumn %}
{% endcolumns %}
{% hint style="info" icon="figma" %}
Figma reference:\
[**KYC**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=61-7302\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}
### Displaying the URID during KYC
The URID is the user's support identifier. During custom partner KYC flows, your users should always be able to read and share this value when they need support.
#### Where the URID comes from
Retrieve the URID by way of `tokenId` from the Account NFT contract by calling `tokenOfOwnerByIndex(userAddress, 0)`.
{% content-ref url="" %}
{% endcontent-ref %}
#### When to display it
Keep the URID on screen for the full duration of KYC: through every step of onboarding, on each retry or failure screen, and until the user either completes KYC or exits the flow.
#### UX recommendations
Keep the URID always visible in a fixed area such as a top bar or sticky footer, with a one-tap way to copy it. Its visual priority should stay low so it does not compete with the primary KYC actions.
# Card activation
Currency authorization and card activation by integration mode.
Card activation bridges account verification and spending capability. This page covers the currency authorization users complete during activation and the authentication patterns that protect card details, for both Managed Custody Mode and External Wallet Access Mode.
### Currency authorization and enablement
For regulatory reasons, your users must authorize currencies for payment. To prevent payments from failing at the point of purchase, include currency authorization in the card activation flow.
{% hint style="success" %}
Enable all currencies by default to maximize payment success. For wallet partners, currencies must be enabled via EIP-7702 to batch the transactions.
{% endhint %}
### Managed Custody Mode
{% hint style="info" icon="figma" %}
Figma reference:\
[**Managed Custody Mode card activation**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=28-107\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}
**Authentication requirement**
Every "View card" action requires re-authentication, for both activated and inactive cards. Card details are highly sensitive information, comparable to physical card access. Gating them protects against unauthorized access: someone with temporary access to an unlocked phone still cannot read the full card number and CVV. It also follows the industry standard set by financial apps, and it builds trust by tying card access to a verification step users recognize. Authentication adds friction, but the trade-off is acceptable because users expect this measure for financial data.
In Managed Custody Mode, users authenticate with their UR credentials (Google Sign-In or email one-time password (OTP)) to view card details, and they activate through your standard authentication flow via UR's webview. Currency authorization is included within the activation flow.
### External Wallet Access Mode
{% hint style="info" icon="figma" %}
Figma reference:\
[**External Wallet Access Mode card activation**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=135-6297\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}
**Authentication requirement**
Every "View card" action requires wallet authentication, for both activated and inactive cards. The same reasoning applies as in Managed Custody Mode: it protects against unauthorized access, follows industry standards, and creates a security ritual that builds trust.
In External Wallet Access Mode, users authenticate with their wallet (for example, biometric or PIN) to view card details. The wallet signature proves ownership and intent. To activate the card, users sign with their wallet, and currency authorization is recommended as part of the activation flow.
Viewing sensitive card data (full number, CVV) requires cryptographic proof of wallet ownership every time.
# Card management
The card hub for security and spending controls.
The card page is the central hub for card security and spending preferences.
{% columns %}
{% column %}
From the card page, your users view their card details, manage currency authorization, monitor spending limits, and control the card's security features.
{% endcolumn %}
{% column %}
Card management example
{% endcolumn %}
{% endcolumns %}
{% hint style="info" icon="figma" %}
Figma reference:\
[**Card management**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=83-4148\&t=HrYv0jeJvqeSoQlT-1)
{% endhint %}
# Off-ramp
Converting digital assets to fiat in the UR account.
UR's off-ramp service lets your users convert digital assets into fiat and deposit the funds directly into their UR account. It connects on-chain value with the regulated financial system, so users can cash out digital assets at competitive rates with transparent fees.
### How it works
Users start an off-ramp transaction from your platform, choosing the digital asset to convert, the amount to cash out, and the destination currency. The converted fiat appears in the UR account balance within minutes, ready to spend with the Mastercard debit card.
{% hint style="info" icon="figma" %}
Figma reference:\
[**Off-ramp**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=29-4447\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}
# Bank transfer
Receiving funds from external bank accounts into the UR account.
UR's bank transfer service lets your users receive funds from external bank accounts held in their own name into their UR account. Users can accept incoming transfers in CHF, EUR, and USD from their personal bank accounts at other financial institutions, which gives them funding options beyond off-ramping digital assets.
### How it works
For security, users authenticate before they can access their IBAN details. They provide these details to their external bank to start a transfer. Funds arrive in the UR account within standard banking timeframes.
{% hint style="info" icon="figma" %}
Figma reference:\
[**Bank transfer**](https://www.figma.com/design/WKbdwKpCGPRaAN43tGXHiN/Partner-UX-Guide?node-id=31-6328\&t=LdSer2mHyoMOtsCs-1)
{% endhint %}
# Co-branded debit card design
Design and submit your custom co-branded Mastercard debit card artwork.
A co-branded card puts your brand on a real UR virtual Mastercard, so your users see something that looks and feels like yours while UR handles issuing and settlement. If you plan to offer cards to your users, follow these steps to design the artwork, license your brand to UR, and submit the card for approval.
The card is virtual. Your users add it to Apple Pay, Google Pay, or a similar wallet and spend it from their phone; there is no physical card to print or ship. The artwork you create here is the face they see in those wallets and inside your app. Approval and compliance review take time, so start early and plan for it ahead of any launch date.
{% stepper %}
{% step %}
**Download and customize the template**
Start from the official Adobe Illustrator template. It is set up with the correct dimensions and safe areas, so your artwork lines up with how the card renders in the app.
{% file src="/files/ABg4DuX5ZQmA7UtJ0Zwo" %}
Choose either the dark or light color scheme as your base, then customize the card surface color to match your brand. Keep every design element inside the dashed safe area; anything outside it can be clipped or interfere with the card's functional zones.
{% endstep %}
{% step %}
**Export your design correctly**
Export a single flattened image that meets the format and compliance requirements. Getting this right avoids a rejection later in approval.
Your final card design must be:
* PNG format
* 1536 × 969 pixels
* The debit mark, included
Do not include any of the following, which either do not apply to a virtual card or are prohibited on Mastercard artwork:
* EMV chip faceplate or contacts
* Magnetic stripe
* Embossed elements
* Transparency overlays
* Holograms
* Rounded corners
* Shading or 3D effects
{% endstep %}
{% step %}
**Authorize use of your brand**
UR needs your permission to display your brand on a Mastercard product. Provide the Copyright Registration documentation for your logo, then complete and sign the Trademark License Agreement below. This grants UR the limited right to reproduce your mark on the card.
{% file src="/files/fhmWVT0o9otGqxIqzU6W" %}
{% endstep %}
{% step %}
**Submit your design to UR for approval**
Send your exported artwork and signed agreement to UR through your dedicated integration channel. UR reviews the design against Mastercard brand standards and the card's functional constraints. Approval takes time, so submit early; UR will tell you if anything needs to change before the card can be issued.
{% endstep %}
{% endstepper %}
# OpenAPIs
Base URLs, environments, and authentication for all UR API endpoints.
## API configurations
### Base URLs
The API is deployed across different environments. Use the appropriate base URL for your integration stage.
| Environment | Base URL |
| -------------- | --------------------------------- |
| **Testnet** | `https://uropenapi-qa.ur-inc.xyz` |
| **Production** | `https://openapi.ur.app` |
### API authentication
The authentication method for the following Core Banking APIs refers to [this document](/api-reference/signature-and-verify#part-a-partner-authentication-ur-open-api-and-webhooks).
## Mint URID
**Endpoint: POST /v1/mint/nft**
Allows the Partner to create a registered user in the UR system via an API call and simultaneously mint a URID NFT for the user.
Before calling this endpoint, first query the Account NFT contract with `tokenOfOwnerByIndex` to check whether the user address already owns an NFT:
* If an NFT already exists, reuse the existing `tokenId` and do not call mint again
* If no NFT exists, call this endpoint to mint a new URID
Calling mint for an address that already has an NFT can return `30001` (the EVM address already has an NFT).
**Request Parameters**:
```json
{
"email": "example@test.com",
"evmAddress": "0xD4FcD82E3589b81A6de532e92E574761CC619531",
"signature": "0x7f561411c39e993c807cd49d336e32bc2ec5e9ca12035a7efaa724ca760f97dc66f45a73b1b5dbf605127ee9ec5989e88972ba6c9a09d3684b0dec436229cc2701",
"hash": "test-hash-1768792402",
"deadline": "1768792702"
}
```
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | string | Yes | User's email address |
| `evmAddress` | string | Yes | User's EVM Wallet Address |
| `signature` | string | Yes | User's wallet signature (EIP-191). See [User authentication](/api-reference/signature-and-verify#part-b-user-authentication-ur-api) for signing details |
| `hash` | string | Yes | A Keccak256 hash of the business payload or a unique message |
| `deadline` | string | Yes | Unix timestamp (seconds) for signature expiration |
**User Signature Generation**:
* Construct base message: `baseMessage = hash + deadline` (string concatenation)
* Generate intermediate hash: `intermediateHash = Keccak256(baseMessage)`
* Construct final message: `finalMessage = "I agree to access my profile. " + intermediateHash.hex()`
* User signs the `finalMessage` using their wallet (EIP-191)
For detailed signing and verification rules, please refer to [Signature and Verification](/api-reference/signature-and-verify).
**Response Example**:
```json
{
"code": 0,
"message": "success",
"data": {
"tokenId": 6021634448,
"txHash": "0xb21c3e15de2f85fad9b04729f6db9ed6477fe08524b4db91a8e35ef2ab08039e"
}
}
```
**Response Field Description**:
* `tokenId`: The minted NFT Token ID, required for all subsequent API calls
* `txHash`: On-chain transaction hash
## Fetch UR Account information
**Endpoint: POST /v1/profile**
Get user profile information including on-chain status and ERC20 authorization information.
**Request Parameters**:
```json
{
"urId": 12345,
"authCode": "UAC_a1b2c3"
}
```
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `urId` | int64 | No | UR user ID, can directly query on-chain information |
| `authCode` | string | No | OAuth authorization code for future extension (can exchange via authorization code when `urId` is missing) |
> **Note**: At least one of `urId` or `authCode` must be provided. Currently, the endpoint primarily uses `urId` for queries, `authCode` field is for future authorization code extension scenarios.
**Response Example**:
```json
{
"code": 0,
"message": "",
"data": {
"urId": 12345,
"chainStatus": 5,
"evmAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"usedLimit": 120000000,
"clientLimit": 500000000,
"startLimitDate": 1714377600,
"allowances": [
{
"tokenSymbol": "USD",
"hasAllowance": true
},
{
"tokenSymbol": "EUR",
"hasAllowance": true
},
{
"tokenSymbol": "CHF",
"hasAllowance": false
},
{
"tokenSymbol": "JPY",
"hasAllowance": true
},
{
"tokenSymbol": "CNH",
"hasAllowance": false
},
{
"tokenSymbol": "SGD",
"hasAllowance": false
},
{
"tokenSymbol": "HKD",
"hasAllowance": false
}
],
"kycRetryVerificationLevel": 0,
"kycRetryVerificationLevelStr": "UNKNOWN",
"kycCurrentStep": 0,
"kycCurrentStepStr": "UNKNOWN",
"bankAccounts": {
"CHF": [
{
"account": "CH93 0000 0000 0001 2345 6",
"bankName": "SR Saphirstein AG",
"bankAddress": "Bellerivestrasse 245, 8008 Zurich, Switzerland",
"bic": "SAHHCHZ2"
}
],
"EUR": [
{
"account": "CH93 0000 0000 0001 2345 6",
"bankName": "SR Saphirstein AG",
"bankAddress": "Bellerivestrasse 245, 8008 Zurich, Switzerland",
"bic": "SAHHCHZ2"
}
]
},
"crsInfo": {
"needCrs": true,
"restrictDate": 1778402365685,
"url": "https://ur-fe2.qa4.gomantle.org/info-provide/crs?hash=D9cEvsYk&source=ur"
}
}
}
```
**Response Field Description**:
* `urId`: UR NFT ID
* `chainStatus`: [On-chain status](https://docs.ur.app/concepts/overview-the-user-lifecycle#user-states)
* `1` - SoftBlocked
* `2` - Tourist
* `3` - Blocked
* `4` - Closed
* `5` - Live (Normal)
* `evmAddress`: User's EVM address
* `usedLimit`: Current Accumulated Usage: The total volume used within the current 30-day billing cycle. This value is retrieved directly from the UR [smart contract ](/api-reference/smart-contracts#account)on-chain.
* The value is denominated in CHF with 2 decimal places (e.g., a return value of `505` represents `5.05 CHF`). This limit is incremented by all fiat-related operations, including Card Spending, FX, On-ramping, and Cash Payouts.
* `clientLimit`: Maximum Monthly Limit: The total spending capacity allocated to the user for a 30-day period.
* The unit and retrieval method are identical to `usedLimit`. Any transaction (FX, Card Spending, On-ramp, or Cash Payout) that exceeds this threshold will be rejected by the smart contract. Partners are highly recommended to perform a pre-transaction check against the user's remaining limit (`clientLimit` - `usedLimit`) before initiating payment flows.
* `startLimitDate`: Limit start timestamp (seconds, UTC)
* `allowances`: ERC20 authorization list (batch queried on-chain via multicall)
* `tokenSymbol`: Token symbol (USD, EUR, CHF, JPY, CNH, SGD, HKD)
* `hasAllowance`: true if allowance has been set, otherwise false
* `kycRetryVerificationLevel`: KYC retry verification level (integer enum)
* `kycRetryVerificationLevelStr`: KYC retry verification level string
* `kycCurrentStep`: KYC current step (integer enum)
* `kycCurrentStepStr`: KYC current step string
* `bankAccounts`: Bank account information, keyed by currency code (e.g., `CHF`, `EUR`). Each currency maps to an array of bank account objects:
* `account`: IBAN account number (generated based on user's NFT ID, Swiss IBAN format)
* `bankName`: Bank name (e.g., `SR Saphirstein AG`)
* `bankAddress`: Bank address
* `bic`: SWIFT/BIC code (e.g., `SAHHCHZ2`)
* `crsInfo`: CRS information :
* `needCrs`: Indicates whether the user is required to complete the CRS process.
* `restrictDate`: Represents the deadline or restriction timestamp for completing the CRS process, usually in Unix timestamp format (milliseconds). After this time, the user may be softBlocked.
* `url`: The CRS submission link that directs the user to the CRS information collection page.
\*\*
**KycRetryVerificationLevel Enum**:
| Value | Name | Description |
| ----- | ------------------------- | ----------------------------------------------------------------- |
| `0` | UNKNOWN | Default value, Normal First KYC |
| `1` | ResetAll | Clear Sumsub + Sign, redo KYC + signature |
| `2` | ResetSumsub | Clear Sumsub KYC info, restart KYC |
| `3` | ResetSign | Clear signature info, re-sign |
| `4` | ResetGPS | Proactive GPS reset (created manually in admin) |
| `5` | RetryGPS | Passive GPS retry (auto-created when GPS fails) **(Deprecated)** |
| `6` | RetryVerificationPassport | Supplement passport info |
| `7` | ResetKYCToReadID | Reset KYC flow, use Sumsub + ReadID to redo KYC **(Deprecated)** |
| `8` | TransactionEdd | Transaction-related EDD questionnaire (created manually in admin) |
**kycCurrentStep Enum**:
| Value | Name | Description |
| ----- | --------- | ------------- |
| `0` | UNKNOWN | Default value |
| `1` | FormA | Form A step |
| `2` | IDScan | ID Scan step |
| `3` | SignFormA | Sign Form A |
| `4` | Review | Review step |
| `5` | Rejected | Rejected |
## Fetch UR Account balance
**Endpoint: POST /v1/balance**
Get user balance information.
**Request Parameters**:
```json
{
"urId": 12345
}
```
| Field | Type | Required | Description |
| ------ | ----- | -------- | ----------- |
| `urId` | int64 | Yes | UR user ID |
**Response Example**:
```json
{
"code": 0,
"message": "",
"data": [
{
"symbol": "USDC",
"amount": "1000.50"
},
{
"symbol": "USD24",
"amount": "5000.00"
}
]
}
```
**Response Field Description**:
* `symbol`: Token symbol
* `amount`: Balance amount, formatted according to Token's `Decimals` precision (e.g., 2 or 6 decimal places)
## Fetch transaction history
**POST /v1/transactions**
Get user transaction records, supports multi-condition filtering and cursor pagination. The endpoint returns top-level pagination markers (`hasNextPage`, etc.) and structured information for each transaction.
**Request Parameters**:
```json
{
"urId": 7639951412,
"chainId": "eip155:5000",
"symbol": "USD24",
"type": "P2P",
"transactionTypes": ["P2P", "FRX"],
"pageSize": 20,
"fromTimestamp": 1701234567,
"toTimestamp": 1704234567,
"direction": "ALL",
"minAmount": "1000",
"maxAmount": "100000",
"status": "completed",
"currencies": ["USD", "EUR"],
"cursorTimestamp": 1702000000,
"cursorId": 123456789,
"prevCursorTimestamp": 1701990000,
"prevCursorId": 123456700
}
```
| Field | Type | Required | Description |
| -------------------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `urId` | int64 | Yes | UR user ID |
| `type` | string | No | Single transaction type filter: P2P, FRX, CTU, CRD, CDP, CWD, CTF |
| `transactionTypes` | \[]string | No | Multiple transaction types filter (mutually exclusive with `type`, which only supports a single value) |
| `chainId` | string | No | Chain ID (e.g., `eip155:5000`) |
| `symbol` | string | No | Token symbol (on-chain Token or fiat 24 series) |
| `currencies` | \[]string | No | Fiat identifier array: EUR, USD, CHF, CNH |
| `pageSize` | int | No | Items per page, default 50, max 100 |
| `fromTimestamp` / `toTimestamp` | int64 | No | Time range filter, Unix seconds |
| `direction` | string | No | Transaction direction: IN, OUT, ALL |
| `minAmount` / `maxAmount` | string | No | Amount range filter (on-chain smallest unit string, follows amount description at the beginning of the document) |
| `status` | string | No | Transaction status filter (pending/completed/rejected/…) |
| `cursorTimestamp` / `cursorId` | int64 | No | Cursor for next page pagination (obtained from previous page's `nextCursor`) |
| `prevCursorTimestamp` / `prevCursorId` | int64 | No | Cursor for previous page pagination (optional) |
**Response Example**:
```json
{
"code": 0,
"message": "",
"data": [
{
"title": "Transfer to Alice",
"subtitle": "#7639",
"amount": "-100.50",
"type": "P2P",
"timestamp": 1704234567,
"currency": "USD",
"direction": "OUT",
"txHash": "0x21b4...",
"chainId": "eip155:5000",
"inputToken": "USD24",
"inputAmount": "100.50",
"status": "completed"
},
{
"title": "Card Payment",
"subtitle": "Merchant ABC",
"amount": "-36.90",
"type": "CRD",
"timestamp": 1704234000,
"currency": "USD",
"direction": "OUT",
"txHash": "0x3051...",
"chainId": "eip155:5000",
"mcc": 5812,
"status": "pending"
}
],
"hasNextPage": true,
"hasPrevPage": false,
"nextCursor": {
"timestamp": 1704233500,
"id": 99887766
},
"prevCursor": {
"timestamp": 1704235000,
"id": 99887700
},
"currentPageSize": 2
}
```
**Response Field Description**:
**Top-level fields**
* `code` / `message`: Status code and description, `0` indicates success.
* `data`: Transaction records array.
* `hasNextPage` / `hasPrevPage`: Whether next/previous page exists.
* `nextCursor` / `prevCursor`: Pagination cursors (next page uses `cursorTimestamp/cursorId`, previous page uses `prevCursorTimestamp/prevCursorId`).
* `currentPageSize`: Number of entries returned in current page.
**Each item in `data` array (same as `/v1/transaction/query`)**
* `title` / `subtitle`: Display title information.
* `amount`: Amount string with sign to indicate direction.
* `type`: Transaction type abbreviation (P2P, FRX, CTU, CRD, CDP, CWD, CTF, etc.).
* `timestamp`: Transaction occurrence Unix seconds.
* `currency`: Token (USD24, EUR24, etc.).
* `direction`: `IN` / `OUT`.
* `txHash`: Transaction hash (if applicable).
* `chainId`: CAIP-2 chain identifier (e.g., `eip155:5000`).
* `image`: Transaction display icon or card logo.
* `inputToken` / `inputAmount` / `inputTokenAddress`: Original chain info for cross-chain transactions like CTU, CSW.
* `outputAmount`: Amount after FRX/CSW exchange.
* `token` / `tokenAddress`: Token and contract address involved in certain card or aggregated transactions.
* `mcc`, `reference`, `bankAccount`: Fields specific to card payments or bank transfers.
* `crdMultiToken`, `ctuExternalSender`, `fromAddress`, `toAddress`, etc.: Additional fields attached by transaction type.
* `status`: `pending` / `completed` / `rejected` / `unknown`.
* `statusCode` / `crdCurrency`: Card-returned status code, original currency, and other supplementary info.
* `listingTitle`, `txHashUrl`, `txIdIcon`, `officialName`: Supplementary fields for client display.
## Fetch transaction details
**POST /v1/transaction/query**
Query aggregated transaction details based on on-chain transaction hash, supports single or multiple hashes.
The `txHash` field accepts both **EVM transaction hashes** (`0x`-prefixed hex) and **Solana transaction signatures** (Base58-encoded, 32–88 characters). The server auto-detects the format.
**Request Parameters**:
```json
{
"txPairs": [
{
"urId": 7639951412,
"txHash": "0x1234567890abcdef..."
},
{
"urId": 7639951412,
"txHash": "65ocipMENgErDtSxqo16J2JY8V2raAHeMLDgQNnRibbe5dc4JsENok34dWgcoh1qgBQwEi54jcSejgW6RsQB7S5s"
}
]
}
```
| Field | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `txPairs` | array\