Quickstart guide

Get your first Weavr integration working end-to-end. This guide takes you from zero to processing your first transaction with a complete, hands-on approach.

New to Weavr?

Read How Weavr works first for an overview of the core concepts like customers, 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)., and Transactions.

Customers and your app's users

A customer in the Weavr platform is separate from the account a customer signs in to in your own app. The customer is the regulated record that holds accounts, cards, and payment permissions, and the end user authenticates against it directly - Strong Customer Authentication can't be delegated to your app. Even so, your customer should experience a single app and a single set of credentials. See Customers and your app's users for how the two relate.

What you'll build

By the end of this guide, you'll have:

• A working API connection to Weavr
• A corporate created and verified
• A managed accountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. with funds
• A virtual cardVirtual CardA payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. issued and ready to use
• Your first successful transaction processed

Download our postman collection

All the steps mentioned in this guide are also included in a postman collection, available from the Developers tab in your 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.. Here you'll also find an Environment file, containing all your profileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. IDs that can be uploaded directly to postman. Then simply follow the sequence of one of our pre-approved payment models, such as "Smarter Expenses"

Prerequisites

Before you start, you'll need:

1. Development environment

• Command line access (Terminal, Command Prompt, or PowerShell)
• cURL installed (or your preferred API client, like Postman)
• Text editor for viewing responses

2. Weavr sandbox account

If you don't have one yet, contact the Weavr team to get your sandbox environment set up.

3. API credentials ready

From your Embedder Portal, fetch and save the values listed below: your programmeProgrammeA programme represents your application within Weavr. Everything you create - customers, instruments, and transactions - sits beneath a programme. When you register as an Embedder, you receive a programme in the Sandbox and, once approved, one in Live. A programme is not a Workspace: a workspace is your company's account, and it can hold several programmes. ID from Developers > API credentials, your profileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. IDs from Developers > Profile IDs, and your API key from API clients in the account menu. For details on what each one is and where it's used, see Keys and IDs.

📋 Program ID (example: 115079696319971359)
📋 API Key (base64-encoded, example: dpcYgcIKBp8BmNhfxHYBIQ==)
📋 ProfileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. IDs (all numeric):

• Corporate ProfileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. ID (example: 115079696331702303)
• Managed AccountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. ProfileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. ID (example: 115079696351297567)
• Managed CardManaged CardA payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User. ProfileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. ID (example: 115079696398155807)
• Transfer ProfileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. ID (example: 115079696434790431)
• Outgoing Wire TransferWire TransferA transaction that moves funds between accounts. An incoming wire transfer moves funds from a third-party bank account to a Weavr managed account, while an outgoing wire transfer moves funds from a Weavr managed account to a third-party bank account. Wire transfers require the managed account to have an assigned IBAN (for EUR) or sort code and account number (for GBP). ProfileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. ID (example: 115079696444882975)

Save your credentials

Copy your values now - you'll need them for API calls. Store them securely and never commit them to version control.

✅ Checkpoint: You should have your Program ID, API key, and all ProfileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. IDs ready before proceeding.

⚙️

API Environment Variables

0/13 configured

Which header goes where

The quickstart uses three auth conventions. Knowing when each applies is the single biggest 401-prevention you can do up front:

Header	Used by	Source	Example call in this guide
api-key: YOUR_API_KEY	Every MultiMultiWeavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise. API call (create corporate, login, accounts, cards, …)	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	All sandbox.weavr.io/multi/… calls
Authorization: Bearer YOUR_TOKEN	Authenticated end-user calls - needed once the user is logged in	Returned by POST /login_with_password (or the password-create endpoint)	Step 3 onwards
programme-key: YOUR_API_KEY *	Sandbox simulator endpoints (sandbox.weavr.io/simulate/api/…)	Same value as your API key - but a different header name	Step 3's "Verify corporate (sandbox simulation method)" and the deposit / card purchase simulator calls

* The simulator examples in this guide use program-key; both spellings are accepted in sandbox. Reference docs use programme-key, matching the Simulator OpenAPI.

