Content
Introduction
This function allow merchants to use a double layer encryption :
- The whole traffic is encrypted through the SSL tunnel ;
- The card object is encrypted inside the message.
Please contact our sales team to access this feature.
Encryption step
The processing takes place in 3 steps:
- The merchant requests parameters to generate the encryption key.
- The merchant encrypts the sensitive data on his server.
- The merchant calls the Payline web services with the encrypted data.
How to integrate
To start this step, you must have a merchant and a merchant access key.
You must integrate Payline web services and know RSA data encryption :
- getEncryptionKey : allows you to retrieve the encryption settings to encrypt your message.
Step 1 : Call the getEncryptionKey
to obtain the key.
Merchant calls the getEncryptionKey service on the usual endpoint.
This service can be called multiple times if needed (for instance multiple place to store the public key). The only parameter is the version to use. It must be set to 21.
You must integrate the Payline web services:
- The merchant performs a getEncryptionKey : retrieves the encryption parameters.
- The merchant retrieves the encryption parameters and the key.keyId from getEncryptionKey.
These data must be stored by the merchant in order to encrypt further messages.
Step 2 : Encrypt the card data with the public key
Having data from step 1, merchant can instantiate a key using details provided by the getEncryptionKey service.
The merchant can then encrypt the message with the sensitive data.
The encryption function must :
- generate a public key with the parameters retrieved from the getEncryptionKeyReply: algo, modulus, exponent ;
- build the public key with the parameters: modulus and publicExponent ;
- build the Cipher is returned by the getEncryptionKeyReponse service ;
- encrypt the message with the following parameters: the message formatted with the sensitive data, the Cipher and the PublicKey.
cardDataToEncrypt = "CardNumber=497010000000006,ExpDate=0220,CVX=123,OwnerBirthDate=07071977,Password=Payline,Cardholder=John Doe"
- encode the message in base64.
If any data is not available, then it shall be absent in the string. For instance, if only the card and the expiration date are available:
cardDataToEncrypt = "CardNumber=497010000000006,ExpDate=0220"
Then merchant can encrypt the cardDataToEncrypt using the publicKey. Before sending this data in any payment or authentication service, it has to be converted in base 64.
encryptedData = BASE64.encodeBase64(RSA.encrypt(publicKey,cardDataToEncrypt))
Step 3 : Calls the Payline web services with the encrypted data.
Merchant can send encryptedData
in web services message instead of clear data.
One very important element is the key ID : Monext will uncrypt data with the private key associated to this key ID.
Check the getEncryptionKey wbs to list the wbs using the encrypted message.
Here is an exemple of the card
object in messages :
Clear card data
Encrypted card data
Code example
Encryption function code example
List of Key/Value accepted
The following keys are accepted in the encrypted data:
CardNumber | card.number | 497010000000006 |
ExpDate | card.expirationDate | 0220 |
CVX | card.cvx | 123 |
OwnerBirthDate | card.ownerBirthdayDate | 31121980 |
Password | card.password | Payline01$ |
Cardholder | card.cardholder | Jeremy Mattio |
Key renewal
A key is valid for 90 days. A new key will be issued 30 days before the previous key expiration. During this period both keys are valid and usable.
A merchant has 30 days to change the key in its systems before the old key become unusable.
A good practice is to call the getEncryptionKey
everyday, and to start the renew process as soon as a new key ID is received by the merchant
Security
The key is unique per merchant.
The current key specification are :
- Algorithm : RSA
- Key size : 2048
- Cipher : RSA/ECB/OAEPWithSHA-256AndMGF1Padding