Verifying users
Every screen in your app that touches money sends authenticated API requests. This page covers the two things you build first: verifying a customer so they're allowed to hold funds, and verifying the people who act on that customer's behalf.
Your app keeps its own sign-in. Many customers use it for months before they ever touch a financial feature, and Weavr doesn't replace that login. A Weavr user is created the first time a customer reaches a financial feature - typically when they set up their first card - and the credential they set at that moment exists for one reason: Strong Customer Authentication. Regulation requires Weavr, as the regulated institution, to authenticate the end user directly for payment operations, and that obligation can't be delegated to your app. So treat everything that follows as the security layer behind your app's own login, not a replacement for it.
This is the foundation of the embedded app blueprint. Cards, payments, and trusted payeesTrusted PayeeA trusted recipient for payments, including the business or individual's details and their bank account or instrument details. Sending to a Trusted Payee may let customers skip Strong Customer Authentication (SCA) on Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. Previously referred to as a Beneficiary. all require a verified customer and an authenticated end-user, so build this first.
Here's the screen you'll build. Each pin maps a part of the screen to the Weavr secure component that renders it or the API endpoint behind it:
Sign in
Welcome back
Hover or focus a numbered pin to see which Weavr secure component renders the area, or which API endpoint supplies its data - then click to open the docs.
Customers and users
Weavr draws a line between the two:
- A customer is the verified business (corporate) or person (consumer) that owns the accounts, cards, and funds.
- A user is a person whose credentials Weavr verifies before they act on the customer's behalf - the root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. who created the customer, or an authorised user they invited.
Your app verifies users' Weavr credentials for the regulated operations they perform - it's a security layer on top of your own sign-in, not your app's account system. A corporate user can act for more than one corporate and can have a different role on each. The API acts on the selected customer's instrumentsInstrumentA financial product owned by a customer. There are two types: Managed Accounts (stored-value accounts that hold balances and can receive wire transfers) and Managed Cards (prepaid cards - virtual or physical - used for purchases).. Keep the user, customer, and membership between them separate in your data model from day one.
Step 1: Onboard and verify the customer
Before a customer can hold funds, you create them and run compliance checks.
Create the customer
Your backend creates the customer with your API key. The response includes the root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user.'s credentials context and returns an Auth Token you use to continue.
/corporates /corporates{ "idempotency-ref": "transfer-2026-08-07-001"}{ "profileId": "10001", "tag": "customer-123", "rootUser": { "name": "string", "surname": "string", "email": "[email protected]", "mobile": { "countryCode": "+44", "number": "7700900123" }, "companyPosition": "DIRECTOR", "dateOfBirth": { "year": 1990, "month": 1, "day": 1 }, "tag": "customer-123", "locale": "en-GB", "brand": "Acme" }, "company": { "type": "SOLE_TRADER", "businessAddress": { "addressLine1": "1 High Street", "addressLine2": "Flat 2", "city": "London", "postCode": "W1A 1AA", "state": "Greater London", "country": "GB" }, "name": "string", "registrationNumber": "string", "registrationCountry": "string" }, "industry": "ACCOUNTING", "sourceOfFunds": "LABOUR_CONTRACT", "sourceOfFundsOther": "string", "acceptedTerms": true, "ipAddress": "string", "baseCurrency": "GBP", "feeGroup": "string"}/consumers /consumers{ "idempotency-ref": "transfer-2026-08-07-001"}{ "profileId": "10001", "tag": "customer-123", "rootUser": { "name": "string", "surname": "string", "email": "[email protected]", "mobile": { "countryCode": "+44", "number": "7700900123" }, "dateOfBirth": { "year": 1990, "month": 1, "day": 1 }, "occupation": "ACCOUNTING", "address": { "addressLine1": "1 High Street", "addressLine2": "Flat 2", "city": "London", "postCode": "W1A 1AA", "state": "Greater London", "country": "GB" }, "placeOfBirth": "string", "nationality": {}, "tag": {}, "locale": "en-GB", "brand": "Acme" }, "ipAddress": "string", "acceptedTerms": true, "baseCurrency": "GBP", "feeGroup": "string", "sourceOfFunds": "PERSONAL_SAVINGS", "sourceOfFundsOther": "string"}Follow the full walkthrough for each type: create a corporate or create a consumer.
Verify with KYB or KYC
Compliance verification is where the SDK earns its keep. Identity documents and business details are collected inside a Weavr secure component, so the sensitive data never lands on your servers.
- CorporatesCorporates (Corporate Identity). Business entities that can be onboarded as customers on Weavr. Corporate customers represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees. run KYB (Know Your Business) through our web KYB component, which also covers stakeholder due diligence for directors and beneficial owners. On mobile, embed the same component in a webview.
- ConsumersConsumers (Consumer). Individual people who can be onboarded as customers on Weavr. Consumer customers require Know Your Customer (KYC) verification. For consumers, the card owner and card assignee are typically the same person. run KYC (Know Your Customer). Mount the KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. component: Web, iOS, Android, React Native.
Verification runs asynchronously. Subscribe to the corporate or consumer webhook events to learn when a customer becomes verified, and gate the rest of your app on that state.
In the sandbox, approve KYBKYB (Know Your Business). Know Your Business - the identity verification process for corporate customers. This process allows you to securely verify your business customer's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. and KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. instantly with the Simulator instead of uploading real identity documents.
Invite the people who use the app
A customer usually has more than one person acting on it - a finance administrator, employees who carry cards, an approver for payments. Invite each as an authorised user and assign a role that scopes what they can do. For example, our pre-configured Card AssigneeCard AssigneeThe person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users. role onboards a cardholder without giving them access to the rest of the customer's finances.
Step 2: Set up and use the Weavr credential
The first time a user reaches a financial feature they set a Weavr credential; on every later visit they re-enter it so Weavr can verify them. Either way it's captured through a Weavr login component, which tokenizesTokenizeReplace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. the value inside a sandboxed field and hands your backend a one-time token to exchange for a session.
We support two factors:
- Password - a full-strength secret. See the complexity requirements.
- Passcode - a 4-digit code, suitable when your app already authenticates the user another way.
This credential isn't your app's login, so don't label it "password" or "log in" for your customer - that wording implies a separate account they don't have. Collect it, and ask for it again, inside your own already-authenticated screens, framed as a security key for their card or account. EmbeddersEmbedder (Embedded Finance Provider). A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers. commonly call it a backup key or card key, with copy like "To secure your card, set up a backup key." The regulated password lives underneath; the customer still sees one app with one sign-in.
Mount the login component on your platform:
- Web - password and passcode fields, each with a paired confirm component for sign-up flows.
- iOS, Android, React Native - the same factors, plus biometric login on mobile.
Your backend uses the tokenizedTokenizeReplace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. credential to verify the user and receives an end-user token:
/login_with_password /login_with_password{ "email": "[email protected]", "password": { "value": "Passw0rd!" }}Inspect tokenType in every verification response. If it is ACCESS, the token is already scoped to the user's only active identity. If it is AUTH, retrieve the user's identities, let them select one, and exchange the token for an identity-scoped Access Token. A user who has one identity today can gain another later, so handle both results from the start.
Follow end-user authentication for the complete flow, including switching identities without another credential verification.
Authenticate each API request
From here on, every call your app makes on the customer's behalf carries two credentials:
| Credential | What it identifies | Where it comes from |
|---|---|---|
api-key: YOUR_API_KEY | Your app (the account) | Embedder PortalEmbedder PortalA web-based portal where embedders manage their Weavr account: browse customers and instruments, configure programmes, find API credentials and profile IDs, run Sandbox simulations, and inspect webhook deliveries. Sandbox and Live are separate, with their own credentials and data. → account menu → API clients |
Authorization: Bearer YOUR_TOKEN | The user and selected customer | Returned by login or POST |
End-user tokens expire after 5 minutes of inactivity and there is no refresh endpoint - the user must log in again. Design your UX around user activity: prompt the user to act while a minute of the session remains, rather than waiting for a 401. See end-user authentication.
Step 3: Step up for sensitive actions
Some actions carry more risk than logging in - viewing a full card number, moving money to a new payee, changing a password. Under PSD2, these need Strong Customer Authentication (SCASCA (Strong Customer Authentication). Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics).), which Weavr implements as step-up: the same session, re-authenticated with a second factor.
You trigger step-up, the user clears a second factor, and their token is upgraded. The upgraded token unlocks the gated endpoint.
Second factors by platform:
- SMS OTP - available on every platform. The user receives a code and enters it in a login/OTP component.
- Push notification and biometrics - mobile only.
Build the OTP entry screen with the login component on Web, iOS, Android, or React Native, and follow step-up authentication for the full list of gated endpoints and how to perform the upgrade.
Biometric login, push-notification step-up, and push provisioningPush ProvisioningA method that allows cardholders to add their card to a digital wallet (such as Apple Pay or Google Pay) directly from your app. The card details are securely tokenized and sent to the wallet provider, streamlining the process and enhancing the user experience compared to manual provisioning. This feature is currently in beta. are mobile-only. Check the SDK capability matrix before you decide which screens each platform delivers.
What you've built
At this point your app can onboard a customer, verify them, and log a user in with an active session that can be stepped up on demand. That session is the currency for everything that follows.
Next, put it to work: issue and manage cards.