Link & activate a non-personalised physical card
Learn how to assign and activate a non-personalised physical card for a specific user. This guide explains the process of linking a non-personalised physical card to a user's account, making it ready for use.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to link or associate a specific non-personalised physical card (non-activated) from the bulk of printed physical cards.
- You want to activate a linked card that was delivered to a user and enable it for online and offline transaction usage.
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. - For card activation, the physical card must have already been delivered to the end user via applicable channels or modes of distribution.
- The embossing file containing the details of the non-personalized cards (in bulk) that can be linked to the users has already been handed over to the partner. Request this file from your MatchMove Implementation team before you proceed with the non-personalised card provisioning.
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}}/{{program_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
Link a non-personalized card to the user account
Call the Create Card POST /users/wallets/cards/types/{{card_type_code}} passing the correct physical card card_type_code to trigger the linkage process of a non-personalized card to the account.
Depending on your card-issuing journey, you have two modes of providing the card identifier that will be linked to the user account. This card identifier must be passed to the assoc_number parameter for linkage.
Proxy number or card kit number | This is the identifier that is used to generate the kit number of the personalized card. This number will be printed on the back of the physical card. In the staging environment, the proxy number can be located in the embossing file received from the MatchMove Implementation team. | assoc_number = E.g., if the proxy number is 00012342122, the value passed for assoc_number will be PY000012342122 |
Card number or PAN | This is the actual card number of the physical card assigned and delivered to the end user In the staging environment, the PAN will be masked until the card is activated, so this linking method will not be available. In the live environment, the PAN can be located by the end-user printed on the non-personalised physical card. In this scenario, the card delivery has happened before the card creation or linking. You will need to ask the end-user to input this PAN in your frontend to be able to link it to his account. | assoc_number = E.g., if the card number is 5412 3200 0012 0012, the value passed for assoc_number will be 5412320000120012 |
The Create Card has a parameter that allows you to do card linking and activation of a non-personalised card in one go.
To do this, you will need to pass it auto_activate = true as a request parameter.
Create Card (Non-personalized physical) request using proxy number
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomcpcard' \
--header 'X-Auth-User-Id: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'assoc_number=PY000012342122'Create Card (Non-personalized physical) request using card number
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomcpcard' \
--header 'X-Auth-User-Id: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'assoc_number=5412320000120012'Create Card (Non-personalized physical) response
{
"id": "d41d8cd98f00b204e9800998ecf8427e",
"number": "5412XXXXXXXX0012",
"holder": {
"name": "John Doe"
},
"type": {
"type": "sgmmdemomcpcard",
"name": "MatchMove Physical Card",
"description": "MatchMove Physical Card",
"form_factor": "physical",
"personalised_order": false
},
"token": {
"type": "CVV",
"generation": "static"
},
"date": {
"expiry": "2030-01",
"issued": "2030-01-01",
"closed": null
},
"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"
},
"status": {
"is_active": false,
"text": "pending_activation",
},
"activation_code": "123456",
"kit": "000012342122"
}Create card response
The Create Card request will return the card status as pending_activation on the initial.
The new linked card will be assigned a unique card_id identifier, which is a unique identifier for the card in the MatchMove platform.
You also have the option to save this card_id in your data store to have a direct identifier to access a specific card.
The response will also return a activation_code value that will be required to activate the card later, if you did not pass auto_activate = true
3
Activate a non-personalized physical card
Using the activation_code returned from the card linking stage and the card_id generated by the system, you can proceed to activate the physical card.
Call Activate Card PUT /users/wallets/cards/{{card_id}} to start activating the non-personalised physical card.
Activate Card (Non-personalized physical) request
curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}' \
--header 'X-Auth-User-Id: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'activation_code={{activation_code}}'Activate Card (Non-personalized physical) response
{
"status": "success"
}[Optional] Additional security and authentication measures that you can add before card activation:
- Verify the activation code — the activation_code can be sent to the customer in the form of an email/SMS/push as an OTP. When the customer has returned the code, you can verify if it's similar to the one in the records.
- Verify the last 4 digits of the card number — Until the card is in an active state, the card number on file will be masked and only reveal the last 4 digits. You can ask for the last 4 digits of the PAN from the user and verify it against the one in the records.
- Verify the proxy number or the card kit number — Additionally, you can also ask to validate the card kit number printed on the back of the non-personalised physical card of the customer.
4
Display non-personalised physical card details to the end-user (front end)
Even though the card is of a physical product, you can still display its card details in a digital format.
Call the Get Card Details (GET /users/wallets/cards/{{card_id}}) 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 --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
{
"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
On this page
- Link & activate a non-personalised physical card