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.
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
- Authentication and environments
- Conventions: requests, responses, errors and retries
- The reference of each area above
- Events and how to verify their signature
- Step-by-step guides for the most common flows
Each item is published when it can be tested.