Request for a personalised physical card
Understand the steps to request a new physical card that is personalised 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 personalised physical card.
- You want to send a card order for a personalised physical card (non-activated) for a specific user.
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 --location 'https://{{cards_base_url}}/{{product_code}}/v1/users/wallets/cards/types' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••'Get 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 Card (POST /users/wallets/cards/types/{{card_type_code}}) passing the card type code of the personalised 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 Card (Personalized physical) request
curl --location 'https://{{cards_base_url}}/{{product_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 Card (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}}/{{product_code}}/v1/users/wallets/cards/d41d8cd98f00b204e9800998ecf8427e",
"method": "PUT"
}
],
"activation_code": "145193",
"kit": "000004600855"
}Create card response
- The Create Card 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 personalised 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 personalised physical cards will only be simulated. As such, you will need to pool (listed in batches) all newly provisioned personalised 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