Skip to main content

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 Identities, 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)., and Transactions.

What you'll build

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

  • A working API connection to Weavr
  • A corporate identity created and verified
  • A managed accountManaged Account An 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 Card A 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 API Credentials page in your 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.. Here you'll also find an Environment file, containing all your profileProfile A 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, on the API Credentials page under the ProfilesProfile A 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. tab, fetch and save your IDs listed below. 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==)
📋 ProfileProfile A 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 ProfileProfile A 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 Account An 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. ProfileProfile A 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 Card A 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. ProfileProfile A 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 ProfileProfile A 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 Transfer A 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). ProfileProfile A 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 ProfileProfile A 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:

HeaderUsed bySourceExample call in this guide
api-key: YOUR_API_KEYEvery MultiMulti Weavr 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 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 CredentialsAll sandbox.weavr.io/multi/… calls
Authorization: Bearer YOUR_TOKENAuthenticated end-user calls - needed once the user is logged inReturned 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 nameStep 3's "Verify corporate identity (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 '{}'

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

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 identity​

Now create a corporate (business) identity that will own accounts and cards. Choose your region based on your corporate profileProfile A 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/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"
}

Create the corporate​

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

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

Copy id.id from the response above
Copy rootUser.id.id from the response above
Region-specific profiles

Getting COUNTRY_UNSUPPORTED error?

  • Your corporate profileProfile A 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 profilesProfile A 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 profilesProfile A 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 profileProfile A 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
Follow your progress in the embedder portal

You can see the corporate that was created via the UI of the 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.. 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 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. ID saved.

Step 3: Set root user credentials, and verify identity​

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 identity verification before it can be used.

Set root user password​

POST/passwords/{user_id}/createTry it 
{
  "password": {
    "value": "pa$$word"
  }
}
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!"
  }
}'

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

Update your credentials

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

Copy token from the login response above

Send an email verification code to the root user​

POST/corporates/verification/email/sendTry it 
{
  "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"
}'

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

Verify email of the root user​

POST/corporates/verification/email/verifyTry it 
{
  "email": "[email protected]",
  "verificationCode": "string"
}
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"
}'

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

FlowEndpoint familyWhen it runsWhat it changes
Factor enrolment/authentication_factors/otp/SMSOnce per user, during onboardingRegisters the SMS channel against the user
Step-up challengeStep-up challenge A 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/SMSEvery time the user accesses a protected resourceSteps 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}Try it 
{
  "code": "string",
  "message": "string"
}
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"

Verify the enrollment​

POST/authentication_factors/otp/{channel}/verifyTry it 
{
  "verificationCode": "string"
}
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"
}'
Sandbox Step-Up

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

Verify corporate identity (sandbox simulation method)​

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

Simulator API

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

Verify Corporate Identity
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"

✅ 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 login and complete step-up authentication. This is a security requirement for accessing and completing sensitive operations.

Login 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_passwordTry it 
{
  "email": "[email protected]",
  "password": {
    "value": "pa$$word"
  }
}
Login 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!"
  }
}'

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.

Copy token from the login response above

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/SMSTry it 
{
  "code": "string",
  "message": "string"
}
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"
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/verifyTry it 
{
  "verificationCode": "string"
}
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"
}'

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

Create the managed account​

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

POST/managed_accountsTry it 
{
  "profileId": "string",
  "friendlyName": "string",
  "currency": "str",
  "tag": "string"
}
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"
}'

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.

Copy id from the account response above

Upgrade account to IBAN​

Upgrade your managed accountManaged Account An 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 - 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 Transfer A 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}/ibanTry it 
{
  "state": "UNALLOCATED",
  "bankAccountDetails": [
    {
      "beneficiaryNameAndSurname": "string",
      "beneficiaryBank": "string",
      "beneficiaryBankAddress": "string",
      "paymentReference": "string",
      "details": {
        "iban": "stringstringstr",
        "bankIdentifierCode": "stringst"
      }
    }
  ]
}
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 '{}'

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 Account An 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 - 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 Card A 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 Account An 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_cardsTry it 
{
  "profileId": "string",
  "tag": "string",
  "friendlyName": "string",
  "nameOnCard": "string",
  "nameOnCardLine2": "string",
  "cardholderMobileNumber": "string",
  "billingAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "postCode": "string",
    "state": "string",
    "country": "st"
  },
  "digitalWallets": {
    "pushProvisioningEnabled": true,
    "walletsEnabled": true,
    "artworkReference": "string"
  },
  "authForwardingDefaultTimeoutDecision": "APPROVE",
  "threeDSecureAuthConfig": {
    "linkedUserId": "string",
    "primaryChannel": "OTP_SMS",
    "fallbackChannel": "OTP_SMS"
  },
  "mode": "string",
  "externalData": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "renewalType": "RENEW",
  "userId": "string"
}
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"
  }
}'

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.

Copy id from the card response above

✅ Checkpoint: You should have an active virtual cardVirtual Card A 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 Account An 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 Account An 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:

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"
  }
}'
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 Mode A 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/transfersTry it 
{
  "profileId": "string",
  "tag": "string",
  "source": {
    "id": "string",
    "type": "managed_cards"
  },
  "description": "string",
  "destination": {
    "id": "string",
    "type": "managed_cards"
  },
  "destinationAmount": {
    "currency": "str",
    "amount": 0
  },
  "scheduledTimestamp": "string"
}
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.

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

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.

Simulate a card purchase (sandbox simulation method)​

Test your virtual cardVirtual Card A 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:

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"
  }
}'
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:

EventWebhook URLWhen it fires
Authorization${WEBHOOK_URL}/managed_cards/authorisations/watchImmediately, with approved: true | false and the merchant details
Settlement${WEBHOOK_URL}/managed_cards/settlements/watchWhen 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:

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 identity with verified email
✅ Set up authentication for your business user
✅ Created a managed accountManaged Account An 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 Card A 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​

Build your integration​

Stay current​

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

Need help?​