Virtual Cards
Create and manage virtual cardsVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. for your customers using our MultiMulti Weavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise. API. Virtual cardsVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. are created instantly and can be used for e-commerce and online purchases.
Onboard an Identity
You must assign a virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. to a corporate or consumer identity before the card can be used. This identity can also be described as the card owner.
Onboard corporate identities by following the corporate identity onboarding guide and consumer identities by following the consumer identity onboarding guide.
Create a card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds.
Weavr does not support anonymous cards. All cards must be linked to a card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds.. Therefore, for a card to be used, it must be linked to a card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. that has been created in the system as an Authorised User.
Follow the steps in the Authorised User section to create the user, set their credentials, and verify their mobile number by enrolling them for an authentication factor.
For a card to be used for purchases online, provisioned to a digital wallet, or upgraded to a physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use., it must be assigned to a user that has provided:
- First and last name
- An email address; validation of which (via user invite, or email verification process) is optional
- A mobile number, that has been enrolled for an authentication factor (such as SMS OTP)
- Date of birth
- Country of residence (optional). This ensures compliance checks are completed more quickly
Not all of the user information may be available, or the user able to complete all the steps, at the point when the card is created. The intended user may not even be known yet. Therefore a card can be created without being linked to a user, but will remain in a NOT_ENABLED state. The card can even be provisionally assigned to a card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. with incomplete information, but again this card will remain in a NOT_ENABLED state. It will be made ACTIVE when all of the information and steps have been completed for the linked user.
The sensitive card details (cardNumber and cvv) are not accessible for a card in a NOT_ENABLED state. Only once a card is made ACTIVE are these details made available.
| Behaviour dependent on card state | NOT_ENABLED | ACTIVE |
|---|---|---|
Sensitive card details (cardNumber and cvv) provided in API responses | ✗ | ✓ |
| Provision to a digital wallet (Google Pay or Apple Pay) | ✗ | ✓ |
| Upgrade card to physical | ✗ | ✓ |
If all information is available for the linked user at the point of card creation, the virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. can be created fully active.
To create a card for the logged-in identity, you need to provide the profileId. You can find your card profile IDs in the Multi Portal > Settings > Profiles section. Card profiles contain configuration that determines the behaviour and properties of the card.
Create a virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode.
Create and assign a virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. that is active immediately
Create an Authorised User (or have an existing user ready) that has all of the mandatory information provided, and the appropriate card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. role assigned. When creating the card, provide the userId of the user.
Log in an End-User
To create a card for an identity, you must log in an end-user belonging to the identity. You need your API key and an active end-user authentication token to create a card. Read more about authentication in the authentication guide.
Stepped-up Token
It is not mandatory for the end-user to have performed two-factor authentication to create a managed cardManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User.. However, for sensitive card details to be returned in the response, your active end-user token is required to be stepped-up. For more instructions on how to step-up read step-up authentication.
Create the card
You can create virtual cardsVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. in prepaid or debit modeDebit Mode A card mode where the card does not have a balance of its own. Instead, debit cards are linked to a parent managed account and the system uses the linked account's balance to authorise and settle purchases registered on the card. Spend limits can be specified on the card via spend controls.. This determines the funds that the card has access to. Read more about the different modes in the card modes guide.
nameOnCard is a separate field in the create a virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. endpoint. This is because cards can only accommodate fewer characters than are allowed in the name fields of the Authorised User. Wherever possible, the nameOnCard should match the name of the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds./Authorised User. When this is not possible, a shortened version of the name should be used. This is the name that should be quoted by the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. when making online purchases when asked for the "card holder" name.
Since all of the mandatory information for the linked user has been provided, the card is created in an ACTIVE state. For ACTIVE cards, the sensitive card details are accessible immediately. As long as the API request was stepped up, and the caller has the correct permissions from their role, the sensitive card details will automatically be included in the synchronous response to the API call.
All the card details (both sensitive and non-sensitive card details) can also be retrieved via GET /managed_cards/{id}.
The response contents to GET /managed_cards/{id} endpoint depends on authentication level, caller, and card state.
Sensitive details are returned only when ALL of the following are true:
- Caller is the linked user (or user with the Admin role)
- Token is stepped-up
- Card is in
ACTIVEstate (or has previously reached an active state)
Otherwise, only non-sensitive details are returned.
| Caller | Token | Card state | Response |
|---|---|---|---|
| Linked user | Stepped-up | ACTIVE | Sensitive/all details |
| Linked user | Stepped-up | NOT_ENABLED | Non-sensitive details only |
| Linked user | Not stepped-up | ACTIVE | Non-sensitive details only |
| Admin (own card) | Stepped-up | ACTIVE | Sensitive/all details |
| Admin (other's card) | Stepped-up | ACTIVE | Sensitive/all details |
| Cards Management Role (other's card) | Stepped-up | ACTIVE | Non-sensitive details only |
Sensitive card information will tokenised in the API response. Read more about tokenisation here.
Sensitive/all details are also returned for cards in state BLOCKED or DESTROYED as long as they were previously in an ACTIVE state.
Create cards in advance in a not-enabled state
Not all mandatory information may be available for the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. at the point of card creation; or the intended user may not even be known yet. Weavr allows you to create cards in this scenario but they will be in a NOT_ENABLED state.
When a card is created:
Linked userId | Card state |
|---|---|
| Not provided | NOT_ENABLED |
| Provided, but linked user has incomplete information | NOT_ENABLED |
| Full mandatory information is provided for linked user | ACTIVE |
Therefore, certain information that is optional for a user at the point of creation, becomes mandatory before a virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. they are linked to can be made active and become usable.
The card will automatically become active (and a webhook sent) once all relevant information for the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. is provided.
Log in an End-User
To create a card for an identity, you must log in an end-user belonging to the identity. You need your API key and an active end-user authentication token to create a card. Read more about authentication in the authentication guide.
Stepped-up Token
It is not mandatory for the end-user to have performed two-factor authentication to create a managed cardManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User. for an unlinked card or a card linked to a user with incomplete information, since it will be created in a NOT_ENABLED state and sensitive card details will not be returned in the response. Sensitive information (cardNumber and cvv) will only be accessible once the card has been enabled.
Create the card
You can create virtual cardsVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. in prepaid or debit modeDebit Mode A card mode where the card does not have a balance of its own. Instead, debit cards are linked to a parent managed account and the system uses the linked account's balance to authorise and settle purchases registered on the card. Spend limits can be specified on the card via spend controls.. This determines the funds that the card has access to. Read more about the different modes in the card modes guide.
nameOnCard is a separate field in the create a virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. endpoint. This is because cards can only accommodate fewer characters than are allowed in the name fields of the Authorised User. Wherever possible, the nameOnCard should match the name of the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds./Authorised User. When this is not possible, a shortened version of the name should be used. This is the name that should be quoted by the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. when making online purchases when asked for the "card holder" name.
Enable a virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode.
A virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. will only be enabled for use (and sensitive details made available) once all mandatory information is provided for the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds.. See the card users section.
This normally means providing all of the following information:
- First and last name
- An email address; validation of which (via user invite, or email verification process) is optional
- A mobile number, that has been enrolled for an authentication factor (such as SMS OTP)
- Date of birth
- Country of residence (optional). This ensures compliance checks are completed more quickly
If any of the information listed is not available at the point of creating the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds., it can be updated via PATCH /users/${ID} at a later time.
Once all the information for the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. is provided the card will be enabled automatically. A card state change webhook will be sent with state: ACTIVE.
All the card details (both sensitive and non-sensitive card details) can also be retrieved via GET /managed_cards/{id}.
The response contents to GET /managed_cards/{id} endpoint depends on authentication level, caller, and card state.
Sensitive details are returned only when ALL of the following are true:
- Caller is the linked user (or user with the Admin role)
- Token is stepped-up
- Card is in
ACTIVEstate (orBLOCKED)
Otherwise, only non-sensitive details are returned.
| Caller | Token | Card state | Response |
|---|---|---|---|
| Linked user | Stepped-up | ACTIVE | Sensitive/all details |
| Linked user | Stepped-up | NOT_ENABLED | Non-sensitive details only |
| Linked user | Not stepped-up | ACTIVE | Non-sensitive details only |
| Admin (own card) | Stepped-up | ACTIVE | Sensitive/all details |
| Admin (other's card) | Stepped-up | ACTIVE | Sensitive/all details |
| Cards Management Role (other's card) | Stepped-up | ACTIVE | Non-sensitive details only |
Sensitive card information will tokenised in the API response. Read more about tokenisation here.
Sensitive/all details are also returned for cards in state BLOCKED or DESTROYED as long as they were previously in an ACTIVE state.