Set card PIN
Understand the process for setting or changing the PIN for a physical card. As this feature is only available for physical cards, this guide covers the secure steps a user must take to manage their PIN.
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 set their card PIN for ATM and offline transactions.
- You want to implement a feature in your application that will allow users to reset a compromised or forgotten card PIN.
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. - The user card must be in an
activestatus.
API Workflow
1
Ask the user to employ a PIN
In your Set PIN page, you can ask the user to employ a PIN. Please note that the system currently only supports a 4-digit PIN.
2
Prepare to generate a PIN block
A PIN block is a secure, encrypted data structure used in electronic financial transactions (like those at an ATM or a point-of-sale terminal) to protect a cardholder's Personal Identification Number (PIN) before transmitting it.
The PIN block must be encrypted using a ZPK or Zone PIN Key (also known as a PIN Protection Key or PPK), a cryptographic key used in the financial services industry to secure cardholders' PINs during electronic financial transactions.
The ZPK is part of the program resources that will be provided to the partner.
3
Pad the PIN entered by the user
Before we generate the PIN block, a padded PIN needs to be generated using a concatenation formula.
Padded PIN formula: ‘0’ + {{PIN LENGTH}} + {{USER PIN}}
The string needs to be padded with F at the end to complete a 16-digit string.
Example:
If the user enters PIN: 1234, the constructed string becomes :
‘0’ + ‘4’ + ‘1234’ + ‘FFFFFFFFFF’
Final padded PIN value: 041234FFFFFFFFFF (16-digit string)
4
Pad the user's registered mobile number
To add another layer of a secure element associated with the user, we will need to use a padded mobile number.
Padded mobile formula: '0 padding prefix to complete a 16-digit string' + {{mobile.mobile_country_code}} + {mobile.number}}
Example:
If the user is based out of Singapore with a registered mobile number of +65 8888 9999 (mobile.mobile_country_code = 65 and mobile.number = 88889999). The (+) sign is excluded in the formula. Which gets us a 10-digit string (65 + 88889999).
Following the padding formula, we will add six ‘0’ as a prefix to the 10-digit mobile number to complete a 16-digit string. ‘000000’ + ‘65’ + ‘88889999’
Final padded mobile value: 0000006580800000 (16-digit string)
5
Perform Triple-DES encryption
Perform an XOR of the padded PIN value and the padded mobile value. Then, encrypt the output using the provided ZPK to get the PIN block.
6
Pass the encrypted PIN block
Call the Set Card PIN (POST /users/wallets/cards/{(card_id})/pins) passing the encrypted pinblock to set the PIN.
Set Card PIN request
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/180ac588b91dc6bff6a5d42a671d1d6a/pins' \
--header 'X-Auth-User-Id: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'pinblock=2F08670F5615DE76'Set Card PIN response
{
"status": "success"
}Related Links
On this page
- Set card PIN