Skip to main content

Logging in and verifying users

Every screen in your app that touches money sits behind an authenticated user. This page covers the two things you build first: verifying a customer so they're allowed to hold funds, and authenticating the people who act on that customer's behalf.

Weavr is not your app's identity provider

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.

Where this fits

This is the foundation of the embedded app blueprint. Cards, payments, and trusted payeesTrusted Payee A 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 pinPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. maps a part of the screen to the Weavr secure component that renders it or the API endpoint behind it:

your app

Sign in

Welcome back

Password
•••••••••
SDK componentform.input("password", "password")PasswordCaptures the password inside a tokenized secure field so the raw value never reaches your servers.View docs →
Log in
API · data sourcePOST/login_with_passwordLog inYour backend exchanges the tokenized credential for an end-user Auth Token that carries the session.View docs →
SDK component (renders the area)API endpoint (the data source)

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 who authenticates against Weavr and acts on the customer's behalf - the root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. who created the customer, or an authorised user they invited.

Your app authenticates users against Weavr for the regulated operations they perform - it's a security layer on top of your own sign-in, not your app's account system. The API then acts on the customer's instrumentsInstrument A financial product owned by an Identity. 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 two 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 user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user.'s credentials context and returns an Auth Token you use to continue.

POST/corporatesTry it 
{
  "profileId": "string",
  "tag": "string",
  "rootUser": {
    "name": "string",
    "surname": "string",
    "email": "[email protected]",
    "mobile": {
      "countryCode": "stri",
      "number": "string"
    },
    "companyPosition": "DIRECTOR",
    "dateOfBirth": {
      "year": 1900,
      "month": 1,
      "day": 1
    },
    "tag": "string"
  },
  "company": {
    "type": "SOLE_TRADER",
    "businessAddress": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st"
    },
    "name": "string",
    "registrationNumber": "string",
    "registrationCountry": "st"
  },
  "industry": "ACCOUNTING",
  "sourceOfFunds": "LABOUR_CONTRACT",
  "sourceOfFundsOther": "string",
  "acceptedTerms": true,
  "ipAddress": "string",
  "baseCurrency": "str",
  "feeGroup": "string"
}
POST/consumersTry it 
{
  "profileId": "string",
  "tag": "string",
  "rootUser": {
    "name": "string",
    "surname": "string",
    "email": "[email protected]",
    "mobile": {
      "countryCode": "stri",
      "number": "string"
    },
    "dateOfBirth": {
      "year": 1900,
      "month": 1,
      "day": 1
    },
    "occupation": "ACCOUNTING",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st"
    },
    "placeOfBirth": "string",
    "nationality": "st",
    "tag": "string"
  },
  "ipAddress": "string",
  "acceptedTerms": true,
  "baseCurrency": "str",
  "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 Business entities that can be onboarded as identities on Weavr. Corporate identities 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 Individual persons who can be onboarded as identities on Weavr. Consumer identities represent individual customers and 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 - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved 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.

Test without real documents

In the sandbox, approve KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. and KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved 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 Assignee The 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 to authenticate. Either way it's captured through a Weavr login component, which tokenizesTokenize Replace 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.
Present it as a security key, not a second login

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 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 completes the login and receives the end-user Auth Token:

POST/login_with_passwordTry it 
{
  "email": "[email protected]",
  "password": {
    "value": "pa$$word"
  }
}

For the full flow - including exchanging an Auth Token for an Access Token when a user is linked to multiple identities - see end-user authentication and the authentication overview.

Carry the session on every call​

From here on, every call your app makes on the customer's behalf carries two credentials:

CredentialWhat it identifiesWhere it comes from
api-key: YOUR_API_KEYYour app (the account)Embedder PortalEmbedder Portal A web-based portal where embedders can access their Weavr account, manage API credentials, configure settings, view dashboards, and access documentation. The portal provides access to both sandbox and production environments, with separate credentials for each. → API Credentials
Authorization: Bearer YOUR_TOKENThe logged-in userReturned by POST /login_with_password
Sessions expire after 5 minutes of inactivity

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 - 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.

Plan platforms against capabilities

Biometric login, push-notification step-up, and push provisioningPush Provisioning A 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.