Skip to main content

15-Minute Quick Start Guide

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

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 account with funds
✅ A virtual card issued and ready to use
✅ Your first successful transaction processed

Alternatively, download our postman collection

All the steps mentioned in this guide are included in a postman collection, available from the API Credentials page in your embedder portal. Here you'll also find an Environment file, containing all your profile 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, make sure you have:

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: Open a Sandbox Account →

3. API credentials ready​

From your Embedder Portal, on the API Credentials page under the Profiles tab, fetch and save your IDs listed below:

📋 Programme ID (example: 115079696319971359)
📋 API Key (base64-encoded, example: dpcYgcIKBp8BmNhfxHYBIQ==)
📋 Profile IDs (all numeric):

  • Corporate Profile ID (example: 115079696331702303)
  • Managed Account Profile ID (example: 115079696351297567)
  • Managed Card Profile ID (example: 115079696398155807)
  • Transfer Profile ID (example: 115079696434790431)
  • Outgoing Wire Transfer Profile 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 Programme ID, API key, and all Profile IDs ready before proceeding.

⚙️

API Environment Variables

0/13 configured

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​

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 Portal

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

POST/corporatesTry it

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:

{
  "id": {
    "id": "115134292391559225",
    "type": "CORPORATE"
  },
  "profileId": "115079696331702303",
  "creationTimestamp": 1756809885699,
  "company": {
    "name": "QuickStart Demo GmbH", // or "QuickStart Demo Ltd" for UK
    "type": "LLC"
  },
  "rootUser": {
    "id": {
      "id": "115134292391559225",
      "type": "USER"
    },
    "name": "Hans", // or "John" for UK
    "surname": "Müller" // or "Smith" for UK
  }
}

📝 Save these values:

  • id.id: Your corporate ID (example: 115134292391559225)
  • rootUser.id.id: Your 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
💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.
Region-Specific Profiles

Getting COUNTRY_UNSUPPORTED error?

  • Your corporate profile may be configured for a different region
  • Try switching between the EU and UK tabs above
  • EU profiles typically support: DE, FR, IT, ES, NL, etc.
  • UK profiles support: GB only
  • Contact support if you need to change your profile configuration
Follow your progress in the embedder portal

You can see the corporate that was created via the UI of the embedder portal. 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 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
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
💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

Send an email verification code to the root user​

POST/corporates/verification/email/sendTry it
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
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).

Enrol mobile number for SMS​

POST/authentication_factors/otp/{channel}Try it
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 enrolment​

POST/authentication_factors/otp/{channel}/verifyTry it
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 KYB checks:

Simulator API

This step uses the Weavr Simulator API which is only available in sandbox environments for testing purposes. In production, corporates go through full KYB verification.

Verify Corporate Identity
curl -X POST "https://sandbox.weavr.io/simulate/api/corporates/YOUR_CORPORATE_ID/verify" \
-H "programme-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
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
💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

Initiate a step-up challenge via SMS​

POST/stepup/challenges/otp/SMSTry it
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
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
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", // or "GBP" for UK accounts
  "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
💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

Upgrade account to IBAN​

Upgrade your managed account to have an IBAN (or a sort code and account number in the case of a GBP account) for receiving incoming wire transfers:

POST/managed_accounts/{id}/ibanTry it
Upgrade to IBAN
curl -X POST "https://sandbox.weavr.io/multi/managed_accounts/YOUR_MANAGED_ACCOUNT_ID/iban" \
-H "Content-Type: application/json" \
-H "programme-id: YOUR_PROGRAMME_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 Account enabled with an IBAN, or sort code and account number, ready for transactions.

Step 5: Issue virtual card​

Create a virtual card linked to your Managed Account for online purchases.

Create a virtual card​

POST/managed_cardsTry it
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",
  "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
💡 Auto-populate: Once saved, these values will automatically appear in all subsequent cURL commands below.

✅ Checkpoint: You should have an active virtual card ready for use.

Step 6: Process transactions​

Add funds to your Managed Account and test a card transaction.

Add test funds (sandbox simulation method)​

Add test funds to your Managed Account 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 "programme-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 mode" card to enable purchases:

POST/transfersTry it
Create transfer
curl -X POST "https://sandbox.weavr.io/multi/transfers" \
-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_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": "txn_mno345pqr678",
  "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 card 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 "programme-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.

🎉 Congratulations! You're done​

In just 15 minutes, you've successfully:

✅ Connected to the Weavr API
✅ Created a corporate identity with verified email
✅ Set up authentication for your business user
✅ Created a managed account to hold funds
✅ Issued a virtual card for online purchases
✅ Processed your first card purchase transaction

What's next?​

Immediate next steps​

Build your integration​

Need help?​