Request for a personalised physical card
Understand the steps to request a new physical card that is personalized with the cardholder's name. This guide covers the process of initiating a card order for production and delivery to the user.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to implement a feature in your application that will allow users to request a personalized physical card.
- You want to send a card order for a personalized physical card (non-activated) for a specific user.
Prerequisites
- The user must have an
approvedKYC. - The user profile must be in an
activestatus. - The user profile risk assessment status must not be
risk_flagged(v1). This is not applicable in v2. - The user account or wallet must be in an
activestatus.
API Workflow
1
Retrieve available card types
Call the List 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.
List Card Types API request
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••'
List Card Types API response
{
"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 physical.
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 a request for a personalized card order
Call the Create Cards (POST /users/wallets/cards/types/{{card_type_code}}) passing the card type code of the personalized physical card.
For personalized cards, you can specify a name on the card that will be embossed and printed on the physical card. You can do this by passing an optional parameter name_on_card. If the value is not passed, the card will be embossed based on the preferred_name value defined in the user profile.
For personalized physical cards, the auto_activate parameter is not applicable. An activation process must be completed for this card type.
Create Cards (Personalized physical) request
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomcppcard' \
--header 'X-Auth-User-Id: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
Create Cards (Personalized physical) response
{
"id": "d41d8cd98f00b204e9800998ecf8427e",
"number": "5412XXXXXXXX0012",
"holder": {
"name": "John Smith"
},
"type": {
"type": "sgmmdemomcppcard",
"name": "MatchMove Personalized Physical Card",
"description": "MatchMove Personalized Physical Card",
"form_factor": "physical",
"personalised_order": true
},
"token": {
"type": "CVV",
"generation": "static"
},
"date": {
"expiry": "2030-01",
"issued": "2030-01-01",
"closed": null
},
"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"
},
"status": {
"is_active": false,
"text": "pending_activation",
},
"links": [
{
"rel": "cards.activation",
"href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/d41d8cd98f00b204e9800998ecf8427e",
"method": "PUT"
}
],
"activation_code": "145193",
"kit": "000004600855"
}
Create cards response
- The Create Cards request will return the card status as
pending_activationon the initial. - The new linked card will be assigned a unique
card_ididentifier, which is a unique identifier for the card in the MatchMove platform. - You also have the option to save this
card_idin your data store to have a direct identifier to access a specific card. - The response will also return an
activation_codevalue that will be required to activate the card later.
3
Card delivery to the customer
In the live environment, after a successful personalized physical card provisioning, a card order will be generated and shared with the card printer. Then once the personalized physical card has been delivered to the end-user, the card activation process can commence. The delivery process to the end user is generally recommended to be managed by partners. Do reach out to your Implementation Manager to better understand the options available for you.
In the staging environment, the actual printing of personalized physical cards will only be simulated. As such, you will need to pool (listed in batches) all newly provisioned personalized physical cards card id and submit them to the MatchMove Implementation team. This card list will be used to simulate card printing, which will result in a reverse embossing file. When the simulation is completed (signalling that the card has been delivered), the card activation process can commence.
Related Links
On this page
- Request for a personalised physical card