Set card PIN

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"
} {
  "status": "success"
}