Provision virtual accounts
Understand the process for instantly issuing a digital-only virtual card for your users. This guide covers the steps required to create a card ready for immediate online use.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to issue a virtual card and associate it with a user account.
- You want to issue a card (virtual) to a user that can be immediately usable after card creation.
- You want to issue a virtual card that can be used for e-commerce or online purchases.
- You want to issue disposable or one-time transaction virtual cards that can be discarded after their card transactions are settled.
Prerequisites
- The user profile risk assessment status must not be
risk_flagged. - The user profile must be in an
activestatus. - The user must have an
approvedKYC or KYB status. - The user account or wallet must be in an
activestatus.
API Workflow
1
Retrieve available card types
Call the Get Card Types (GET /users/wallets/cards/types) to get a list of available card products enabled in the program.
Note that this API uses public scope. Ensure X-Auth-User-ID is not passed when calling this API.
Get Card Types API request
CURL
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••'Get Card Types API response
JSON
{
"types": [
{
"code": "sgmmdemomcpcard",
"name": "MatchMove Physical Card",
"description": "MatchMove Physical Card",
"form_factor": "physical",
"personalised_order": false,
"token": {
"type": "CVV",
"generation": "static"
},
"currency": [
"USD"
],
"image": {
"small": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-small.png",
"medium": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-medium.png",
"large": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-large.png"
},
"details": {
"max_load_limit": 500000,
"network_type": "mastercard",
"fee": "0.00",
"fee_currency": "USD",
"max_count": 10,
"topup_limits": {
"pre_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 2250,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 2250,
"weekly_count_limit": null,
"weekly_transactional_limit": 2250,
"annual_count_limit": null,
"annual_transactional_limit": 15000,
"unit_transactional_limit": 750
},
"post_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 500000,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 500000,
"weekly_count_limit": null,
"weekly_transactional_limit": 500000,
"annual_count_limit": null,
"annual_transactional_limit": null,
"unit_transactional_limit": 500000
}
},
"deduct_limits": {
"pre_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 2250,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 2250,
"weekly_count_limit": null,
"weekly_transactional_limit": 2250,
"annual_count_limit": null,
"annual_transactional_limit": 15000,
"unit_transactional_limit": 750
},
"post_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 500000,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 500000,
"weekly_count_limit": null,
"weekly_transactional_limit": 500000,
"annual_count_limit": null,
"annual_transactional_limit": null,
"unit_transactional_limit": 500000
}
}
}
},
{
"code": "sgmmdemomccard",
"name": "MatchMove Virtual Card",
"description": "MatchMove Virtual Card",
"form_factor": "virtual",
"personalised_order": false,
"token": {
"type": "CVV",
"generation": "static"
},
"currency": [
"USD"
],
"image": {
"small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png",
"medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png",
"large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png"
},
"details": {
"network_type": "mastercard",
"fee": "0.00",
"fee_currency": "USD",
"max_count": 10,
"topup_limits": {
"pre_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 2250,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 2250,
"weekly_count_limit": null,
"weekly_transactional_limit": 2250,
"annual_count_limit": null,
"annual_transactional_limit": 15000,
"unit_transactional_limit": 750
},
"post_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 500000,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 500000,
"weekly_count_limit": null,
"weekly_transactional_limit": 500000,
"annual_count_limit": null,
"annual_transactional_limit": null,
"unit_transactional_limit": 500000
}
},
"deduct_limits": {
"pre_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 2250,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 2250,
"weekly_count_limit": null,
"weekly_transactional_limit": 2250,
"annual_count_limit": null,
"annual_transactional_limit": 15000,
"unit_transactional_limit": 750
},
"post_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 500000,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 500000,
"weekly_count_limit": null,
"weekly_transactional_limit": 500000,
"annual_count_limit": null,
"annual_transactional_limit": null,
"unit_transactional_limit": 500000
}
}
}
},
{
"code": "sgmmdemomcppcard",
"name": "MatchMove Personalized Physical Card",
"description": "MatchMove Personalized Physical Card",
"form_factor": "physical",
"personalised_order": true,
"token": {
"type": "CVV",
"generation": "static"
},
"currency": [
"USD"
],
"image": {
"small": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-small.png",
"medium": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-medium.png",
"large": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-large.png"
},
"details": {
"network_type": "mastercard",
"fee": "0.00",
"fee_currency": "USD",
"max_count": 10,
"topup_limits": {
"pre_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 2250,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 2250,
"weekly_count_limit": null,
"weekly_transactional_limit": 2250,
"annual_count_limit": null,
"annual_transactional_limit": 15000,
"unit_transactional_limit": 750
},
"post_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 500000,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 500000,
"weekly_count_limit": null,
"weekly_transactional_limit": 500000,
"annual_count_limit": null,
"annual_transactional_limit": null,
"unit_transactional_limit": 500000
}
},
"deduct_limits": {
"pre_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 2250,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 2250,
"weekly_count_limit": null,
"weekly_transactional_limit": 2250,
"annual_count_limit": null,
"annual_transactional_limit": 15000,
"unit_transactional_limit": 750
},
"post_kyc": {
"allowed": 0,
"daily_count_limit": null,
"daily_transactional_limit": 500000,
"lifetime_count_limit": null,
"lifetime_transactional_limit": null,
"monthly_count_limit": null,
"monthly_transactional_limit": 500000,
"weekly_count_limit": null,
"weekly_transactional_limit": 500000,
"annual_count_limit": null,
"annual_transactional_limit": null,
"unit_transactional_limit": 500000
}
}
}
}
]
}If you want to offer the choice to the user and also show the card design, you can filter the objects with form_factor value equal to virtual.
Additionally, you can use the image object under a given card type to display the card design to the user when he is choosing the card product.
You are also recommended to check details.issuance_limit to validate if the user can be issued more cards against that card type. Every card product has an issuance limit, which dictates how many cards for a given card type can be issued to a given user in the system. If you try to create cards that breach this limit, the system will throw an issuance limit error.
2
Initiate virtual card creation
Depending on whether it's a user-initiated choice or a choice you are making for your program on behalf of the user, once the card_type_code has been selected.
Call the Create Card (POST /users/wallets/cards/types/{{card_type_code}}) to trigger the virtual card creation.
You may refer to the API reference page to view the list of error codes associated with this endpoint.
Create Card (Virtual) request
CURL
curl --location --request POST 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types/{{card_type_code}}' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Create Card (Virtual) response
JSON
{
"id": "7bea197412c6df14ce4e80b5e6d13353",
"number": "5412320000120012",
"holder": {
"name": "John Smith"
},
"type": {
"type": "sgmmdemomccard",
"name": "MatchMove Virtual Card",
"description": "MatchMove Virtual Card",
"form_factor": "virtual",
"personalised_order": false
},
"token": {
"type": "CVV",
"generation": "static"
},
"date": {
"expiry": "2030-07",
"issued": "2025-07-18",
"closed": null
},
"image": {
"small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png",
"medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png",
"large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png"
},
"status": {
"is_active": true,
"text": "active"
},
"reason": null,
"kit": "000012342122",
}3
Display virtual card details to the end-user (frontend)
Call the Get Card Details (GET /users/wallets/cards/{{card_id}}) API by passing the card_id to retrieve the non-sensitive card details. This will include the cardholder's name, card image, etc., which you can use to construct the card form in your frontend and display it to the user. Go to the Retrieve non-sensitive card information to learn more about non-sensitive card information.
Get Card Details request
CURL
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/7bea197412c6df14ce4e80b5e6d13353' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Get Card Details response
JSON
{
"id": "7bea197412c6df14ce4e80b5e6d13353",
"number": "5412320000120012",
"holder": {
"name": "John Smith"
},
"type": {
"type": "sgmmdemomccard",
"name": "MatchMove Virtual Card",
"description": "MatchMove Virtual Card",
"form_factor": "virtual",
"personalised_order": false
},
"token": {
"type": "CVV",
"generation": "static"
},
"date": {
"expiry": "2030-07",
"issued": "2025-07-18",
"closed": null
},
"image": {
"small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png",
"medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png",
"large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png"
},
"status": {
"is_active": true,
"text": "active"
},
"reason": null,
"kit": "000012342122",
}Call the Retrieve Card Sensitive Details (GET /users/wallets/cards/{{card_id}}/sensitive-data) to reveal the transaction-sensitive card information. Go to the Retrieve sensitive card information to learn more about these protected card data.
When needed, the list of card ID associated with a user and account can be retrieved using the Get Wallet (GET /users/wallets).
Related Links
Was this section helpful?
On this page
- Provision virtual accounts