# Web3Card Docs
> White-label crypto card infrastructure for web3 projects. Visa cards funded by stablecoins, under your brand and your domain.
---
Source: https://docs.web3card.dev/
# Launch your card program under your own brand
The manual of Web3Card, the white-label software for Visa cards funded by stablecoins. From the first sign-up to the API.
Web3Card is white-label software for card programs. Your company runs a program of Visa cards funded by stablecoins, with your brand on the app and your own domain in the address bar. Your users create an account and manage their cards in an app that looks like yours.
This documentation is the user manual of the platform. It follows the path a new company takes, from the first visit to advanced use of the API, and it grows together with the product. A chapter is published when the feature it describes is ready.
**Where this manual is today**
Version 2 of Web3Card is opening in stages, and this manual grows with it. Account creation and sign-in are finished in both panels and are fully documented here. The next chapters (identity, wallets, cards, branding, your own domain and the API reference) are listed in [From sign-up to launch](https://docs.web3card.dev/platform/path-to-launch/) and are published as each part is finished.
## What Web3Card is
Web3Card is a technology provider. It delivers three things:
- **Software.** A panel for your company and an app for your users, both ready to carry your brand.
- **Infrastructure.** Hosting, security, account access and the connection to the card networks through partner institutions.
- **Integration.** One API to operate your card program from your own systems.
Web3Card is not a bank or a financial institution. Cards are issued by licensed and regulated partner institutions within the Visa network.
## Two panels, one platform
The platform has two sides. Each one has its own address, its own accounts and its own audience.
| | Business | Personal |
| --- | --- | --- |
| Who uses it | The company that runs the card program, and its team | The end user of each company |
| What it is for | Set up and operate the program | Create an account and use the card |
| Address | `business.web3card.dev`, the same for every company | The company's own domain, such as `cards.yourcompany.com` |
| Brand on the screen | Web3Card | The company's brand |
Read [How the platform works](https://docs.web3card.dev/platform/overview/) for the full picture.
## How this documentation is organized
| Chapter | What it covers | Status |
| --- | --- | --- |
| [The platform](https://docs.web3card.dev/platform/overview/) | The two panels, what white-label means, and the path from sign-up to launch | Published |
| [Card playground](https://docs.web3card.dev/playground/) | Design a sample card in 3D, see what each card action does and preview your users' app | Preview of screens in development |
| [Flow builder](https://docs.web3card.dev/flow-builder/) | Pick a token on a network and see the route it takes to your wallet, your program contract or a Visa card, with the API calls for each step | Illustrative: API v2 is planned |
| [Cards](https://docs.web3card.dev/cards/countries/) | The countries and regions where cards don't work, and where they can be used with Apple Pay | Published |
| [Account access](https://docs.web3card.dev/access/create-business-account/) | Creating an account, signing in and out, resetting the password, replacing the authenticator, security rules and messages | Published |
| [API](https://docs.web3card.dev/api/overview/) | What API v2 is and how it is designed. The [reference of API v1](https://docs.web3card.dev/api-reference/overview/), with code examples, is kept as legacy | v2: overview published, reference planned. v1: legacy |
| Identity, wallets, cards, branding, domain, team | The next steps of the journey | To come. See [From sign-up to launch](https://docs.web3card.dev/platform/path-to-launch/) |
New to the terms used here? The [glossary](https://docs.web3card.dev/glossary/) explains each one in a sentence.
## Languages
This documentation is available in English and in Portuguese (Brazil). Use the language menu at the top of the page to switch. The screens of the platform are in English, so button and field names are quoted in English in both versions.
## For AI assistants
The full text of this documentation is also published as plain text, ready to be read by language models:
- [llms.txt](https://docs.web3card.dev/llms.txt): the index of pages, with a one-line summary of each
- [llms-full.txt](https://docs.web3card.dev/llms-full.txt): every page in a single file
## Need help?
Write to [contact@web3card.dev](mailto:contact@web3card.dev) or visit [web3card.dev](https://web3card.dev).
---
Source: https://docs.web3card.dev/playground/
## What you can try here
**In development**
Card setup and White label, the two screens of the Business panel this playground is based on, are being built. The options and the texts may change.
The playground runs in your browser. Nothing is sent anywhere, and a logo you pick stays on this page. The card is a sample, with sample details.
### Design your card
**Card setup**, in the Business panel, is where your company chooses the cards its users can get and how each one looks. The playground has the options of a card designed by the company: a preset material, the color, the pattern, the finish, the grain, the color of the marks and your brand or logo.
The name on the card is always the verified name of the user. The card network mark is added by the platform and cannot be moved.
### Card actions
Each action shows on the card what it does.
| Action | What it does | Where |
| --- | --- | --- |
| Create card | Creates a virtual card for a user whose identity is verified, paid from the program balance in your contract | Business panel and users' app |
| Top up | Moves balance from the program to a card. The top-up fee is paid on top, so the card receives the full amount | Business panel and users' app |
| Freeze | Stops the card with one click. Unfreezing asks for the code from the authenticator app | Business panel and users' app |
| Reveal | Shows the full number, the expiry date and the security code, after the code from the authenticator app. They are not stored anywhere | Users' app |
| Billing | The name on the card and the billing address, which an online store asks for at checkout | Business panel and users' app |
| Limits | A monthly limit per card, and a range for the first load and for top-ups per card type | Business panel and users' app |
| Rename | Changes the nickname of the card. The name printed on the card does not change | Business panel |
| Cancel | Ends the card for good | Business panel |
### Your users' app
**White label**, in the Business panel, is where your company sets the name, the logo and the colors of the app its users see. The preview shows your brand in each of the four themes of the platform, with your accent color.
### Measures
The card follows the ID-1 size of payment cards: 85.60 × 53.98 mm, with corners rounded at 3.18 mm. Turn on **Measures** above the card to see them.
---
Source: https://docs.web3card.dev/flow-builder/
## What the flow builder shows
**Illustrative**
The flow builder shows how a token reaches a card of your program, and the calls we want API v2 to have for each step. API v2 is planned: no endpoint is published yet, and the names, fields and responses may change. The Bridge in your users' app is being built.
The flow builder runs in your browser. Nothing is sent anywhere and no wallet is connected. The amounts, addresses and identifiers in the code are samples.
Pick a token and its network on the left, then where it should end. The flow on the right draws each step the token goes through. Hover a step to see its call in the code below, or click it to jump there.
### Where a flow starts
A flow starts in the user's own wallet, on one of these networks.
| Network | Tokens |
| --- | --- |
| BNB Chain | BNB, USDT, USDC |
| Ethereum | ETH, USDT, USDC |
| Arbitrum | ETH, USDT, USDC |
| Polygon | POL, USDT, USDC |
| Base | ETH, USDC |
**Your project token** shows how a token of your own project can enter the same flow: it is first swapped on a decentralized exchange (DEX) of its network, then follows the same route as any other token. This only works for a token that has a market on a DEX of its network.
### Where a flow ends
| Destination | What happens |
| --- | --- |
| **Your wallet** | The user receives the program token, on BNB Chain, in their own wallet |
| **Program contract** | The program token is deposited into your program contract and becomes program balance |
| **Visa card** | After the deposit, the balance is moved from the program to a card of the user, ready to spend |
The **program token** is the token your program contract works with: USDT or USDC, on BNB Chain.
### The steps of a route
| Step | What it does |
| --- | --- |
| **DEX swap** | Converts the token into the program token, on the same network |
| **Web3Card Bridge** | Brings the token from another network to BNB Chain, converting it on the way when needed |
| **Deposit** | Moves the program token from the user's wallet into your program contract |
| **Top up** | Moves balance from the program to a card. The top-up fee is paid on top, so the card receives the full amount |
The user signs each transaction in their own wallet. The tokens leave the user's wallet and arrive in the same wallet: nothing goes through you or the platform on the way. A token that is already the program token on BNB Chain skips the swap and the bridge.
### The calls
Each step of the flow has a call in the **Code** panel, in cURL and in JavaScript, with a sample response. They follow the [design principles of API v2](https://docs.web3card.dev/api/overview/): operations you follow until they finish, a key that makes a repeated request safe, and signed events.
| Call | What it does |
| --- | --- |
| Get a route | Returns the route to the program token and the transactions for the user to sign |
| Follow the transfer | Reads the operation of the transfer until it ends |
| Deposit into the program | Returns the two transactions of a deposit: the authorization of the exact amount and the deposit |
| Top up the card | Moves balance from the program to a card. It carries an idempotency key |
| Receive the event | Your systems get a signed event when the flow ends |
`$W3C_API` stands for the address of the API, which is not published yet, and `$W3C_API_KEY` for your key.
## Related pages
| Page | What it covers |
| --- | --- |
| [Card playground](https://docs.web3card.dev/playground/) | Design a sample card and see what each card action does |
| [API v2 overview](https://docs.web3card.dev/api/overview/) | What API v2 is and the principles it is designed on |
| [Cards: countries](https://docs.web3card.dev/cards/countries/) | Where cards don't work, and where they can be used with Apple Pay |
---
Source: https://docs.web3card.dev/platform/overview/
# How the platform works
Web3Card has two sides that work together. A company operates its card program in the **Business** panel. The users of that company create their accounts and use their cards in the **Personal** app, which carries the company's brand.
## The Business panel
The Business panel belongs to the company that runs the card program, and to its team.
- **One address for everyone.** Every company uses the same address: `business.web3card.dev`.
- **The company comes from the account.** There is nothing to choose on the login screen. The platform knows which company you belong to from the account you sign in with.
- **Two roles.** The person who creates the company is its **owner**. Other people will join the team by invitation from the owner, as **members**.
- **The Web3Card brand is visible.** The company that buys the software knows it is buying from Web3Card, so the panel does not hide it.
## The Personal app
The Personal app belongs to the end user: the person who holds the card.
- **One address per company.** The app lives on the company's own domain, such as `cards.yourcompany.com`. The address bar shows that domain the whole time.
- **The company comes from the domain.** When a user opens the address, the platform recognizes which company owns that domain and loads its name, logo and theme.
- **The Web3Card brand is not visible.** The user sees the company's brand, on the screen and in the messages the platform sends.
Web3Card uses its own platform in the same way as any other company. Its Personal app is at `wallet.web3card.app`.
## Side by side
| | Business | Personal |
| --- | --- | --- |
| Who signs in | The owner and the team of a company | The end users of that company |
| Address | `business.web3card.dev` | The company's domain |
| How the company is identified | By the account that is signed in | By the domain in the address bar |
| Brand on the screen | Web3Card | The company's brand |
| An email address can have | One account in the whole panel | One account in each company's app |
## Accounts are separate
A Business account and a Personal account are different accounts, even when they use the same email address.
- In the **Business** panel, an email address has one account. That account belongs to one company.
- In the **Personal** app, an email address has one account per company. The same person can be a user of two different companies. Those are two independent accounts, each with its own password and its own authenticator.
The same rule applies to mobile numbers: a number can be used once in the Business panel and once in each company's app.
## Who does what
| | Responsibility |
| --- | --- |
| **Your company** | Owns the brand, the domain and the relationship with its users. Decides how the program is presented and operated. |
| **Web3Card** | Provides the software, the infrastructure and the API. Web3Card is a technology provider, not a bank or a financial institution. |
| **Partner institutions** | Licensed and regulated institutions within the Visa network. They issue the cards. |
## What this manual covers today
Account access is finished in both panels and documented step by step:
- [creating a Business account](https://docs.web3card.dev/access/create-business-account/) and [creating a Personal account](https://docs.web3card.dev/access/create-personal-account/), each with three verification steps
- [signing in and signing out](https://docs.web3card.dev/access/sign-in/), with a password and an authenticator code
- [resetting a forgotten password](https://docs.web3card.dev/access/reset-password/)
- [replacing the authenticator](https://docs.web3card.dev/access/replace-authenticator/) when a phone is lost
- the Personal app opening with the brand of the company that owns the domain
Everything that comes after sign-in is being built now. The order is in [From sign-up to launch](https://docs.web3card.dev/platform/path-to-launch/).
---
Source: https://docs.web3card.dev/platform/white-label/
# White-label: your brand, your domain
On Web3Card, white-label means that your users deal with your brand from start to finish. They open your domain, see your name and your logo, and receive messages signed by your company.
## What your users see
| Where | What appears |
| --- | --- |
| Address bar | Your domain, such as `cards.yourcompany.com`, on every screen |
| Browser tab | Your name and your logo |
| Screens | Your name, your logo and the theme you chose |
| Authenticator app | Your name next to the user's email |
| Email and SMS codes | Your name, as the sender and in the text |
The Personal app is the same software for every company. What makes it yours is configuration, not custom code:
- **Name.** Shown on the screens, in the browser tab and in the messages.
- **Logo.** A square image. It appears small, next to your name, and becomes the icon of the browser tab. Without a logo, the app shows the first letter of your name.
- **Theme.** One of four: **Graphite Dark**, **Graphite Light**, **Gold Dark** and **Ivory**. This is the default for your users.
**Status: planned**
Today the brand of each company is set up by the Web3Card team. The screens where the owner edits name, logo and theme in the Business panel are planned. This page will get a step-by-step guide when they open.
## Each person can pick another theme
The theme you choose is the starting point. Each person can switch to any of the four on their own device.
- **Personal app.** At the bottom of the menu, **Theme** shows the name of the current theme. The **Account** screen has the same choice under **Appearance**.
- **Business panel.** At the bottom of the side menu, **Theme**.
The choice is kept in that browser only. On another device the person sees the default of the company again.
## Your own domain
The standard is that the Personal app runs on a domain that belongs to you.
**Use a subdomain.** Addresses such as `app.yourcompany.com` or `cards.yourcompany.com` work with every DNS provider. The bare domain (`yourcompany.com`) does not work with all of them, and `www` is usually taken by your institutional website.
**How it works:**
1. You choose the subdomain.
2. You create one record in your DNS: a CNAME that points the subdomain to the platform. The exact value is shown in your Business panel.
3. The platform issues the HTTPS certificate for your domain and renews it automatically.
4. Your users open your address. The platform recognizes the domain and loads your brand.
This is not a redirect. The address bar keeps showing your domain on every screen. Only you can change your DNS: Web3Card never asks for access to it.
An address that is not linked to a company shows a neutral page, **This address is not active**, without any brand.
**Status: planned**
Connecting a domain from the Business panel is planned. The step-by-step guide, with the record to create and how to check that it is active, will be published here when it opens.
## What white-label covers
White-label means that your users see your brand and your domain, and not ours. It covers everything a user sees while using the app: the address, the screens and the messages.
It is not a promise that the technology behind your program can never be identified by someone who investigates the infrastructure. If that matters for your business, talk to us before launch.
## The stages of a company
A company does not get everything on the first day. The account moves through stages, and each stage opens more of the platform.
| Stage | What it opens |
| --- | --- |
| **First stage** | You created the account and can look around the Business panel. Nothing in it is real yet. |
| **Next stages** | A test card for the owner, then full activation: branding, your own domain, your team and your users. |
The Home screen of the Business panel shows a notice that tells you which stage your company is in.
**Status: in development**
The screens of the panel are being redesigned, and the requirements of the next stages are still being defined. Both will be documented here before they open.
---
Source: https://docs.web3card.dev/platform/path-to-launch/
# From sign-up to launch
This page shows the whole path of a company on Web3Card, in the order it happens. Each step links to its guide as soon as the guide exists. It is also the map of this documentation: every chapter that is still to come is listed here.
## Status of each step
| Status | Meaning |
| --- | --- |
| **Ready** | The screens are finished and the guide is published. |
| **In development** | Being built now. The guide is published when the feature is finished. |
| **Planned** | Next in line. Details may still change. |
## The path of your company
The order is fixed. Each step opens when the one before it is done.
| # | Step | Where | Status |
| --- | --- | --- | --- |
| 1 | [Create your company account](https://docs.web3card.dev/access/create-business-account/): email, authenticator app and mobile number | Business | Ready |
| 2 | Subscribe: the one-time subscription fee of the software, paid by card | Business | In development |
| 3 | Verify the identity of the owner | Business | In development |
| 4 | Verify the company | Business | In development |
| 5 | Create the contract of your program: the network and the token are chosen once | Business | In development |
| 6 | Make the first deposit | Business | In development |
| 7 | Card setup: the cards your users can get and how each one looks. Try it in the [card playground](https://docs.web3card.dev/playground/) | Business | In development |
| 8 | White label: the name, the logo and the colors of the app your users see | Business | In development |
| 9 | [Connect your own domain](https://docs.web3card.dev/platform/white-label/#your-own-domain) | Business | Planned |
| 10 | Invite your team | Business | In development |
| 11 | Operate the program from your own systems with the [API](https://docs.web3card.dev/api/overview/) | API | Planned |
Plans and prices are on [web3card.dev](https://web3card.dev/#pricing).
## The sandbox
After the two verifications, **Go to sandbox**, at the bottom of the menu of the Business panel, opens a second panel with test banks and test money, to practice before going live. It opens already signed in, and nothing in it is real.
**In development**
The sandbox is being built together with the steps above.
## The path of your users
Your users follow a shorter path, inside the app that carries your brand. The app of your company opens to them after your program is active.
| # | Step | Status |
| --- | --- | --- |
| 1 | [Create an account](https://docs.web3card.dev/access/create-personal-account/): email, authenticator app and mobile number | Ready |
| 2 | [Sign in](https://docs.web3card.dev/access/sign-in/) with password and authenticator code | Ready |
| 3 | Link a wallet | In development |
| 4 | Make the first deposit | In development |
| 5 | Verify identity (KYC) | In development |
| 6 | Get a card | In development |
| 7 | Top up the card, deposit and withdraw | In development |
## What is documented so far
| Guide | Applies to |
| --- | --- |
| [Create a Business account](https://docs.web3card.dev/access/create-business-account/) | Business |
| [Create a Personal account](https://docs.web3card.dev/access/create-personal-account/) | Personal |
| [Sign in and sign out](https://docs.web3card.dev/access/sign-in/) | Both |
| [Reset your password](https://docs.web3card.dev/access/reset-password/) | Both |
| [Lost your phone: replace the authenticator](https://docs.web3card.dev/access/replace-authenticator/) | Both |
| [Security rules and limits](https://docs.web3card.dev/access/security-and-limits/) | Both |
| [Card playground](https://docs.web3card.dev/playground/) | A preview of Card setup and White label |
This page is updated every time a step changes status.
---
Source: https://docs.web3card.dev/cards/countries/
# Countries and regions
Cards follow international sanctions and the rules of the partner institutions that issue them. This page lists the countries and regions where cards don't work, and where they can be used with Apple Pay.
**The list can change**
It follows international sanctions and the partner institutions that issue the cards, and it is updated when they change. A card program can have more restrictions than the ones listed here. Last updated: October 2026.
## Availability by card program
Web3Card connects to more than one card program. The lists on this page are the ones of the main program, **SU**. Other programs, offered to some users, have restrictions of their own: a country blocked on the main program can be open on another one, and a country where cards work can have a specific requirement on some program. On this page these programs are named by code: **MO**, **UN-B** and **UN-Z**.
A dot next to a country shows its level. Hover or tap the dot to see what each program says about it.
- **Notice**: Cards work, with a specific requirement on some programs.
- **Partial**: Blocked on the main program; some programs don't restrict it.
- **Restricted**: Blocked on every program.
Which program a user can get depends on the company and on the user. These levels are a guide, not a promise that a card is available.
## Where cards don't work
Cards don't work in these 29 countries on the main program:
Afghanistan (Partial: SU blocked; MO blocked; UN-B blocked; UN-Z not restricted), Belarus (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Burundi (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Central African Republic (Partial: SU blocked; MO blocked; UN-B virtual card only, no physical card delivery; UN-Z virtual card only, no physical card delivery), China mainland (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Côte d'Ivoire (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Cuba (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Democratic Republic of the Congo (Partial: SU blocked; MO blocked; UN-B not restricted; UN-Z not restricted), Eritrea (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Guinea (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Guinea-Bissau (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Haiti (Partial: SU blocked; MO blocked; UN-B not restricted; UN-Z not restricted), Iran (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Iraq (Partial: SU blocked; MO blocked; UN-B blocked; UN-Z not restricted), Lebanon (Partial: SU blocked; MO blocked; UN-B not restricted; UN-Z not restricted), Libya (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Mali (Partial: SU blocked; MO blocked; UN-B not restricted; UN-Z not restricted), Myanmar (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Nicaragua (Partial: SU blocked; MO blocked; UN-B not restricted; UN-Z not restricted), North Korea (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Russia (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Somalia (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), South Sudan (Partial: SU blocked; MO blocked; UN-B virtual card only, no physical card delivery; UN-Z virtual card only, no physical card delivery), Sudan (Partial: SU blocked; MO not restricted; UN-B blocked; UN-Z blocked), Syria (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Ukraine (Partial: SU blocked; MO not restricted; UN-B blocked; UN-Z blocked), Venezuela (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Yemen (Partial: SU blocked; MO blocked; UN-B not restricted; UN-Z not restricted), Zimbabwe (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked).
### Regions
They also don't work in these regions:
Ambazonia (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Kosovo (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Northern Cyprus (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Occupied territories of Georgia (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Transnistria (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Western Sahara (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted).
## Apple Pay
Where a card can be added to Apple Pay, Apple Pay works only in the countries and regions where Apple offers it, and never in the places listed above. Apple keeps its list on the page [Countries and regions that support Apple Pay](https://support.apple.com/en-my/102775), published on October 19, 2026.
These are the countries on Apple's list where cards work:
- Africa: Egypt, Mauritius, Morocco, South Africa.
- Asia-Pacific: Australia, Hong Kong, Japan, Macao, Malaysia, Mongolia, New Zealand, Philippines, Singapore, South Korea, Taiwan, Vietnam.
- Europe: Albania, Andorra, Armenia, Austria (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Azerbaijan, Belgium (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Bosnia & Herzegovina, Bulgaria (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Croatia (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Cyprus (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Czechia (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Denmark (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Estonia (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Faroe Islands, Finland (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), France (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Georgia, Germany (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Greece (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Greenland, Guernsey, Hungary (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Iceland (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Ireland (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Isle of Man, Italy (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Jersey, Kazakhstan, Kyrgyzstan, Latvia (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Liechtenstein (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Lithuania (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Luxembourg (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Malta (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Moldova, Monaco, Montenegro, Netherlands (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), North Macedonia, Norway (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Poland (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Portugal (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Romania (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Serbia, Slovakia (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Slovenia (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Spain (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Sweden (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Switzerland (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Tajikistan, United Kingdom (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), Vatican City.
- Latin America and the Caribbean: Argentina, The Bahamas, Brazil, Chile, Colombia, Costa Rica, Dominican Republic, Ecuador, El Salvador, Guatemala, Honduras, Mexico, Panama, Paraguay, Peru, Uruguay.
- Middle East and India: Bahrain, India, Israel, Jordan, Kuwait, Oman, Palestine, Qatar, Saudi Arabia, United Arab Emirates.
- North America: Canada (Notice: SU not restricted; MO not restricted; UN-B not restricted; UN-Z ID documents issued here are not accepted), United States, Puerto Rico.
### On Apple's list, but blocked for cards
These are on Apple's list, but cards don't work there:
China mainland (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Belarus (Restricted: SU blocked; MO blocked; UN-B blocked; UN-Z blocked), Kosovo (Partial: SU blocked; MO not restricted; UN-B not restricted; UN-Z not restricted), Ukraine (Partial: SU blocked; MO not restricted; UN-B blocked; UN-Z blocked).
---
Source: https://docs.web3card.dev/access/create-business-account/
# Create a Business account
The Business account is the account of your company on Web3Card. Whoever creates it becomes the **owner** of the company in the platform. It takes a few minutes and has three verification steps, all required.
The Business panel is at `business.web3card.dev`.
## Before you start
Have these three things at hand:
- **Access to your work email.** You will receive a 6-digit code.
- **An authenticator app on your phone.** Google Authenticator, Microsoft Authenticator, Authy or 1Password all work.
- **A mobile phone that receives SMS.** You will receive one code by text message.
After you confirm your email, you have **60 minutes** to finish the other two steps. The account and the company only exist when the last step is done. If you stop before that, nothing is saved.
## Open the form
1. Open the Business panel. On the login screen, select **Sign up your company**.
2. Fill in the form **Create your company account**:
| Field | Rule |
| --- | --- |
| **Company name** | 2 to 60 characters |
| **Email** | Your work email. An email address can have only one Business account |
| **Password** | At least 12 characters, with at least 1 number, 1 lowercase letter and 1 uppercase letter |
3. Check **I agree to the Terms of Service and Privacy Policy**.
4. Select **Create account**.
The four password rules turn green on the screen as you type, and the eye button in the field shows what you typed. Passwords are case-sensitive. Choose one that you do not use anywhere else.
## Step 1 of 3: confirm your email
The platform sends a 6-digit code to the email you entered.
1. Open the email and copy the code.
2. On the screen **Confirm your email**, type it in **Code from the email**.
3. Select **Confirm email**.
Good to know:
- The code works for **15 minutes**.
- **Send a new code** sends another one. Only the newest code works.
- **After 5 wrong codes the sign-up is cancelled.** Fill in the form again to receive a new code.
- If no email arrives after you ask for a new code, select **Use a different email** and fill in the form again.
- The email brings only the code. It never has a link to click.
## Step 2 of 3: set up the authenticator app
From now on, every sign-in asks for a code from an authenticator app. A stolen password is not enough to get into your account.
1. On the screen **Protect your account**, open your authenticator app and scan the QR code.
2. Cannot scan it? Under **Can't scan it? Type this key into the app instead:** the screen shows a key. Type it into the app. The button next to the key copies it.
3. The app starts showing a 6-digit code for **Web3Card Business**. Type it in the field **2. Enter the 6-digit code the app shows**.
4. Select **Continue**.
The code changes every 30 seconds. If one is refused, wait for the next.
**Keep the phone with the app**
The key is shown only on this screen. After this step it is never shown again. If you lose the phone, follow [Lost your phone: replace the authenticator](https://docs.web3card.dev/access/replace-authenticator/).
## Step 3 of 3: confirm your mobile number
1. On the screen **Confirm your mobile number**, choose your **Country** and type your **Mobile number** with the area code. If your country is not on the list, choose **Other country** and type the full number, starting with the country code.
2. Select **Send code by SMS**.
3. On the screen **Enter the code we texted you**, type the code in **Code from the SMS**. The screen shows the number that received the code, partly hidden.
4. Select **Finish creating account**.
Good to know:
- The SMS code works for **10 minutes** and stops working after **5 wrong attempts**. When that happens the screen goes back to the mobile number, and you ask for another SMS.
- You can receive up to **3 SMS** per sign-up, with at least 60 seconds between one and the next. The button counts down: **Send a new code in 42s**.
- Typed the wrong number? Select **Wrong number? Change it**. The screen **Send the code again** opens. Sending to the new number uses one of the 3 SMS.
- If you reload the page, **Send a new code** asks for the number again.
- If the 3 SMS are used up, that sign-up cannot be finished. Start again from the form.
- A mobile number can have only one Business account.
- This is the only SMS the platform ever sends you. Signing in never uses SMS.
## You are in
When the SMS code is accepted, the company and your account are created and you are signed in. This first session lasts 1 day. The Home screen of the panel opens with a notice that tells you which stage your company is in.
What opens next is described in [From sign-up to launch](https://docs.web3card.dev/platform/path-to-launch/).
## If you stop in the middle
| Where you stopped | What happens when you come back |
| --- | --- |
| Before confirming the email | Sign in with the email and password you chose. The platform takes you to the screen **Confirm your email**. You can also fill in the form again: the new sign-up replaces the old one |
| After confirming the email, in the same browser | Reloading the screen shows the same step. If you open the main address of the panel, you see the login: sign in with your email and password, and the platform takes you back to the step where you stopped |
| After 60 minutes | The screen shows **This step has expired. Please start again.** and takes you to the sign-up form. Nothing was saved from the first attempt |
| In another browser or device | Signing in shows **Your sign-up was not finished and can no longer be continued here. Create the account again.** Select **Sign up your company** |
## Joining a company that already exists
Team members do not open a new company. They will join by invitation from the owner, and go through the same three steps.
**Status: in development**
The invitation screens are being built. This section gets its step-by-step guide when the owner can create invitations in the Business panel.
## Messages you may see
| Message | What it means | What to do |
| --- | --- | --- |
| This email already has an account. Log in instead. | There is already a Business account for this email | [Sign in](https://docs.web3card.dev/access/sign-in/), or [reset the password](https://docs.web3card.dev/access/reset-password/) |
| That code is not right or has expired. Check it and try again. | The code is wrong or too old | Check the code, or ask for a new one. After 5 wrong email codes, fill in the form again |
| That code can no longer be used. Ask for a new one. | The SMS code expired or reached 5 wrong attempts | Ask for another SMS |
| This mobile number already belongs to an account. Use another one. | The number is in use by another Business account | Use a different number |
| Wait a minute before asking for another SMS. | Less than 60 seconds since the last SMS | Wait for the countdown on the screen |
| No more SMS can be sent for now. Try again later. | An SMS limit was reached | See [the limits](https://docs.web3card.dev/access/security-and-limits/#sms). If the 3 SMS of this sign-up are used up, start again from the form |
| This step has expired. Please start again. | More than 60 minutes passed, or the step no longer exists | Create the account again |
| Too many attempts. Wait a few minutes and try again. | Too many tries in a short time from your network | Wait a few minutes |
Every message of the access screens is listed in [Security rules and limits](https://docs.web3card.dev/access/security-and-limits/#messages).
---
Source: https://docs.web3card.dev/access/create-personal-account/
# Create a Personal account
The Personal account is the account of the person who uses the card. You create it in the app of the company that offers the card program, on that company's own address.
This guide is written for end users. Companies can point their users to it.
Each company has its own address. Web3Card's own app is at `wallet.web3card.app`.
## Before you start
Have these three things at hand:
- **Access to your email.** You will receive a 6-digit code.
- **An authenticator app on your phone.** Google Authenticator, Microsoft Authenticator, Authy or 1Password all work.
- **A mobile phone that receives SMS.** You will receive one code by text message.
After you confirm your email, you have **60 minutes** to finish the other two steps. The account only exists when the last step is done.
## Open the form
1. Open the address of the app. On the login screen, select **Sign up**.
2. Fill in the form **Create your account**:
| Field | Rule |
| --- | --- |
| **Email** | An email address can have one account in each company's app |
| **Password** | At least 12 characters, with at least 1 number, 1 lowercase letter and 1 uppercase letter |
| **Invite code (optional)** | If you received an invite code, type it here. You can leave it empty |
3. Check **I agree to the Terms of Service and Privacy Policy**.
4. Select **Create account**.
The four password rules turn green on the screen as you type. Passwords are case-sensitive. Choose one that you do not use anywhere else.
## Step 1 of 3: confirm your email
1. Open the email you received and copy the 6-digit code.
2. On the screen **Confirm your email**, type it in **Code from the email**.
3. Select **Confirm email**.
Good to know:
- The code works for **15 minutes**.
- **Send a new code** sends another one. Only the newest code works.
- **After 5 wrong codes the sign-up is cancelled.** Fill in the form again to receive a new code.
- If no email arrives after you ask for a new code, select **Use a different email** and fill in the form again.
- The email brings only the code. It never has a link to click.
## Step 2 of 3: set up the authenticator app
Every sign-in asks for a code from an authenticator app. A stolen password is not enough to get into your account.
1. On the screen **Protect your account**, open your authenticator app and scan the QR code.
2. Cannot scan it? Under **Can't scan it? Type this key into the app instead:** the screen shows a key. Type it into the app.
3. The app starts showing a 6-digit code under the name of the company. Type it in the field **2. Enter the 6-digit code the app shows**.
4. Select **Continue**.
The code changes every 30 seconds. If one is refused, wait for the next.
**Keep the phone with the app**
The key is shown only on this screen. If you lose the phone later, follow [Lost your phone: replace the authenticator](https://docs.web3card.dev/access/replace-authenticator/).
## Step 3 of 3: confirm your mobile number
1. On the screen **Confirm your mobile number**, choose your **Country** and type your **Mobile number** with the area code. If your country is not on the list, choose **Other country** and type the full number, starting with the country code.
2. Select **Send code by SMS**.
3. On the screen **Enter the code we texted you**, type the code in **Code from the SMS**. The screen shows the number that received the code, partly hidden.
4. Select **Finish creating account**.
Good to know:
- The SMS code works for **10 minutes** and stops working after **5 wrong attempts**. When that happens the screen goes back to the mobile number, and you ask for another SMS.
- You can receive up to **3 SMS** per sign-up, with at least 60 seconds between one and the next. The button counts down: **Send a new code in 42s**.
- Typed the wrong number? Select **Wrong number? Change it**. Sending to the new number uses one of the 3 SMS.
- If the 3 SMS are used up, that sign-up cannot be finished. Start again from the form.
- This is the only SMS you will ever receive from the app. Signing in never uses SMS.
## You are in
When the SMS code is accepted, your account is created and you are signed in. This first session lasts 1 day.
## One account per company
Your account belongs to the app where you created it.
- Your email and your mobile number can be used once in each company's app.
- If you use the apps of two different companies, you have two independent accounts. Each has its own password and its own entry in the authenticator app.
## If you stop in the middle
| Where you stopped | What happens when you come back |
| --- | --- |
| Before confirming the email | Sign in with the email and password you chose. The app takes you to the screen **Confirm your email**. You can also fill in the form again |
| After confirming the email, in the same browser | Reloading the screen shows the same step. If you open the main address of the app, you see the login: sign in with your email and password, and the app takes you back to the step where you stopped |
| After 60 minutes | The screen shows **This step has expired. Please start again.** and takes you to the sign-up form |
| In another browser or device | Signing in shows **Your sign-up was not finished and can no longer be continued here. Create the account again.** Select **Sign up** |
## If the address does not open
| What you see | What it means | What to do |
| --- | --- | --- |
| **This address is not active** | The address you typed is not linked to a company | Check the address with the company that offers the card |
| **We could not load the page** | The app could not reach the server | Check your connection and select **Try again** |
## Messages you may see
| Message | What to do |
| --- | --- |
| This email already has an account. Sign in instead. | [Sign in](https://docs.web3card.dev/access/sign-in/), or [reset the password](https://docs.web3card.dev/access/reset-password/) |
| That code is not right or has expired. Check it and try again. | Check the code, or ask for a new one. After 5 wrong email codes, fill in the form again |
| That code can no longer be used. Ask for a new one. | The SMS code expired or reached 5 wrong attempts. Ask for another SMS |
| This mobile number already belongs to an account. Use another one. | Use a different number |
| Wait a minute before asking for another SMS. | Wait for the countdown on the screen |
| No more SMS can be sent for now. Try again later. | See [the limits](https://docs.web3card.dev/access/security-and-limits/#sms). If the 3 SMS of this sign-up are used up, start again from the form |
| This step has expired. Please start again. | Create the account again |
| Too many attempts. Wait a few minutes and try again. | Wait a few minutes |
Every message of the access screens is listed in [Security rules and limits](https://docs.web3card.dev/access/security-and-limits/#messages).
---
Source: https://docs.web3card.dev/access/sign-in/
# Sign in and sign out
Signing in works the same way in the Business panel and in the Personal app. It always has two parts: your password, then a code from your authenticator app.
## Sign in
1. Open the login screen. In the Business panel its title is **Log in to Web3Card Business**. In a Personal app the title is **Log in to your**, the name of the company and **account**.
2. Type your **Email** and **Password**.
3. **Stay signed in for 7 days** comes checked. Leave it if this is your own device. Uncheck it on a shared computer.
4. Select **Sign In**.
5. On the screen **Enter your authenticator code**, open your authenticator app and type the code in **6-digit code from the app**.
6. Select **Sign In**.
You have **5 minutes** to type the authenticator code after the password is accepted. After that, start again from the password.
In the Business panel, if you opened an address inside the panel before signing in, you land on that address after the code. The Personal app always opens on its Home screen.
## Sign out
- **Business panel.** At the bottom of the side menu, select your name. The menu shows your email and **Sign out**.
- **Personal app.** At the bottom of the menu, select your email, then **Sign out**. The **Account** screen also has a **Sign out** button.
After you sign out, the login screen opens.
## How long you stay signed in
| Option on the login screen | The session lasts |
| --- | --- |
| **Stay signed in for 7 days** checked | 7 days |
| Unchecked | 1 day |
The first session, right after you create the account, lasts 1 day.
A session also ends right away when:
- you sign out
- the password of the account is changed
- the authenticator of the account is replaced
A session can also end when the platform is updated. If that happens, sign in again.
When a session ends, the next screen you open takes you back to the login.
## About the authenticator code
- **Each code works only once.** If you have just used a code, wait for the app to show the next one.
- **The code changes every 30 seconds.** The platform also accepts the code right before and right after the current one, to tolerate small clock differences.
- **After 5 wrong codes the sign-in is cancelled.** The next attempt shows **This step has expired. Please start again.** and you start again from the password.
**Codes always refused?**
Check the clock of your phone. Authenticator codes depend on the exact time. Set the date and time of the phone to automatic and try again.
## If you did not finish creating the account
- **You did not confirm the email.** Signing in takes you straight to the screen **Confirm your email**.
- **You confirmed the email and stopped after that.** In the same browser, signing in takes you back to the step where you stopped. In another browser the screen shows **Your sign-up was not finished and can no longer be continued here. Create the account again.**
## If something goes wrong
| Message | What it means | What to do |
| --- | --- | --- |
| Invalid email or password. | The email or the password does not match. The answer is the same whether the account exists or not | Check both. Passwords are case-sensitive. Or [reset the password](https://docs.web3card.dev/access/reset-password/) |
| That code is not right or has expired. Check it and try again. | The authenticator code is wrong or was already used | Wait for the next code |
| This step has expired. Please start again. | More than 5 minutes passed since the password, or 5 wrong codes were typed | Sign in again |
| Too many attempts. Wait a few minutes and try again. | Too many tries in a short time from your network | Wait a few minutes |
| We could not load the page | The app could not reach the server | Check your connection and select **Try again** |
## Related
- Forgot the password? See [Reset your password](https://docs.web3card.dev/access/reset-password/).
- Lost the phone with the authenticator app? See [Lost your phone: replace the authenticator](https://docs.web3card.dev/access/replace-authenticator/).
- All validity periods, limits and messages are in [Security rules and limits](https://docs.web3card.dev/access/security-and-limits/).
---
Source: https://docs.web3card.dev/access/reset-password/
# Reset your password
If you forgot your password, you choose a new one with a 6-digit code sent to your email. The platform never sends a link for this. It works the same way in the Business panel and in the Personal app.
This is also the way to change a password you still remember: sign out and select **Forgot password?**
## Choose a new password
1. On the login screen, select **Forgot password?**
2. On the screen **Reset your password**, type the **Email** of your account and select **Send code**.
3. Open the email and copy the 6-digit code.
4. On the screen **Choose a new password**, type the code in **Code from the email** and type your **New password**.
5. Select **Save new password**.
6. On the screen **Password changed**, select **Go to log in** and [sign in](https://docs.web3card.dev/access/sign-in/) with the new password. The platform asks for your authenticator code, as usual.
The new password follows the same rules as the first one: at least 12 characters, with at least 1 number, 1 lowercase letter and 1 uppercase letter.
## About the code
- It works for **10 minutes**.
- It works **once**.
- It stops working after **5 wrong attempts**.
- **Send a new code** sends another one. Only the newest code works.
For privacy, the screen shows the same message whether or not an account exists for the email you typed. If no email arrives, check the address and your spam folder.
## What happens when the password changes
- **Every open session of the account is closed**, on every device. Each device has to sign in again.
- **You receive an email** telling you that the password was changed. If it was not you, contact support right away.
- **Replacing the authenticator is locked for 24 hours.** See [Lost your phone: replace the authenticator](https://docs.web3card.dev/access/replace-authenticator/).
## What does not change
Resetting the password does not change your authenticator app. You still need its code to sign in with the new password.
---
Source: https://docs.web3card.dev/access/replace-authenticator/
# Lost your phone: replace the authenticator
If you lost or changed the phone that has your authenticator app, you can set up a new one. You need your password and access to your email. It works the same way in the Business panel and in the Personal app.
## What you need
- **Your password.** The replacement starts after the password is accepted.
- **Access to the email of the account.** You will receive a 6-digit code.
- **An authenticator app on the new phone.**
- **24 hours since the password was created or last changed.** This includes a new account: on its first day the authenticator cannot be replaced. See [why](#why-the-24-hour-wait) below.
You do not need SMS, and there are no recovery codes to keep.
## Replace the authenticator
1. On the login screen, type your **Email** and **Password** and select **Sign In**.
2. On the screen **Enter your authenticator code**, select **I lost my phone**. You have 5 minutes to do it after the password is accepted.
3. The platform sends a 6-digit code to your email. On the screen **Check your email**, type it in **Code from the email** and select **Continue**.
4. On the screen **Set up your new authenticator**, scan the QR code with the authenticator app on your new phone. Cannot scan it? Type the key shown under the QR code.
5. Type the code in the field **2. Enter the 6-digit code the app shows** and select **Finish and sign in**.
Good to know:
- You have **15 minutes** to type the email code, and then another **15 minutes** to set up the new app.
- **5 wrong codes** in either step cancel the replacement. The screen shows **This step has expired. Please start again.** and you start again from the password.
- There is no button to send the email again. If the email does not arrive or the code expires, select **Back to log in**, sign in with your password and select **I lost my phone** again.
## What happens when you finish
- **The old authenticator stops working** at that moment.
- **Every open session of the account is closed**, on every device.
- **You receive an email** telling you that the authenticator was replaced. If it was not you, contact support right away.
- You are signed in on the device where you did the replacement.
## Why the 24-hour wait
The authenticator can only be replaced 24 hours after the password was created or changed. If you try earlier, this notice appears below the field on the screen **Enter your authenticator code**:
> For your security, the authenticator can only be replaced 24 hours after the password was created or changed. Try again later.
This protects you when someone gets into your email. Without the wait, that person could reset your password and replace your authenticator one after the other, and take the account in minutes. With the wait, you receive the password-change email and have a full day to react.
## What cannot be changed yet
The mobile number confirmed at sign-up cannot be changed. In the Personal app, the **Account** screen shows it under **Mobile number**, without an edit button. The platform uses SMS only once, when the account is created, so losing access to that number does not lock you out.
---
Source: https://docs.web3card.dev/access/security-and-limits/
# Security rules and limits
This page is the reference for every rule of account access. The rules are the same in the Business panel and in the Personal app.
## Password
| Rule | |
| --- | --- |
| Length | At least 12 characters |
| Numbers | At least 1 (0-9) |
| Lowercase | At least 1 (a-z) |
| Uppercase | At least 1 (A-Z) |
| Upper and lower case | Passwords are case-sensitive |
## Codes
Every code has 6 digits.
| Code | Arrives by | Works for | On the 5th wrong attempt |
| --- | --- | --- | --- |
| Email confirmation at sign-up | Email | 15 minutes | The sign-up is cancelled. Fill in the form again |
| Mobile confirmation at sign-up | SMS | 10 minutes | The code stops working. Ask for another SMS, if you still have one |
| Sign-in | Authenticator app | 30 seconds, once | The sign-in is cancelled. Type the password again |
| Password reset | Email | 10 minutes, once | The code stops working. Ask for a new one |
| Authenticator replacement | Email, then the new app | 15 minutes for each | The replacement is cancelled. Start again from the password |
When you ask for a new code by email, the previous one stops working.
## SMS
SMS is used once in the life of an account: to confirm the mobile number at sign-up.
| Limit | Value |
| --- | --- |
| Time between one SMS and the next | 60 seconds |
| SMS per sign-up | 3. Changing the number uses one of them |
| SMS to the same number | 3 every 24 hours, counted from the first one |
When a limit is reached, the screen asks you to try again later. If the 3 SMS of a sign-up are used up, that sign-up cannot be finished: start again from the form.
## Mobile number
- The number is stored in the international format, with the country code.
- It has 8 to 15 digits, counting the country code.
- Choose the country from the list, or **Other country** to type the full number.
- A zero in front of the local number is removed automatically.
- The number confirmed at sign-up cannot be changed.
## Time to finish each flow
| Flow | Time |
| --- | --- |
| Sign-up, counted from the email confirmation | 60 minutes |
| Sign-in, between the password and the authenticator code | 5 minutes |
| Authenticator replacement | 15 minutes for the email code, then 15 minutes to set up the new app |
When the time runs out, the flow starts again from the beginning.
## Sessions
| | |
| --- | --- |
| Default duration | 1 day |
| With **Stay signed in for 7 days** | 7 days |
| First session, right after sign-up | 1 day |
| Sign out | Ends the session right away |
| Password changed | Ends every session of the account |
| Authenticator replaced | Ends every session of the account |
| Platform update | May end the session. Sign in again |
A session is valid only where it was created. A session of the Business panel does not work in a Personal app, and a session in one company's app does not work in another company's app.
## One account per email and per number
| | Business panel | Personal app |
| --- | --- | --- |
| Email | One account in the whole panel | One account in each company's app |
| Mobile number | One account in the whole panel | One account in each company's app |
## Too many attempts
The platform limits how many times sign-in, codes and sign-up can be tried in a short period from the same network. When the limit is reached, the screen shows **Too many attempts. Wait a few minutes and try again.**
## What the platform never does
- **It never sends a link by email.** Every email brings a 6-digit code that you type on the site you already have open, or it is only a notice. If you receive an email with a link to sign in or to change a password, it did not come from the platform.
- **It never asks for your password or your codes** by email, by phone or by chat.
- **It never shows your authenticator key again** after the setup screen.
- **It never sends SMS after sign-up.**
## Emails you may receive
Every email is in English. The sender is the name of the company whose app you use. In the Business panel the sender is Web3Card. The subject starts with that same name.
| Subject ends with | When | What it brings |
| --- | --- | --- |
| Confirm your email | You create an account, or ask for a new code | A code that works for 15 minutes |
| Code to reset your password | You select **Forgot password?** | A code that works for 10 minutes, once |
| Code to change your authenticator app | You select **I lost my phone** | A code that works for 15 minutes |
| Your password was changed | The password of the account was changed | A notice, without a code |
| Your authenticator app was changed | The authenticator of the account was replaced | A notice, without a code |
The SMS has one line: the name of the company, the code and how long it works.
If an email does not arrive, check your spam folder and ask for a new code. If you receive a notice for something you did not do, contact support right away.
## Messages on the access screens
**When you fill in a field**
| Message | When it appears | What to do |
| --- | --- | --- |
| Enter a valid email address. | The email does not have the format of an email address | Fix the address |
| Enter your password. | Sign-in with the password empty | Type the password |
| The password does not meet the rules below. | One of the four password rules is missing | Look at the rules that are not green yet |
| Enter the name of your company. | Business sign-up with a company name shorter than 2 characters | Type the name |
| You need to accept the terms to continue. | Sign-up without checking the terms box | Check the box |
| Enter the 6-digit code. | A code with fewer than 6 digits | Type the 6 digits |
| Enter your mobile number, with the area code. | The number is too short or too long | Check the number |
| Enter the full number, starting with the country code. | With **Other country**, the number is out of the format | Type the country code and the number |
**When the platform answers**
| Message | When it appears | What to do |
| --- | --- | --- |
| Invalid email or password. | The email or the password does not match | Check both, or [reset the password](https://docs.web3card.dev/access/reset-password/) |
| This email already has an account. Log in instead. | Sign-up in the Business panel with an email that has an account | [Sign in](https://docs.web3card.dev/access/sign-in/) |
| This email already has an account. Sign in instead. | Sign-up in a Personal app with an email that has an account | [Sign in](https://docs.web3card.dev/access/sign-in/) |
| That code is not right or has expired. Check it and try again. | A code is wrong, too old or already used | Check it, wait for the next one or ask for a new one |
| That code can no longer be used. Ask for a new one. | The SMS code expired or reached 5 wrong attempts | Ask for another SMS |
| This mobile number already belongs to an account. Use another one. | The number is already in use | Use a different number |
| Wait a minute before asking for another SMS. | Less than 60 seconds since the last SMS | Wait for the countdown |
| No more SMS can be sent for now. Try again later. | An [SMS limit](#sms) was reached | Try again later, or start again from the form |
| This step has expired. Please start again. | The time of the flow ran out, or 5 wrong codes were typed | Start the flow again |
| Your sign-up was not finished and can no longer be continued here. Create the account again. | You signed in with an unfinished sign-up, in another browser | Create the account again |
| Too many attempts. Wait a few minutes and try again. | Too many tries in a short time | Wait a few minutes |
| Check the fields and try again. | The platform refused one of the fields | Check what you typed |
| Could not reach the server. Check your connection and try again. | No connection, or no answer | Check your connection |
**Notices that are not errors**
| Message | When it appears |
| --- | --- |
| New code sent. | After **Send a new code** on the SMS screen |
| If this email is waiting for confirmation, a new code is on its way. | After **Send a new code** on the screen **Confirm your email** |
| If there is an account for this email, a new code is on its way. | After **Send a new code** on the screen **Choose a new password** |
| Key copied | After the button that copies the authenticator key |
**Pages instead of a screen**
| Page | When it appears | What to do |
| --- | --- | --- |
| This address is not active | The address of a Personal app is not linked to a company | Check the address with the company that offers the card |
| We could not load the page | The app could not reach the server | Check your connection and select **Try again** |
---
Source: https://docs.web3card.dev/api/overview/
# API v2 overview
The Web3Card API lets your own systems operate your card program by code: users, identity verification, the accounts that fund the cards, the cards themselves, transactions and events.
The API covers the card program. Account access, team, branding and domain are managed in the Business panel and are not part of it.
**Status: planned**
API v2 is designed and not built yet. No endpoint is published. This page describes what the API is and the principles it follows, and details may still change. The full reference, with every endpoint, request and response, will be published in this chapter when the first version can be tested.
## One API for your program
Web3Card works as a hub connected to several card issuing partners. A program can run on one partner or on more than one.
You integrate once, with one API. Users, cards and transactions have the same format whatever institution is behind them.
Not every function exists in every program. Functions such as spending limits per card, or moving balance from a card back to the account, depend on the partner behind the program. The API tells you which functions your program has, and answers with a specific error when you call one that it does not have.
## Design principles
These are the principles the API is designed on.
| Principle | What it means for your integration |
| --- | --- |
| **Asynchronous operations** | A request that creates or changes something at the partner institution, such as requesting or freezing a card, returns an operation that you follow until it finishes. Requests that do not depend on the partner answer right away |
| **Safe retries** | Every write request carries a key chosen by you. Sending the same request twice with the same key never repeats the effect |
| **Signed events** | The platform notifies your system when something happens, such as a card becoming active or a purchase being made. Each notification is signed, so you can confirm it came from the platform |
| **Same model for every program** | Users, cards and transactions have the same format and the same states in every program |
| **Card data stays protected** | The platform does not store full card numbers, security codes or PINs |
## What the API will cover
| Area | What you will do with it |
| --- | --- |
| Users | Create and look up the users of your program |
| Identity verification | Start the verification of a user and follow its result |
| Products | List the card products available in your program |
| Funding accounts | Create the account that funds the cards, follow its balance, deposit and withdraw |
| Cards | Request, freeze, unfreeze and close cards |
| Top-up and withdrawal | Move balance from the account to a card, and from a card back to the account |
| Limits and spending controls | Set limits and restrict types of merchant, where the program has them |
| Card details | Get the full details of a card to show to its holder, through a single-use request |
| Verification codes | Receive the code that a store asks for in an online purchase |
| Operations | Follow every request you made until it finishes |
| Transactions | List purchases, refunds, deposits and top-ups |
| Events | Receive notifications in your own systems |
| Simulation | Create test purchases, refunds and settlements |
The list may change before the reference is published.
## What comes next in this chapter
1. Authentication and environments
2. Conventions: requests, responses, errors and retries
3. The reference of each area above
4. Events and how to verify their signature
5. Step-by-step guides for the most common flows
Each item is published when it can be tested.
---
Source: https://docs.web3card.dev/getting-started/quickstart/
# Quickstart
This quickstart takes you from zero to your first virtual card in five steps. It assumes you already have partner credentials; if you don't, contact [contact@web3card.dev](mailto:contact@web3card.dev) to set up your program.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## 1. Get your API key
Every request to the partner API is authenticated with your API key in the `Authorization` header:
```bash
curl https://api.web3card.dev/v1/ping \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
Sandbox keys are prefixed `w3c_test_` and operate against testnet vaults. No real funds move in sandbox mode.
## 2. Create a user
Users are the cardholders of your program. Create one with their wallet address and email:
```bash
curl -X POST https://api.web3card.dev/v1/users \
-H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@example.com",
"walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
"chain": "polygon"
}'
```
## 3. Complete KYC
Cardholders must pass identity verification before a card can be activated. Request a KYC session link and redirect your user to it:
```bash
curl -X POST https://api.web3card.dev/v1/users/usr_9f4c/kyc/session \
-H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx"
```
You will receive a `kyc.approved` webhook when verification completes. See [Users & KYC](https://docs.web3card.dev/api-reference/users-and-kyc/).
## 4. Deploy the user's vault
Each card is backed by its own multisig smart-contract vault. Deploy it on the user's chain:
```bash
curl -X POST https://api.web3card.dev/v1/vaults \
-H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "userId": "usr_9f4c", "chain": "polygon", "currency": "USDC" }'
```
## 5. Create a virtual card
```bash
curl -X POST https://api.web3card.dev/v1/cards \
-H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "userId": "usr_9f4c", "type": "virtual" }'
```
The response includes the card id and its current status:
```json
{
"id": "card_3b7c",
"userId": "usr_9f4c",
"type": "virtual",
"status": "active",
"last4": "1234",
"network": "visa",
"createdAt": "2026-07-19T14:00:00Z"
}
```
Once the vault holds a balance, the card is ready to spend. Continue with the [top-ups guide](https://docs.web3card.dev/guides/top-ups/) or subscribe to [webhooks](https://docs.web3card.dev/guides/webhooks/) for real-time events.
---
Source: https://docs.web3card.dev/getting-started/integration-models/
# Integration Models
Web3Card offers two integration models. Both run on the same infrastructure and API; they differ in how much of the card experience carries your own design.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## White-label
The fastest path to launch. Your program uses card artwork from the pre-approved layout catalog of the issuing partner, co-branded with your project name.
- Card artwork selected from pre-certified layouts
- Fast program approval, since layouts are already homologated with the network
- Virtual and physical cards
- Full API access: users, vaults, cards, transactions, webhooks
**Best for:** projects that want to launch a card program in weeks, not months.
## Custom
A fully bespoke program. Card design is 100% your own, produced with our design team and submitted to Visa for artwork approval.
- Exclusive card layout designed with your brand
- We handle the artwork approval process with Visa end to end
- Everything included in White-label
- Dedicated implementation support
**Best for:** established projects for which the card itself is a brand statement.
## Comparing the models
| | White-label | Custom |
| --- | --- | --- |
| Card artwork | Pre-approved layouts of the issuing partner | Fully bespoke, your design |
| Network artwork approval | Not required (pre-certified) | Managed by our team |
| Time to launch | Weeks | Depends on artwork approval |
| Virtual cards | ✓ | ✓ |
| Physical cards | ✓ | ✓ |
| API access | Full | Full |
| Support | Dedicated onboarding | Dedicated implementation team |
Plans and prices are on [web3card.dev](https://web3card.dev/#pricing).
---
Source: https://docs.web3card.dev/getting-started/onboarding-flow/
# Onboarding Flow
This page describes the end-to-end journey of a cardholder in your program, from signup to first payment. Each step maps to specific API calls, so you can build the entire flow inside your own product.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Flow overview
```
Signup → Wallet link → KYC → Vault deployment → Card creation → Top-up → First payment
```
## 1. Signup
Create the user with their email. The email is verified with a one-time code delivered by the platform.
- `POST /users`: create the user
- `POST /users/{id}/email/verify`: confirm the OTP code
## 2. Wallet link
The user proves ownership of their wallet by signing a message (Sign-In with Ethereum). The wallet becomes the user's authentication identity and the owner of their vault.
- `POST /auth/nonce`: generate the message to sign
- `POST /auth/verify`: verify the SIWE signature
## 3. KYC
Identity verification is required by the card network and the issuer. Web3Card provides a hosted verification flow you can embed or redirect to.
- `POST /users/{id}/kyc/session`: start a verification session
- Webhook `kyc.approved` or `kyc.rejected`: result notification
## 4. Vault deployment
With KYC approved, deploy the user's individual multisig vault on their chosen chain. The user's wallet is registered as owner; the settlement operator is added as a co-signer for authorized card settlements only.
- `POST /vaults`: deploy the vault
- `GET /vaults/{id}`: check deployment status
## 5. Card creation
Create a virtual card instantly, or start a physical card order for worldwide delivery.
- `POST /cards`: create a virtual card
- `POST /card-orders`: order a physical card
## 6. Top-up
The user funds the vault by transferring USDC, USDT, or your project token to the vault address on the selected chain. Balance updates are pushed via webhook.
## 7. First payment
The card is live. Payments are authorized in real time against the vault balance, and every transaction is available through the API and webhooks.
For details on each stage, see the [Guides](https://docs.web3card.dev/guides/create-virtual-cards/) section.
---
Source: https://docs.web3card.dev/concepts/cards/
# Cards
A Web3Card is a Visa card under your project's brand, issued by a partner institution and backed by an on-chain vault. Cards come in two forms and share the same lifecycle and API.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Virtual cards
Virtual cards are created instantly through the API. Card credentials (PAN, expiry, CVV) are delivered to the cardholder through a secure element embedded in your app or site, so sensitive data never touches your servers and your PCI DSS scope stays minimal.
Virtual cards support Apple Pay and Google Pay provisioning out of the box.
## Physical cards
Physical cards are produced with your program's artwork and shipped to cardholders worldwide. A physical card starts its life as an order (see [Order physical cards](https://docs.web3card.dev/guides/order-physical-cards/)), and must be activated by the cardholder before first use.
## Card statuses
| Status | Meaning |
| --- | --- |
| `pending` | Created, waiting for activation (physical) or provisioning (virtual) |
| `active` | Ready to transact |
| `frozen` | Temporarily blocked by the cardholder or your program |
| `lost` | Reported lost; permanently blocked |
| `stolen` | Reported stolen; permanently blocked |
| `voided` | Virtual card cancelled |
Status transitions are available through the [Cards API](https://docs.web3card.dev/api-reference/cards/). `frozen` is reversible; `lost`, `stolen`, and `voided` are terminal, and a replacement card can be created against the same vault.
## Spending controls
Each card has a daily spending limit enforced at authorization time. Limits can be read and changed through the API, with changes taking effect immediately:
- `GET /cards/{id}/limits`
- `PUT /cards/{id}/limits`
## One card, one vault
Every card settles against its own individual multisig vault. This one-to-one relationship is what keeps programs non-custodial: freezing a card never locks the user's funds, and the user can withdraw from their vault at any time. See [Vaults](https://docs.web3card.dev/concepts/vaults/).
---
Source: https://docs.web3card.dev/concepts/vaults/
# Vaults
The vault is the heart of Web3Card's non-custodial design. Every card is backed by its own multisig smart-contract vault, deployed on the cardholder's chosen chain.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## How a vault works
- **Individual.** One vault per card. Funds are never pooled with other users or with the program operator.
- **Owned by the user.** The cardholder's wallet is the vault owner. The Web3Card settlement operator is a co-signer authorized exclusively to execute settlements for card payments the user made.
- **Transparent.** The vault is a contract on a public chain. Every settlement is a verifiable on-chain transaction.
## What the vault holds
The vault holds the card's spendable balance in the program's settlement currency, plus optionally your project token when token top-ups are enabled (see [Chains & Tokens](https://docs.web3card.dev/concepts/chains-and-tokens/)).
## Settlement
When a cardholder pays with the card, the payment is authorized in real time against the vault balance. Settlement then moves the authorized amount from the vault through the settlement operator to the issuing bank as a standard Visa settlement. The full path is described in the [transaction lifecycle](https://docs.web3card.dev/concepts/transaction-lifecycle/).
## Withdrawals
The cardholder can withdraw from their vault at any time by signing a withdrawal with their owner wallet:
- `POST /vaults/{id}/withdrawals`: prepare the withdrawal transaction data
- The user signs and submits it with their own wallet
Withdrawal availability is only reduced by amounts already authorized but not yet settled.
## Spending limits on-chain
Daily card limits are mirrored by the vault contract, giving a defense-in-depth guarantee: even a compromised authorization path cannot settle more than the on-chain limit allows.
## Vault API
Deployment, configuration, balance, and withdrawal endpoints are documented in the [Vaults API reference](https://docs.web3card.dev/api-reference/vaults/).
---
Source: https://docs.web3card.dev/concepts/chains-and-tokens/
# Chains & Tokens
Web3Card is multichain. Each user picks the chain where their vault lives, and each program defines which tokens it accepts for top-ups.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Supported chains
| Chain | Identifier | Vaults | Notes |
| --- | --- | --- | --- |
| Ethereum | `ethereum` | ✓ | Mainnet |
| Polygon | `polygon` | ✓ | PoS |
| Arbitrum | `arbitrum` | ✓ | Arbitrum One |
| BNB Chain | `bnb` | ✓ | BSC |
Additional chains are added program by program. Talk to your integration manager about chains not listed here.
## Settlement currencies
Card authorizations settle in stablecoins:
| Token | Identifier | Chains |
| --- | --- | --- |
| USDC | `USDC` | All supported chains |
| USDT | `USDT` | All supported chains |
The program's settlement currency is configured per vault at deployment (`currency` field).
## Project tokens
Programs can enable top-ups in their own token. When a user tops up with the project token, the platform converts it to the vault's settlement currency at market rate at the moment of top-up, and credits the vault with the resulting stablecoin balance.
This gives your token a concrete, daily utility: it becomes a way to load a card that works anywhere.
```json
{
"topUp": {
"token": "YOURTOKEN",
"amountIn": "1500.00",
"converted": { "currency": "USDC", "amountOut": "487.35" },
"rate": "0.32490",
"chain": "polygon"
}
}
```
Token top-up availability, pairs, and conversion venues are configured during program onboarding.
---
Source: https://docs.web3card.dev/concepts/transaction-lifecycle/
# Transaction Lifecycle
Every card payment travels the same path, from the terminal to on-chain settlement. Understanding this lifecycle helps you build accurate balance displays and transaction feeds.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Stages
```
Authorization → Clearing → Settlement (on-chain)
```
### 1. Authorization
The cardholder taps or enters the card. Visa routes the authorization request to Web3Card, which checks in real time:
- Card status is `active`
- Amount is within the card's daily limit
- The vault balance covers the amount
If all checks pass, the amount is put on hold and the merchant receives approval, typically in under a second. The transaction appears with status `pending`.
### 2. Clearing
The merchant submits the final capture (usually within hours, up to a few days for hotels and similar). The captured amount replaces the hold; small differences (tips, currency adjustments) are normal.
### 3. Settlement
The captured amount is settled from the user's vault: the settlement operator co-signs a transfer out of the vault, and funds flow to the issuing bank as standard Visa settlement. The transaction status becomes `settled`, and the on-chain transfer hash is attached to the transaction record.
## Transaction statuses
| Status | Meaning |
| --- | --- |
| `pending` | Authorized, amount on hold |
| `settled` | Cleared and settled on-chain |
| `declined` | Authorization refused (limit, balance, card status) |
| `reversed` | Authorization released without capture |
| `refunded` | Merchant refund credited back to the vault |
| `disputed` | Chargeback in progress |
## Refunds and disputes
Refunds arrive as separate credit transactions to the vault. Disputes can be opened through the API within 60 days of settlement; see [Transactions API](https://docs.web3card.dev/api-reference/transactions/).
## Real-time events
Every status change emits a webhook (`transaction.created`, `transaction.updated`), so your app can show payment activity live. See [Webhooks](https://docs.web3card.dev/guides/webhooks/).
---
Source: https://docs.web3card.dev/guides/create-virtual-cards/
# Create Virtual Cards
Virtual cards are created instantly and are ready for online payments and wallet provisioning (Apple Pay / Google Pay) as soon as the backing vault is funded.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Prerequisites
- User created and email verified
- KYC approved (`kyc.approved` webhook received)
- Vault deployed for the user
## Create the card
```bash
curl -X POST https://api.web3card.dev/v1/cards \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "userId": "usr_9f4c", "type": "virtual" }'
```
```json
{
"id": "card_3b7c",
"userId": "usr_9f4c",
"type": "virtual",
"status": "active",
"last4": "1234",
"network": "visa",
"vaultId": "vlt_77aa",
"createdAt": "2026-07-19T14:00:00Z"
}
```
## Display card credentials securely
Full card credentials are never returned by the API. To show PAN, expiry, and CVV to the cardholder, embed the **secure element**: a hosted, PCI-compliant iframe scoped to a single card and session.
```bash
curl -X POST https://api.web3card.dev/v1/cards/card_3b7c/secure-session \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
```json
{ "url": "https://secure.web3card.dev/e/card_3b7c?st=abc123", "expiresIn": 300 }
```
Render the returned URL in an iframe inside your app. The session is single-use and expires in five minutes.
## Wallet provisioning
Virtual cards can be added to Apple Pay and Google Pay by the cardholder directly from the secure element UI, or programmatically through push provisioning if your app is enrolled with the wallets.
## Freezing and voiding
```bash
# Freeze (reversible)
curl -X POST https://api.web3card.dev/v1/cards/card_3b7c/freeze \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
# Void (terminal)
curl -X POST https://api.web3card.dev/v1/cards/card_3b7c/void \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
Voiding a card does not touch the vault: the user's balance stays intact and a new card can be created against the same vault.
---
Source: https://docs.web3card.dev/guides/order-physical-cards/
# Order Physical Cards
Physical cards carry your program's artwork and ship worldwide. Ordering is a small state machine: you create an order, it is produced and shipped, and the cardholder activates the card on delivery.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Order states
```
created → confirmed → in_production → shipped → delivered → activated
```
An order can be cancelled while in `created` or `confirmed`. After `in_production`, cancellation is no longer possible.
## Create the order
```bash
curl -X POST https://api.web3card.dev/v1/card-orders \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"userId": "usr_9f4c",
"shippingAddress": {
"line1": "Av. Paulista 1000",
"city": "Sao Paulo",
"state": "SP",
"postalCode": "01310-100",
"country": "BR"
}
}'
```
```json
{
"id": "ord_51de",
"userId": "usr_9f4c",
"status": "created",
"estimatedDelivery": "2026-08-04",
"createdAt": "2026-07-19T14:00:00Z"
}
```
## Track the order
```bash
curl https://api.web3card.dev/v1/card-orders/ord_51de \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
Order status changes also arrive as `card_order.updated` webhooks, including the carrier tracking code once shipped.
## Activation
On delivery, the cardholder activates the card by confirming the last four digits and setting a PIN, either in your app through the API or in the secure element UI:
```bash
curl -X POST https://api.web3card.dev/v1/cards/card_8a1f/activate \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "last4": "5678" }'
```
The physical card settles against the same vault as the user's virtual card, sharing balance and limits.
---
Source: https://docs.web3card.dev/guides/top-ups/
# Top-ups
A card is spendable while its vault holds balance. Users top up by transferring supported tokens to their vault address; no API call is required to receive funds, though the API provides everything you need to build a great top-up UX.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Get the deposit address
The vault address is the deposit address. Show it (and a QR code) in your app:
```bash
curl https://api.web3card.dev/v1/vaults/vlt_77aa \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
```json
{
"id": "vlt_77aa",
"userId": "usr_9f4c",
"chain": "polygon",
"address": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
"currency": "USDC",
"balance": "487.35",
"status": "active"
}
```
Deposits must be sent on the vault's chain. Tokens sent on a different chain are not credited automatically; recovery requires manual support intervention.
## Stablecoin top-ups
Transfers of the vault's settlement currency (USDC or USDT) are credited as soon as the transfer reaches finality on the vault's chain. A `vault.credited` webhook is emitted with the amount and transaction hash.
## Project token top-ups
If your program has token top-ups enabled, transfers of your project token to the vault are converted to the settlement currency at market rate and credited as stablecoin balance. The conversion details are attached to the webhook event:
```json
{
"type": "vault.credited",
"data": {
"vaultId": "vlt_77aa",
"source": "token_conversion",
"tokenIn": "YOURTOKEN",
"amountIn": "1500.00",
"currency": "USDC",
"amountCredited": "487.35",
"rate": "0.32490",
"txHash": "0x9c2f…e11a"
}
}
```
## Balance display
Use `GET /vaults/{id}` for the authoritative balance. The `balance` field already excludes amounts held by pending authorizations, so it is safe to display as "available to spend".
---
Source: https://docs.web3card.dev/guides/webhooks/
# Webhooks
Webhooks push events to your backend in real time: transactions, KYC results, vault credits, card and order status changes. They are the backbone of a responsive card UX.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Subscribe
Register your endpoint and select the events you want:
```bash
curl -X POST https://api.web3card.dev/v1/webhooks \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.yourproject.com/hooks/web3card",
"events": ["transaction.*", "kyc.*", "vault.credited", "card_order.updated"]
}'
```
```json
{ "id": "wh_2210", "status": "active", "secret": "whsec_9k3j…" }
```
## Verify signatures
Every delivery is signed. Compute an HMAC SHA-256 of the raw body with your webhook secret and compare it to the `X-W3C-Signature` header:
```js
const crypto = require("crypto");
function verify(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
```
Reject any delivery whose signature does not match.
## Event catalog
| Event | Emitted when |
| --- | --- |
| `transaction.created` | A new authorization is approved or declined |
| `transaction.updated` | A transaction changes status (settled, refunded, disputed…) |
| `vault.credited` | A top-up is credited to a vault |
| `vault.debited` | A settlement or withdrawal leaves a vault |
| `kyc.approved` | Identity verification approved |
| `kyc.rejected` | Identity verification rejected |
| `card.updated` | Card status change (frozen, lost, voided…) |
| `card_order.updated` | Physical card order progresses |
## Delivery and retries
Deliveries expect a `2xx` response within 10 seconds. Failed deliveries are retried with exponential backoff for up to 24 hours. Events are delivered at least once; use the event `id` for idempotent processing.
---
Source: https://docs.web3card.dev/api-reference/overview/
# API Reference
The Web3Card API is a REST API over HTTPS with JSON request and response bodies.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Base URL
```
https://api.web3card.dev/v1
```
## Authentication
All partner endpoints require your API key as a Bearer token:
```
Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx
```
End-user sessions (for actions signed by the cardholder's wallet) use Sign-In with Ethereum on top of the partner key. See [Authentication](https://docs.web3card.dev/api-reference/authentication/).
## Environments
| Environment | Key prefix | Behavior |
| --- | --- | --- |
| Live | `w3c_live_` | Real cards, mainnet vaults |
| Sandbox | `w3c_test_` | Test cards, testnet vaults, simulated authorizations |
## Errors
Errors use conventional HTTP status codes and a consistent body:
```json
{
"error": {
"code": "insufficient_balance",
"message": "Vault balance does not cover the requested amount.",
"requestId": "req_b81f2c"
}
}
```
| Status | Meaning |
| --- | --- |
| `400` | Invalid request body or parameters |
| `401` | Missing or invalid API key |
| `403` | Key valid but not allowed for this resource |
| `404` | Resource not found |
| `409` | Conflict with resource state (e.g. activating a voided card) |
| `429` | Rate limit exceeded |
| `5xx` | Platform error; safe to retry with backoff |
Include the `requestId` when contacting support about a specific call.
## Pagination
List endpoints return pages with an opaque cursor:
```
GET /transactions?limit=50&cursor=eyJvZmZzZXQiOjUwfQ
```
```json
{ "data": [ … ], "nextCursor": "eyJvZmZzZXQiOjEwMH0" }
```
`nextCursor` is `null` on the last page.
## Idempotency
Send an `Idempotency-Key` header on any `POST` you may retry. Two calls with the same key return the same result and create at most one resource.
---
Source: https://docs.web3card.dev/api-reference/authentication/
# Authentication
Two layers of authentication cover the two kinds of callers:
1. **Partner authentication:** your backend, with an API key.
2. **User authentication:** the cardholder, with their wallet (Sign-In with Ethereum), for actions that must be signed by the vault owner.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## Partner API keys
Keys are issued per environment during onboarding and sent as a Bearer token:
```bash
curl https://api.web3card.dev/v1/users \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
Keys can be rotated at any time from the partner dashboard. Old keys keep working for 24 hours after rotation.
## Sign-In with Ethereum (SIWE)
Vault-owner actions (withdrawals, adding wallets, changing on-chain limits) require a user session proven by a wallet signature.
### POST /auth/nonce
Generate the message the user must sign.
```json
// Request
{ "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F" }
// Response
{
"nonce": "kX9m2pQr",
"message": "web3card.dev wants you to sign in with your Ethereum account…"
}
```
### POST /auth/verify
Verify the SIWE signature and open a user session.
```json
// Request
{
"walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
"signature": "0x8b4d…c91e"
}
// Response
{ "sessionToken": "w3cs_a91k…", "expiresIn": 3600 }
```
Send the session token alongside your API key on user-signed endpoints:
```
Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx
X-W3C-User-Session: w3cs_a91k…
```
## Email verification
### POST /users/\{id\}/email/otp
Send a one-time code to the user's email.
### POST /users/\{id\}/email/verify
```json
// Request
{ "code": "482913" }
// Response
{ "verified": true }
```
---
Source: https://docs.web3card.dev/api-reference/users-and-kyc/
# Users & KYC
Users are the cardholders of your program. A user must have a verified email, a linked wallet, and approved KYC before a card can be created.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## POST /users
Create a user.
```json
// Request
{
"email": "ana@example.com",
"walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
"chain": "polygon"
}
// Response
{
"id": "usr_9f4c",
"email": "ana@example.com",
"emailVerified": false,
"walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
"kycStatus": "not_started",
"createdAt": "2026-07-19T14:00:00Z"
}
```
## GET /users/\{id\}
Retrieve a user's profile, verification state, and linked resources (vaults, cards).
## GET /users
List your program's users. Supports `limit`, `cursor`, and `kycStatus` filters.
## KYC
Identity verification runs through a hosted flow provided by the platform's verification partner. You never handle identity documents.
### POST /users/\{id\}/kyc/session
Create a verification session and receive the URL to redirect or embed:
```json
// Response
{
"url": "https://verify.web3card.dev/s/usr_9f4c?vt=abc123",
"expiresIn": 1800
}
```
### KYC statuses
| Status | Meaning |
| --- | --- |
| `not_started` | No session created yet |
| `pending` | Documents submitted, under review |
| `approved` | Verification passed; cards can be created |
| `rejected` | Verification failed; details in the webhook payload |
Status changes are pushed as `kyc.approved` / `kyc.rejected` webhooks and are also readable on the user profile.
### Phone verification
Some jurisdictions require a verified phone number:
- POST `/users/{id}/phone/otp`: send SMS code
- POST `/users/{id}/phone/verify`: confirm code
---
Source: https://docs.web3card.dev/api-reference/cards/
# Cards API
Create and manage the cards of your program. See [Cards concepts](https://docs.web3card.dev/concepts/cards/) for statuses and lifecycle.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## POST /cards
Create a virtual card for a user with an active vault.
```json
// Request
{ "userId": "usr_9f4c", "type": "virtual" }
// Response
{
"id": "card_3b7c",
"userId": "usr_9f4c",
"vaultId": "vlt_77aa",
"type": "virtual",
"status": "active",
"last4": "1234",
"network": "visa",
"createdAt": "2026-07-19T14:00:00Z"
}
```
## GET /cards
List cards. Filters: `userId`, `status`, `type`.
## GET /cards/\{id\}
Retrieve a card and its current status.
## POST /cards/\{id\}/activate
Activate a delivered physical card.
```json
// Request
{ "last4": "5678" }
```
## POST /cards/\{id\}/freeze
Temporarily block authorizations. Reversible.
## POST /cards/\{id\}/unfreeze
Lift a freeze and return the card to `active`.
## POST /cards/\{id\}/report-lost
Permanently block a card reported lost. Terminal.
## POST /cards/\{id\}/report-stolen
Permanently block a card reported stolen. Terminal.
## POST /cards/\{id\}/void
Cancel a virtual card. Terminal. The vault and its balance are unaffected.
## GET /cards/\{id\}/limits
```json
// Response
{ "daily": { "amount": "1000.00", "currency": "USDC", "spentToday": "112.40" } }
```
## PUT /cards/\{id\}/limits
Set the daily limit. Requires a user session (vault-owner signed).
```json
// Request
{ "daily": { "amount": "2500.00" } }
```
## POST /cards/\{id\}/secure-session
Create a single-use secure element session to display full card credentials to the cardholder. See [Create Virtual Cards](https://docs.web3card.dev/guides/create-virtual-cards/).
---
Source: https://docs.web3card.dev/api-reference/vaults/
# Vaults API
Deploy and manage the multisig smart-contract vaults that back each card. See [Vaults concepts](https://docs.web3card.dev/concepts/vaults/).
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## POST /vaults
Deploy a vault for a KYC-approved user.
```json
// Request
{ "userId": "usr_9f4c", "chain": "polygon", "currency": "USDC" }
// Response
{
"id": "vlt_77aa",
"userId": "usr_9f4c",
"chain": "polygon",
"currency": "USDC",
"address": null,
"status": "deploying",
"createdAt": "2026-07-19T14:00:00Z"
}
```
Deployment is asynchronous. The vault becomes `active` when the contract is live, and the `address` field is populated. A `vault.deployed` webhook is emitted.
## GET /vaults/\{id\}
Retrieve a vault, its address, status, and available balance.
```json
// Response
{
"id": "vlt_77aa",
"userId": "usr_9f4c",
"chain": "polygon",
"currency": "USDC",
"address": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
"balance": "487.35",
"status": "active"
}
```
`balance` is the spendable amount: on-chain balance minus pending authorization holds.
## GET /vaults
List vaults. Filters: `userId`, `chain`, `status`.
## GET /vaults/\{id\}/owners
List the vault's owner wallets.
## POST /vaults/\{id\}/owners
Add an owner wallet. Requires a user session; returns EIP-712 typed data for the current owner to sign.
## DELETE /vaults/\{id\}/owners/\{address\}
Remove an owner wallet. Requires a user session and owner signature.
## POST /vaults/\{id\}/withdrawals
Prepare a withdrawal from the vault to the owner's wallet. Returns the transaction data for the owner to sign and submit with their own wallet.
```json
// Request
{ "amount": "200.00", "to": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F" }
// Response
{
"to": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
"data": "0xa9059cbb…",
"value": "0",
"chainId": 137
}
```
Withdrawals never require platform approval: the vault owner can always exit with their funds.
---
Source: https://docs.web3card.dev/api-reference/transactions/
# Transactions API
Read the payment activity of your program's cards. See [Transaction Lifecycle](https://docs.web3card.dev/concepts/transaction-lifecycle/) for statuses and stages.
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## GET /transactions
List transactions across your program. Filters: `userId`, `cardId`, `status`, `from`, `to`. Paginated with `limit` and `cursor`.
```json
// Response
{
"data": [
{
"id": "txn_c410",
"cardId": "card_3b7c",
"userId": "usr_9f4c",
"status": "settled",
"amount": "42.90",
"currency": "USDC",
"merchant": {
"name": "AIRLINE TICKETS LTD",
"category": "airlines",
"country": "US"
},
"authorizedAt": "2026-07-18T09:12:44Z",
"settledAt": "2026-07-19T02:03:10Z",
"settlementTxHash": "0x9c2f…e11a"
}
],
"nextCursor": null
}
```
`settlementTxHash` links every settled payment to its verifiable on-chain settlement.
## GET /transactions/\{id\}
Retrieve a single transaction with its full event history (authorization, capture, settlement, refunds).
## GET /transactions/dispute-reasons
List the accepted dispute reason codes.
```json
// Response
{
"data": [
{ "code": "fraud", "label": "Unauthorized transaction" },
{ "code": "not_received", "label": "Goods or services not received" },
{ "code": "duplicate", "label": "Duplicate charge" },
{ "code": "amount_differs", "label": "Charged amount differs" }
]
}
```
## POST /transactions/\{id\}/disputes
Open a dispute for a settled transaction. Available within 60 days of settlement.
```json
// Request
{ "reason": "duplicate", "comment": "Charged twice for the same order." }
// Response
{ "id": "dsp_11ba", "transactionId": "txn_c410", "status": "open" }
```
Dispute progress is delivered through `transaction.updated` webhooks with the embedded `dispute` object.
---
Source: https://docs.web3card.dev/api-reference/webhooks/
# Webhooks API
Manage the webhook subscriptions of your program. For signature verification, retries, and the full event catalog, see the [Webhooks guide](https://docs.web3card.dev/guides/webhooks/).
**API v1 · Legacy**
This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: [API v2](https://docs.web3card.dev/api/overview/) replaces it, and the platform today works as described in the rest of this manual.
## POST /webhooks
Create a subscription.
```json
// Request
{
"url": "https://api.yourproject.com/hooks/web3card",
"events": ["transaction.*", "kyc.*", "vault.credited"]
}
// Response
{
"id": "wh_2210",
"url": "https://api.yourproject.com/hooks/web3card",
"events": ["transaction.*", "kyc.*", "vault.credited"],
"status": "active",
"secret": "whsec_9k3j…"
}
```
The `secret` is returned only on creation. Store it securely; it signs every delivery.
## GET /webhooks
List your subscriptions.
## GET /webhooks/\{id\}
Retrieve a subscription and its recent delivery stats.
## PATCH /webhooks/\{id\}
Update the URL or event selection.
## DELETE /webhooks/\{id\}
Delete a subscription. Pending retries are cancelled.
## POST /webhooks/\{id\}/rotate-secret
Rotate the signing secret. The old secret keeps validating deliveries for one hour to allow zero-downtime rotation.
## POST /webhooks/\{id\}/test
Send a signed `ping` event to your endpoint to validate connectivity end to end.
```json
// Response
{ "delivered": true, "responseStatus": 200, "latencyMs": 184 }
```
## Delivery format
```json
{
"id": "evt_88d1",
"type": "transaction.created",
"createdAt": "2026-07-19T14:00:00Z",
"data": { … }
}
```
Headers on every delivery:
| Header | Content |
| --- | --- |
| `X-W3C-Signature` | HMAC SHA-256 of the raw body |
| `X-W3C-Event-Id` | Event id, for idempotent processing |
| `X-W3C-Event-Type` | Event type |
---
Source: https://docs.web3card.dev/glossary/
# Glossary
The terms used across this documentation, in alphabetical order.
## Authenticator app
An app on your phone that shows a 6-digit code that changes every 30 seconds. Google Authenticator, Microsoft Authenticator, Authy and 1Password are examples. Every sign-in on the platform asks for this code. Also called two-factor authentication, or 2FA.
## Business panel
The side of the platform used by the company that runs a card program, and by its team. It has one address for every company: `business.web3card.dev`. See [How the platform works](https://docs.web3card.dev/platform/overview/).
## Card program
The set of cards a company offers to its users, with its rules, its brand and the partner institution that issues the cards.
## CNAME
A record in the DNS of a domain that points one address to another. A company creates one CNAME to connect its own subdomain to the platform. See [Your own domain](https://docs.web3card.dev/platform/white-label/#your-own-domain).
## Company
The business that uses Web3Card to run a card program. In the platform, a company has one owner, a team, a brand and its own users.
## End user
The person who holds and uses the card. End users sign up in the Personal app of a company.
## KYB
Know Your Business. The verification of a company: who owns it, where it is registered and what it does.
## KYC
Know Your Customer. The verification of the identity of a person, required before a card can be used.
## Member
A person who joins the team of a company in the Business panel by invitation from the owner.
## Owner
The person who created the company in the Business panel. Inviting team members will be done by the owner.
## Partner institution
A licensed and regulated financial institution within the Visa network. Partner institutions issue the cards. Web3Card provides the software.
## Personal app
The side of the platform used by end users. Each company has its own, on its own domain and with its own brand. See [How the platform works](https://docs.web3card.dev/platform/overview/).
## Session
The period during which you stay signed in on a device. It lasts 1 day, or 7 days when you choose **Stay signed in for 7 days**. It ends earlier when you sign out, when the password or the authenticator changes, or when the platform is updated. See [Sign in and sign out](https://docs.web3card.dev/access/sign-in/).
## Stablecoin
A digital currency designed to keep the value of a traditional currency. The cards on the platform are funded with dollar stablecoins such as USDC and USDT.
## Theme
The set of colors of the app. There are four: Graphite Dark, Graphite Light, Gold Dark and Ivory. A company chooses one as the default for its users, and each person can pick another on their own device. See [White-label](https://docs.web3card.dev/platform/white-label/).
## White-label
Software provided by one company and presented under the brand of another. On Web3Card, your users see your name, your logo and your domain. See [White-label](https://docs.web3card.dev/platform/white-label/).