The PaymentLink whitelist file can be used to configure encryption key settings and define specific encryption policies for designated card number ranges during transactions. By loading the whitelist, organizations can achieve centralized and consistent management of encryption policies.
The PaymentLink whitelist data mainly consists of the following three components:
Encryption Key Configuration
Defines the encryption key configurations that may be used within the application, including key IDs, encryption methods, and algorithm parameters.
Card Number Range Configuration
Specifies custom encryption settings for specific card number ranges (e.g., BIN ranges), enabling granular security control.
Payment AID Supplement Configuration
Allows the addition of new Application Identifiers (AIDs) to be included in transaction management, supporting newly introduced payment applications or protocols.
Encryption Key Configuration, Card Number Range Configuration and Payment AID Supplement Configuration, the relationship of the three main categories is shown in the diagram below.
The Card Number Range Configuration table will be associated with the Encryption Key Configuration table to specify corresponding encryption policies for specific PAN ranges.
Meanwhile, the Payment AID Supplement Configuration table exists independently and is used to manage newly added or specially controlled Application Identifiers (AIDs).
Both the Card Number Range Configuration table and the Payment AID Supplement Configuration table are optional. They only need to be configured when required by business scenarios. The system can operate normally without these configurations if no special requirements exist.
| Tag | Description | Option Value | Presence |
|---|---|---|---|
| EncryptID | Encryption method ID, serves as a unique identifier | M | |
| KeySystem | Encryption system used | MK/SK DUKPT | M |
| KeyIndex | Key ID in the key table | M | |
| Algorithms | Encryption algorithms used | DES AES | M |
| BlockMode | Block cipher mode used during encryption | ECB CBC ECB_RESP ECB_BOTH CBC_RESP CBC_BOTH | M |
| IV | Initialization vector, required when using CBC encryption mode | O | |
| Padding | Padding mode, mainly used in CBC mode. Default is NONE | NONE PKCS7 ONE_AND_ZEROS ZEROS_AND_LEN ZEROS | O |
| DerivateType | AES DUKPT derived key type | DES AES | O |
| DerivateKeyLen | AES DUKPT derived key length | O | |
| DerivateKeyUsage | AES DUKPT derived key usage | DATA_ENC DATA_BOTH | O |
| IsDefault | Whether this is the default key. Defaults to false if not configured. Only one default configuration allowed in the entire setup | true false | O |
| FirstClearPAN | Length of the first few digits of the PAN shown in plain text after masking | O | |
| LastClearPAN | Length of the last few digits of the PAN shown in plain text after masking | O |
MK/SK - DES
<entry name="Encryption">
<item key="EncryptID" value="1">
<item key="KeySystem" value="MK/SK">
<item key="KeyIndex" value="1">
<item key="Algorithms" value="DES">
<item key="BlockMode" value="ECB">
<item key="Padding" value="ZEROS">
<item key="IsDefault" value="true">
</entry>MK/SK - AES
<entry name="Encryption">
<item key="EncryptID" value="2">
<item key="KeySystem" value="MK/SK">
<item key="KeyIndex" value="1">
<item key="Algorithms" value="AES">
<item key="BlockMode" value="CBC">
<item key="Padding" value="ZEROS">
<item key="IV" value="000000000000">
<item key="IsDefault" value="false">
</entry>DUKPT - DES
<entry name="Encryption">
<item key="EncryptID" value="3">
<item key="KeySystem" value="DUKPT">
<item key="KeyIndex" value="1">
<item key="Algorithms" value="DES">
<item key="BlockMode" value="ECB">
<item key="Padding" value="ZEROS">
</entry>DUKPT - AES
<entry name="Encryption">
<item key="EncryptID" value="3">
<item key="KeySystem" value="DUKPT">
<item key="KeyIndex" value="1">
<item key="Algorithms" value="DES">
<item key="BlockMode" value="CBC">
<item key="Padding" value="ZEROS">
<item key="IV" value="000000000000">
<item key="DerivateType" value="AES">
<item key="DerivateKeyLen" value="16">
</entry>| Tag | Description | Option Value | Presence |
|---|---|---|---|
| PanLen | Length of the card number (PAN) | M | |
| MinPan | Minimum PAN value | M | |
| MaxPan | Maximum PAN value | M | |
| EncryptID | Specifies the corresponding encryption method ID, matching the identifier in the Encryption table | NO-Encrypted: For Pan Range which does not need to Encrypt. EncryptID in Encryption Key Configuration table | M |
| KeyIndex | Specifies the key ID to be used under the selected encryption method | O | |
| FirstClearPAN | Length of the first few digits of the PAN shown in plain text after masking | O | |
| LastClearPAN | Length of the last few digits of the PAN shown in plain text after masking | O |
<entry name="Card Range">
<config name="A card">
<item key="PanLen" value="15" />
<item key="MinPan" value="370200000000000" />
<item key="MaxPan" value="370299999999999" />
<item key="EncryptID" value="NO-Encrypted" />
</config>
<config name="B card">
<item key="PanLen" value="16" />
<item key="MinPan" value="4518000000000000" />
<item key="MaxPan" value="4518999999999999" />
<item key="EncryptID" value="1" />
<item key="KeyIndex" value="5" />
<item key="FirstClearPAN" value="7" />
<item key="LastClearPAN" value="4" />
</config>
<config name="C card">
<item key="PanLen" value="16" />
<item key="MinPan" value="6214000000000000" />
<item key="MaxPan" value="6214999999999999" />
<item key="EncryptID" value="3" />
<item key="FirstClearPAN" value="6" />
<item key="LastClearPAN" value="5" />
</config>
<config name="D card">
<item key="PanLen" value="16" />
<item key="MinPan" value="6250000000000000" />
<item key="MaxPan" value="6250999999999999" />
<item key="EncryptID" value="4" />
</config>
</entry>| Tag | Description | Option Value | Presence |
|---|---|---|---|
| AID | Additional AID used for transaction filtering | M |
<entry name="Payment AID">
<item key="AID" value="A00000033301020304" />
</entry><?xml version="1.0" encoding="UTF-8"?>
<whitelist>
<entry name="Encryption">
<item key="EncryptID" value="1" />
<item key="KeySystem" value="MK/SK" />
<item key="KeyIndex" value="3" />
<item key="Algorithms" value="DES" />
<item key="BlockMode" value="ECB" />
<item key="Padding" value="NONE" />
<item key="IsDefault" value="true" />
</entry>
<entry name="Encryption">
<item key="EncryptID" value="2" />
<item key="KeySystem" value="MK/SK" />
<item key="KeyIndex" value="3" />
<item key="Algorithms" value="AES" />
<item key="BlockMode" value="CBC" />
<item key="Padding" value="ZEROS" />
<item key="IV" value="00000000000000000000000000000000" />
</entry>
<entry name="Encryption">
<item key="EncryptID" value="3" />
<item key="KeySystem" value="DUKPT" />
<item key="KeyIndex" value="1" />
<item key="Algorithms" value="DES" />
<item key="BlockMode" value="ECB_BOTH" />
<item key="Padding" value="NONE" />
<item key="FirstClearPAN" value="6" />
<item key="LastClearPAN" value="3" />
</entry>
<entry name="Encryption">
<item key="EncryptID" value="4" />
<item key="KeySystem" value="DUKPT" />
<item key="KeyIndex" value="2" />
<item key="Algorithms" value="AES" />
<item key="BlockMode" value="CBC" />
<item key="Padding" value="ZEROS" />
<item key="IV" value="00000000000000000000000000000000" />
<item key="DerivateType" value="AES" />
<item key="DerivateKeyLen" value="16" />
<item key="DerivateKeyUsage" value="DATA_BOTH" />
</entry>
<entry name="Card Range">
<config name="A card">
<item key="PanLen" value="15" />
<item key="MinPan" value="370200000000000" />
<item key="MaxPan" value="370299999999999" />
<item key="EncryptID" value="NO-Encrypted" />
</config>
<config name="B card">
<item key="PanLen" value="16" />
<item key="MinPan" value="4518000000000000" />
<item key="MaxPan" value="4518999999999999" />
<item key="EncryptID" value="1" />
<item key="KeyIndex" value="5" />
<item key="FirstClearPAN" value="7" />
<item key="LastClearPAN" value="4" />
</config>
<config name="C card">
<item key="PanLen" value="16" />
<item key="MinPan" value="6214000000000000" />
<item key="MaxPan" value="6214999999999999" />
<item key="EncryptID" value="3" />
<item key="FirstClearPAN" value="6" />
<item key="LastClearPAN" value="5" />
</config>
<config name="D card">
<item key="PanLen" value="16" />
<item key="MinPan" value="6250000000000000" />
<item key="MaxPan" value="6250999999999999" />
<item key="EncryptID" value="4" />
</config>
</entry>
<entry name="Payment AID">
<item key="AID" value="A00000033301020304" />
</entry>
</whitelist>