Rule of thumb: if the URL contains /simulate/api/, you're talking to the sandbox simulator, which uses programme-key. Everywhere else, api-key plus (once you have one) the bearer token.

If a request returns 401, check the header name first - it's the single most common cause.

---

Step 1: Test API connection

Verify your setup works by making your first API call. Test connectivity by sending an empty request to the login endpoint. The validation errors confirm your API connection is working.

Test API Connection

curl -X POST "https://sandbox.weavr.io/multi/login_with_password" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response (connectivity confirmed!)

{
  "message": "Bad Request",
  "_links": {
    "self": {
      "href": "/multi/login_with_password",
      "templated": false
    }
  },
  "_embedded": {
    "errors": [
      {
        "message": "request.email: must not be blank"
      },
      {
        "message": "request.password: must not be null"
      }
    ]
  }
}

✅ Checkpoint Getting validation errors means your API key works and connectivity is established.

Troubleshooting connection issues

Getting {"invalidFields":[{"error":"REQUIRED","fieldName":"api-key"}]}?

• Check your API key is correct
• Verify the api-key header format: api-key: YOUR_API_KEY
• Ensure you're using the correct API key from API clients in the 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.

Getting a different error message?

• Any validation errors about missing fields: ✅ success. API connection working.
• 401 Unauthorized: check your API key is valid.
• 500 Internal Server Error: API issue, try again in a moment.

✅ Checkpoint: You should see validation errors about missing required fields, confirming your API connection works.

---

Step 2: Create corporate

Now create a corporate (business) that will own accounts and cards. Choose your region based on your corporate profileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. configuration.

POST/corporatesOpen API reference →

/corporates

{  "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"}

Create the corporate

🇪🇺 EU Company (e.g. Germany)

Create a German corporate

curl -X POST "https://sandbox.weavr.io/multi/corporates" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "profileId": "YOUR_CORPORATE_PROFILE_ID",
  "baseCurrency": "EUR",
  "ipAddress": "192.168.1.1",
  "company": {
    "name": "QuickStart Demo GmbH",
    "type": "LLC",
    "registrationNumber": "HRB 123456",
    "registrationCountry": "DE",
    "businessAddress": {
      "addressLine1": "Friedrichstraße 123",
      "city": "Berlin",
      "postCode": "10117",
      "country": "DE"
    },
    "industry": "TECHNOLOGY"
  },
  "rootUser": {
    "name": "Hans",
    "surname": "Müller",
    "email": "YOUR_ROOT_USER_EMAIL",
    "companyPosition": "DIRECTOR",
    "mobile": {
      "countryCode": "+49",
      "number": "1701234567"
    },
    "dateOfBirth": {
      "year": 1990,
      "month": 5,
      "day": 15
    },
    "placeOfBirth": {
      "country": "DE"
    },
    "address": {
      "addressLine1": "Friedrichstraße 123",
      "city": "Berlin",
      "postCode": "10117",
      "country": "DE"
    },
    "nationality": "DE"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

🇬🇧 UK Company

Create a UK corporate

curl -X POST "https://sandbox.weavr.io/multi/corporates" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "profileId": "YOUR_CORPORATE_PROFILE_ID",
  "baseCurrency": "GBP",
  "ipAddress": "192.168.1.1",
  "company": {
    "name": "QuickStart Demo Ltd",
    "type": "LLC",
    "registrationNumber": "12345678",
    "registrationCountry": "GB",
    "businessAddress": {
      "addressLine1": "123 Demo Street",
      "city": "London",
      "postCode": "SW1A 1AA",
      "country": "GB"
    },
    "industry": "TECHNOLOGY"
  },
  "rootUser": {
    "name": "Priya",
    "surname": "Patel",
    "email": "YOUR_ROOT_USER_EMAIL",
    "companyPosition": "DIRECTOR",
    "mobile": {
      "countryCode": "+44",
      "number": "7123456789"
    },
    "dateOfBirth": {
      "year": 1990,
      "month": 5,
      "day": 15
    },
    "placeOfBirth": {
      "country": "GB"
    },
    "address": {
      "addressLine1": "123 Demo Street",
      "city": "London",
      "postCode": "SW1A 1AA",
      "country": "GB"
    },
    "nationality": "GB"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response (EU example shown - UK responses substitute the values from the UK tab):

{
  "id": {
    "id": "115134292391559225",
    "type": "CORPORATE"
  },
  "profileId": "115079696331702303",
  "creationTimestamp": 1756809885699,
  "company": {
    "name": "QuickStart Demo GmbH",
    "type": "LLC"
  },
  "rootUser": {
    "id": {
      "id": "115134292391559225",
      "type": "USER"
    },
    "name": "Hans",
    "surname": "Müller"
  }
}

📝 Save these values:

• id.id: Your corporate ID (example: 115134292391559225)
• rootUser.id.id: Your 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. ID (example: 115134292391559226)

📝

Update your credentials

Copy the values from your response above. The email should match what you used in the corporate creation. These will auto-populate in all remaining steps!

Corporate ID:

Copy id.id from the response above

Root User ID:

Copy rootUser.id.id from the response above

💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

Region-specific profiles

Getting COUNTRY_UNSUPPORTED error?

• Your corporate profileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. may be configured for a different region
• Try switching between the EU and UK tabs above
• EU profilesProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. typically support: DE, FR, IT, ES, NL, etc.
• UK profilesProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. support: GB only
• Contact support if you need to change your profileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. configuration

Other errors you might hit here

Conflict errors return HTTP 409 with a body like {"errorCode": "ROOT_EMAIL_NOT_UNIQUE"}:

• ROOT_EMAIL_NOT_UNIQUE: 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. email is already registered - each run of this guide needs a fresh email address.
• PROFILE_NOT_FOUND: the profileId doesn't belong to the programmeProgrammeA programme represents your application within Weavr. Everything you create - customers, instruments, and transactions - sits beneath a programme. When you register as an Embedder, you receive a programme in the Sandbox and, once approved, one in Live. A programme is not a Workspace: a workspace is your company's account, and it can hold several programmes. your API key is for - re-check both against the Developers > Profile IDs page.
• MOBILE_OR_COUNTRY_CODE_INVALID: the mobile country code and number combination isn't valid - check the format against the example payload.

Follow your progress in the embedder portal

You can see the corporate that was created via the UI of the 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.. In later steps you will also be able to see the account and card that is created, and the transactions you make.

✅ Checkpoint: You should have a corporate ID and 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. ID saved.

---

Step 3: Set root user credentials, and verify the customer

Your corporate root-user needs a password, and needs to verify their email and phone number (which will be used for step-up authentication). The corporate must also complete 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. before it can be used.

Set root user password

POST/passwords/{user_id}/createOpen API reference →

/passwords/987654321/create

{  "password": {    "value": "Passw0rd!"  }}

Set Root User Password

curl -X POST "https://sandbox.weavr.io/multi/passwords/YOUR_ROOT_USER_ID/create" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "password": {
    "value": "SecurePass123!"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response:

{
  "passwordInfo": {
    "expiryDate": 0,
    "identityId": {
      "id": "115134345423749179",
      "type": "CORPORATE"
    }
  },
  "token": "eyJraWQiOiJnZW5lcmF0b3IiLCJhbGciOiJFUzI1NiJ9..."
}

✅ Checkpoint: Password info and an auth token is returned. You can use this token for the next steps, or to log in separately.

📝

Update your credentials

Copy the token from your response above. This will auto-populate in all remaining steps!

Auth Token:

Copy token from the login response above

💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

If the password call returns 409

• PASSWORD_ALREADY_CREATED: this 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. already has a password - log in instead with POST /login_with_password (shown in Step 4) to get a token.
• PASSWORD_TOO_SIMPLE: the password doesn't meet complexity rules - use a longer mix of upper and lower case letters, numbers, and symbols.

Send an email verification code to the root user

POST/corporates/verification/email/sendOpen API reference →

/corporates/verification/email/send

{  "email": "[email protected]"}

Send an email verification code to the root user

curl -X POST "https://sandbox.weavr.io/multi/corporates/verification/email/send" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "email": "YOUR_ROOT_USER_EMAIL"
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response: You should receive HTTP 204 (No Content).

Verify email of the root user

POST/corporates/verification/email/verifyOpen API reference →

/corporates/verification/email/verify

{  "email": "[email protected]",  "verificationCode": "123456"}

Verify email of the root user

curl -X POST "https://sandbox.weavr.io/multi/corporates/verification/email/verify" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "email": "YOUR_ROOT_USER_EMAIL",
  "verificationCode": "123456"
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response: You should receive HTTP 204 (No Content).

Enroll mobile number for SMS

Factor enrolment vs step-up challenge

This step (and the next) enrols 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 mobile number as an SMS authentication factor — a one-time setup that registers the channel against the user. Later, in Step 4, you'll trigger a step-up challengeStep-up challengeA two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. (/stepup/challenges/otp/SMS) using that enrolled factor.

Flow	Endpoint family	When it runs	What it changes
Factor enrolment	/authentication_factors/otp/SMS	Once per user, during onboarding	Registers the SMS channel against the user
Step-up challengeStep-up challengeA two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations.	/stepup/challenges/otp/SMS	Every time the user accesses a protected resource	Steps up the current auth token

Both use the same sandbox verification code (123456), which is a frequent source of confusion when reading the logs.

POST/authentication_factors/otp/{channel}Open API reference →

/authentication_factors/otp/SMS

Enrol mobile number for SMS

curl -X POST "https://sandbox.weavr.io/multi/authentication_factors/otp/SMS" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n"

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Verify the enrollment

POST/authentication_factors/otp/{channel}/verifyOpen API reference →

/authentication_factors/otp/SMS/verify

{  "verificationCode": {}}

Verify SMS enrolment

curl -X POST "https://sandbox.weavr.io/multi/authentication_factors/otp/SMS/verify" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "verificationCode": "123456"
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Sandbox Step-Up

In sandbox mode, use this verification code: 123456 (no SMS is actually sent)

Verify corporate (sandbox simulation method)

In sandbox, you can instantly verify your corporate using the Simulator API to bypass 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. checks:

Simulator API

This step uses our Simulator API which is only available in sandbox environments for testing purposes. In production, 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. go through full 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. verification.

Verify Corporate

curl -X POST "https://sandbox.weavr.io/simulate/api/corporates/YOUR_CORPORATE_ID/verify" \
-H "program-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n"

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

✅ Checkpoint: You should receive HTTP 204 (No Content). Your corporate is now verified and can create accounts.

---

Step 4: Create a managed account

Step-up authentication required

Before creating accounts and cards, you need to log in and complete step-up authentication. This is a security requirement for accessing and completing sensitive operations.

Log in as root user

Already have a token?

If you saved the token from the password creation response, you can skip this login step and use that token directly.

POST/login_with_passwordOpen API reference →

/login_with_password

{  "email": "[email protected]",  "password": {    "value": "Passw0rd!"  }}

Log in as root user

curl -X POST "https://sandbox.weavr.io/multi/login_with_password" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "email": "YOUR_ROOT_USER_EMAIL",
  "password": {
    "value": "SecurePass123!"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected login response:

{
  "token": "eyJraWQiOiJnZW5lcmF0b3IiLCJhbGciOiJFUzI1NiJ9...",
  "identity": {
    "id": "115134312111276089",
    "type": "CORPORATE"
  }
}

📝

Save auth token

Copy the token value from the login response above. This will be used for all subsequent API calls.

Auth Token:

Copy token from the login response above

💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

Initiate a step-up challenge via SMS

Different flow from factor enrolment

The SMS channel you enrolled in Step 3 is now being used to step up the auth token. The endpoint family is different (/stepup/challenges/otp/SMS vs /authentication_factors/otp/SMS) and the effect is different — step-up changes the current token's permissions rather than registering a new factor. See Step-up authentication for the full mental model.

POST/stepup/challenges/otp/SMSOpen API reference →

/stepup/challenges/otp/SMS

Initiate step-up challenge

curl -X POST "https://sandbox.weavr.io/multi/stepup/challenges/otp/SMS" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n"

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Sandbox Step-Up

In sandbox mode, use this verification code: 123456 (no SMS is actually sent)

Verify the step-up challenge

POST/stepup/challenges/otp/SMS/verifyOpen API reference →

/stepup/challenges/otp/SMS/verify

{  "verificationCode": {}}

Verify step-up challenge

curl -X POST "https://sandbox.weavr.io/multi/stepup/challenges/otp/SMS/verify" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "verificationCode": "123456"
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

✅ Checkpoint: You should receive HTTP 204 response. Your token is now stepped-up and ready to be used for sensitive operations.

Token lifetime and logout

Your token behaves like a short-lived session, so keep three things in mind before you build on it:

• Lifetime: tokens expire after 5 minutes of inactivity. Each API call resets the timer.
• Refresh: there is no refresh endpoint. Once a token expires, log in again with POST /login_with_password (and step up again for sensitive operations).
• Logout: to end a session explicitly, call POST /logout with the token in the Authorization header. Do this when your user signs out of your app instead of waiting for expiry.

If your token expires while you work through the remaining steps, repeat the login and step-up calls from this step. See Get an access token for the full session model.

Create the managed account

Now create an account that can hold funds and process transactions.

POST/managed_accountsOpen API reference →

/managed_accounts

{  "profileId": "10001",  "friendlyName": "string",  "currency": "GBP",  "tag": "customer-123",  "lowBalanceThreshold": 10000}

🇪🇺 EUR Account

Create EUR Managed Account

curl -X POST "https://sandbox.weavr.io/multi/managed_accounts" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "profileId": "YOUR_MANAGED_ACCOUNT_PROFILE_ID",
  "friendlyName": "Demo Business Account",
  "currency": "EUR"
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

🇬🇧 GBP Account

Create GBP Managed Account

curl -X POST "https://sandbox.weavr.io/multi/managed_accounts" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "profileId": "YOUR_MANAGED_ACCOUNT_PROFILE_ID",
  "friendlyName": "Demo Business Account",
  "currency": "GBP"
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response:

{
  "id": "115134323456789012",
  "profileId": "115079696351297567",
  "friendlyName": "Demo Business Account",
  "currency": "EUR",
  "balances": {
    "availableBalance": 0,
    "actualBalance": 0
  },
  "state": {
    "state": "ACTIVE"
  },
  "creationTimestamp": 1756810186000
}

📝 Save the account ID (id field) - you'll need it for funding and transactions.

📝

Save Account ID

Copy the id value from the managed account response above.

Managed Account ID:

Copy id from the account response above

💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

Errors that point to a skipped step

• HTTP 403 {"errorCode": "STEP_UP_REQUIRED"}: your token isn't stepped up - complete the step-up challengeStep-up challengeA two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. earlier in this step, then retry. If you logged in again in between, step up the new token too.
• HTTP 409 {"errorCode": "OWNER_IDENTITY_NOT_VERIFIED"}: 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. isn't approved yet - re-run the corporate verification simulation in Step 3.
• HTTP 409 {"errorCode": "CURRENCY_NOT_SUPPORTED_BY_PROFILE"}: switch the currency tab to match your managed accountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. profileProfileA template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type.'s region.

Upgrade account to IBAN

Upgrade your managed accountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. to have an IBANIBAN (International Bank Account Number). International Bank Account Number - a standardized international bank account identifier. Managed accounts can be assigned an IBAN to enable wire transfers to and from bank accounts outside of Weavr. IBANs are required for EUR accounts and enable SEPA transfers. (or a sort code and account number in the case of a GBP account) for receiving incoming wire transfersWire TransferA transaction that moves funds between accounts. An incoming wire transfer moves funds from a third-party bank account to a Weavr managed account, while an outgoing wire transfer moves funds from a Weavr managed account to a third-party bank account. Wire transfers require the managed account to have an assigned IBAN (for EUR) or sort code and account number (for GBP).:

POST/managed_accounts/{id}/ibanOpen API reference →

/managed_accounts/123456789/iban

Upgrade to IBAN

curl -X POST "https://sandbox.weavr.io/multi/managed_accounts/YOUR_MANAGED_ACCOUNT_ID/iban" \
-H "Content-Type: application/json" \
-H "program-id: YOUR_PROGRAM_ID" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response:

{
  "bankAccountDetails": [
    {
      "beneficiaryBank": "Demo Bank",
      "beneficiaryBankAddress": "123 Europa st, 8004 Malta, Malta",
      "beneficiaryNameAndSurname": "QuickStart Demo GmbH",
      "details": {
        "code": "PATCBGSF",
        "iban": "BG97YCYI773026LRT3520V"
      }
    },
    {
      "beneficiaryBank": "Demo Bank",
      "beneficiaryBankAddress": "123 Europa st, 8004 Malta, Malta",
      "beneficiaryNameAndSurname": "QuickStart Demo GmbH",
      "details": {
        "bankIdentifierCode": "PATCBGSF",
        "iban": "BG97YCYI773026LRT3520V"
      }
    }
  ],
  "state": "ALLOCATED"
}

✅ Checkpoint: You should have a Managed AccountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. enabled with an IBANIBAN (International Bank Account Number). International Bank Account Number - a standardized international bank account identifier. Managed accounts can be assigned an IBAN to enable wire transfers to and from bank accounts outside of Weavr. IBANs are required for EUR accounts and enable SEPA transfers., or sort code and account number, ready for transactions.

---

Step 5: Issue virtual card

Create a virtual cardVirtual CardA payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. linked to your Managed AccountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. for online purchases.

Create a virtual card

POST/managed_cardsOpen API reference →

/managed_cards

{  "profileId": "10001",  "tag": "customer-123",  "friendlyName": "Travel card",  "nameOnCard": "Alex Smith",  "nameOnCardLine2": "Acme Ltd",  "billingAddress": {    "addressLine1": "1 High Street",    "addressLine2": "Flat 2",    "city": "London",    "postCode": "W1A 1AA",    "state": "Greater London",    "country": "GB"  },  "digitalWallets": {    "pushProvisioningEnabled": true,    "walletsEnabled": true,    "artworkReference": "ART_001"  },  "authForwardingDefaultTimeoutDecision": "APPROVE",  "mode": "PREPAID_MODE",  "externalData": [    {      "name": "Alex Smith",      "value": "INV-1042"    }  ],  "renewalType": "RENEW",  "userId": {},  "currency": "GBP"}

🇪🇺 EUR Card

Create virtual card (EUR)

curl -X POST "https://sandbox.weavr.io/multi/managed_cards" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "profileId": "YOUR_MANAGED_CARD_PROFILE_ID",
  "userId": "YOUR_ROOT_USER_ID",
  "friendlyName": "Demo Virtual Card",
  "currency": "EUR",
  "nameOnCard": "Demo Administrator",
  "mode": "PREPAID_MODE",
  "billingAddress": {
    "addressLine1": "123 Demo Street",
    "city": "London",
    "postCode": "SW1A 1AA",
    "country": "GB"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

🇬🇧 GBP Card

Create virtual card (GBP)

curl -X POST "https://sandbox.weavr.io/multi/managed_cards" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "profileId": "YOUR_MANAGED_CARD_PROFILE_ID",
  "userId": "YOUR_ROOT_USER_ID",
  "friendlyName": "Demo Virtual Card",
  "currency": "GBP",
  "nameOnCard": "Demo Administrator",
  "mode": "PREPAID_MODE",
  "billingAddress": {
    "addressLine1": "123 Demo Street",
    "city": "London",
    "postCode": "SW1A 1AA",
    "country": "GB"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response:

{
  "id": "115134334567890123",
  "profileId": "115079696398155807",
  "friendlyName": "Demo Virtual Card",
  "nameOnCard": "Demo Administrator",
  "mode": "PREPAID_MODE",
  "state": {
    "state": "ACTIVE"
  },
  "type": "VIRTUAL",
  "cardNumberFirstSix": "555544",
  "cardNumberLastFour": "0001",
  "currency": "EUR",
  "balances": {
    "actualBalance": 0,
    "availableBalance": 0
  },
  "creationTimestamp": 1756810186000
}

📝 Save the card ID (id field) for transactions.

📝

Save card ID

Copy the id value from the Managed Card response above.

Managed Card ID:

Copy id from the card response above

💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

✅ Checkpoint: You should have an active virtual cardVirtual CardA payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. ready for use.

---

Step 6: Process transactions

Add funds to your Managed AccountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. and test a card transaction.

Add test funds (sandbox simulation method)

Add test funds to your Managed AccountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. using the simulator API:

🇪🇺 EUR

Add test funds

curl -X POST "https://sandbox.weavr.io/simulate/api/accounts/YOUR_MANAGED_ACCOUNT_ID/deposit" \
-H "Content-Type: application/json" \
-H "program-key: YOUR_API_KEY" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "depositAmount": {
    "amount": 10000,
    "currency": "EUR"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

🇬🇧 GBP

Add test funds

curl -X POST "https://sandbox.weavr.io/simulate/api/accounts/YOUR_MANAGED_ACCOUNT_ID/deposit" \
-H "Content-Type: application/json" \
-H "program-key: YOUR_API_KEY" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "depositAmount": {
    "amount": 10000,
    "currency": "GBP"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Amount Format

Amounts are in minor units (cents for EUR, pence for GBP). So 10000 = €100.00

Make a transfer

Transfer funds from the account to the "prepaid modePrepaid ModeA card mode where the card has its own balance and purchases are authorised based on this balance. Cards in prepaid mode can be topped up with funds and support transactions such as transfers and sends. If there are insufficient funds, purchases are declined until the card has sufficient funds." card to enable purchases:

POST/transfersOpen API reference →

/transfers

{  "profileId": "10001",  "tag": "invoice-2026-0042",  "source": {    "type": "managed_accounts",    "id": "123456789"  },  "destination": {    "type": "managed_accounts",    "id": "987654321"  },  "destinationAmount": {    "currency": "GBP",    "amount": 1250  },  "description": "Invoice 2026-0042"}

Idempotency on money endpoints

Money endpoints accept an idempotency-ref header. Generate a fresh UUIDv4 per logical request and retry with the same value if the call times out or returns a 5xx. Without it, a retry-after-timeout can double-spend.

🇪🇺 EUR

Create transfer

curl -X POST "https://sandbox.weavr.io/multi/transfers" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "idempotency-ref: $(uuidgen)" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "profileId": "YOUR_TRANSFER_PROFILE_ID",
  "tag": "demo-transfer",
  "source": {
    "type": "managed_accounts",
    "id": "YOUR_MANAGED_ACCOUNT_ID"
  },
  "destination": {
    "type": "managed_cards",
    "id": "YOUR_MANAGED_CARD_ID"
  },
  "destinationAmount": {
    "amount": 5000,
    "currency": "EUR"
  },
  "description": "Demo transfer to card"
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

🇬🇧 GBP

Create transfer

curl -X POST "https://sandbox.weavr.io/multi/transfers" \
-H "api-key: YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-H "idempotency-ref: $(uuidgen)" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "profileId": "YOUR_TRANSFER_PROFILE_ID",
  "tag": "demo-transfer",
  "source": {
    "type": "managed_accounts",
    "id": "YOUR_MANAGED_ACCOUNT_ID"
  },
  "destination": {
    "type": "managed_cards",
    "id": "YOUR_MANAGED_CARD_ID"
  },
  "destinationAmount": {
    "amount": 5000,
    "currency": "GBP"
  },
  "description": "Demo transfer to card"
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Expected response:

{
  "id": "115134872658542592",
  "profileId": "your-corporate-profile-id",
  "tag": "demo-transfer",
  "state": "COMPLETED",
  "sourceAmount": {
    "value": 5000,
    "currency": "EUR"
  },
  "destinationAmount": {
    "value": 5000,
    "currency": "EUR"
  }
}

✅ Checkpoint: Your transfer should show "state": "COMPLETED" and you've successfully moved €50.00 to your card.

If the transfer returns 409

• FUNDS_INSUFFICIENT: the account balance is lower than the transfer amount - repeat the test deposit in the previous step and confirm the funds landed.
• CURRENCY_MISMATCH: the source, destination, and destinationAmount currencies must match - keep the account, card, and transfer on the same currency tab.

Simulate a card purchase (sandbox simulation method)

Test your virtual cardVirtual CardA payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. with a simulated purchase transaction:

🇪🇺 EUR

Simulate card purchase

curl -X POST "https://sandbox.weavr.io/simulate/api/cards/YOUR_MANAGED_CARD_ID/purchase" \
-H "Content-Type: application/json" \
-H "program-key: YOUR_API_KEY" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "merchantName": "Test Merchant",
  "merchantCategoryCode": "5411",
  "transactionAmount": {
    "amount": 1000,
    "currency": "EUR"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

🇬🇧 GBP

Simulate card purchase

curl -X POST "https://sandbox.weavr.io/simulate/api/cards/YOUR_MANAGED_CARD_ID/purchase" \
-H "Content-Type: application/json" \
-H "program-key: YOUR_API_KEY" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{
  "merchantName": "Test Merchant",
  "merchantCategoryCode": "5411",
  "transactionAmount": {
    "amount": 1000,
    "currency": "GBP"
  }
}'

💡 Tip: Use the credential form above to automatically populate your API keys and Profile IDs in this code block.

Testing Card Transactions

The simulator API allows you to test various card transaction scenarios in the sandbox environment. The merchant category code (MCC) 5411 represents grocery stores.

What just happened — the webhooks side

If your app had a webhook URL registered, the simulated purchase you just ran would have fired two callbacks to it:

Event	Webhook URL	When it fires
Authorization	${WEBHOOK_URL}/managed_cards/authorisations/watch	Immediately, with approved: true | false and the merchant details
Settlement	${WEBHOOK_URL}/managed_cards/settlements/watch	When the merchant captures the funds — minutes to hours later in production, near-instantly in sandbox

A real integration listens for both. The authorization tells the user the transaction was accepted; the settlement is what actually moves money off the card and is the trigger for things like analytics, receipts, or push notifications to the cardholder.

To wire this up:

• Register a sandbox webhook URL — point at a Pipedream or ngrok endpoint while you're developing.
• Read the full card webhook events reference — full schema for authorisations, settlements, and adjustments.

Re-running the simulator call with the URL configured is the fastest way to see the payload shape end-to-end.

---

Congratulations, you're done

You've successfully:

✅ Connected to our API
✅ Created a corporate with verified email
✅ Set up authentication for your business user
✅ Created a managed accountManaged AccountAn account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. to hold funds
✅ Issued a virtual cardVirtual CardA payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. for online purchases
✅ Processed your first card purchase transaction

What's next?

Immediate next steps

• Explore webhooks → - Get notified of transaction events
• Learn about KYB → - Complete business verification
• Add more users → - Invite team members

Build your integration

• OnVirtual.cards reference → - Complete Vue.js integration example
• UI components → - Secure forms for sensitive data
• Transaction processing → - Advanced payment workflows

Stay current

• Weavr API changelog → - Recent additions, breaking changes, and deprecations to the API surface
• Mobile SDK changelogs by platform: iOS → / Android → / React Native →

Subscribe to the changelog RSS feed so endpoint changes don't surprise you in production.

Need help?

• Common issues → - Authentication troubleshooting
• Support portal → - Get help from our team
• API reference → - Complete endpoint documentation