Card Data encryption

Key derivation algorithm

Encryption algorithm

Note: The initialization vector (IV) for the encryption is always a null vector (0, …, 0).

Example

In this example we encrypt the card data of a transaction using "MASTERSESSION" and "AES128CBC".

Data encryption key used:

The card data is encrypted in field "paymentMethod/paymentCardProtected".
The encrypted data contains the value which would be written to "paymentMethod/paymentCard", if no encryption would be done

Here is the value of "paymentMethod/paymentCard"

{ 
  "number" : "4761739001010036", 
  "expiryDate" : { 
    "month" : "12", 
    "year" : "32" 
  }, 
  "track2" : "4761739001010036=32122011184491489" 
}

As binary and already with padding (appending 0x80 and filling it with 0x00 until its total size is a multiple of the blocksize (16)), it looks like:

0000: 7B 0D 0A 20 20 22 6E 75 | 6D 62 65 72 22 20 3A 20 {..  "number" :  
0010: 22 34 37 36 31 37 33 39 | 30 30 31 30 31 30 30 33 "476173900101003 
0020: 36 22 2C 0D 0A 20 20 22 | 65 78 70 69 72 79 44 61 6",..  "expiryDa 
0030: 74 65 22 20 3A 20 7B 0D | 0A 20 20 20 20 22 6D 6F te" : {..    "mo 
0040: 6E 74 68 22 20 3A 20 22 | 31 32 22 2C 0D 0A 20 20 nth" : "12",..   
0050: 20 20 22 79 65 61 72 22 | 20 3A 20 22 33 32 22 0D   "year" : "32". 
0060: 0A 20 20 7D 2C 0D 0A 20 | 20 22 74 72 61 63 6B 32 .  },..  "track2 
0070: 22 20 3A 20 22 34 37 36 | 31 37 33 39 30 30 31 30 " : "47617390010 
0080: 31 30 30 33 36 3D 33 32 | 31 32 32 30 31 31 31 38 10036=3212201118 
0090: 34 34 39 31 34 38 39 22 | 0D 0A 7D 80 00 00 00 00 4491489"..}..... 

Encrypted with our DEC key (AES128 CBC):

0000: B9 4A 72 23 80 14 3F 18 | 3E FA 42 60 EF A0 AE 2D .Jr#..?.>.B`...- 
0010: 64 39 86 F3 91 7E 99 54 | 92 86 3C 85 1F C7 44 D6 d9.....T..<...D. 
0020: C3 72 D1 08 9E 20 40 3D | 82 AE C0 B1 9A 9C 26 47 .r... @=......&G 
0030: C1 71 7C CC 3D 1E 9E B7 | 48 F0 5F 98 B2 29 53 A4 .q|.=...H._..)S. 
0040: DE FB 46 AD 45 53 3C 89 | 23 27 EC 3A 92 D2 C3 7C ..F.ES<.#'.:...| 
0050: 77 75 DE 84 64 FC AB 16 | 4B 6E 4F F6 58 64 6F 33 wu..d...KnO.Xdo3 
0060: DD 1C E0 36 CC CD 65 55 | 79 45 13 E0 44 5A 68 52 ...6..eUyE..DZhR 
0070: B5 1E AB CD A7 4B E5 1A | 99 46 BA B6 30 90 27 99 .....K...F..0.'. 
0080: 19 2C C9 CF 4F 42 6A 20 | 5E 94 79 25 05 34 E8 32 .,..OBj ^.y%.4.2 
0090: 4B B1 3F DB 38 BC BC 26 | B0 00 47 DF 09 82 76 F8 K.?.8..&..G...v.

Base64 encoded:

uUpyI4AUPxg++kJg76CuLWQ5hvORfplUkoY8hR/HRNbDctEIniBAPYKuwLGanCZHwXF8zD0enrdI8F+YsilTpN77Rq1FUzyJIyfsOpLSw3x3dd6EZPyrFktuT/ZYZG8z3RzgNszNZVV5RRPgRFpoUrUeq82nS+UamUa6tjCQJ5kZLMnPT0JqIF6UeSUFNOgyS7E/2zi8vCawAEffCYJ2+A==

The resulting "paymentMethod/paymentCardProtected" is then:

"paymentMethod": { 
	"paymentCardProtected": { 
		"key": { 
			"name": "MsTestKey", 
			"index": "171718", 
			"encryptionAlgo": "AES128CBC", 
			"version": "20260714", 
			"derivationAlgo": "MASTERSESSION" 
		}, 
		"encryptedData": "uUpyI4AUPxg++kJg76CuLWQ5hvORfplUkoY8hR/HRNbDctEIniBAPYKuwLGanCZHwXF8zD0enrdI8F+YsilTpN77Rq1FUzyJIyfsOpLSw3x3dd6EZPyrFktuT/ZYZG8z3RzgNszNZVV5RRPgRFpoUrUeq82nS+UamUa6tjCQJ5kZLMnPT0JqIF6UeSUFNOgyS7E/2zi8vCawAEffCYJ2+A==" 
	} 	
}

PIN-block encryption

Key derivation algorithm

Encryption algorithm

MAC calculation

Key derivation algorithm

Mac algorithm

Note: In the payments REST API we use a MAC length of 8 bytes (16 hex digits).

MAC calculation

The MAC is calculated over the complete body of the HTTP message (not over the headers).
The body should consists of the JSON message encoded as UTF-8.

When sending the request to IPG, the MAC is added in the following format as header value to the HTTP message:

"message-authentication-value: " base-64(MAC) ";" derivation-algo ";" mac-algo ";" ksn ";" key-name ";" key-version

Details:

• base-64(MAC)
  The calculated MAC (8 bytes) encoded as base64 string.
• derivation-algo
  "DUKPT2009", "AESDUKPT128ECB" or "MASTERSESSION"
• mac-algo
  "RetailSHA256MAC", "SHA256CMACwithAES128" or "CMACwithAES128"
• ksn
  For DUKPT, this is the "derivation rule" to get the key from the BDK.
  For MASTERSESSION, it is the key index assigned to the key (it is used by IPG to find the right key).
• key-name
  Currently only for information purpose. This is the name of the key. In future, it may be used to find the key.
• key-version
  Currently only for information purpose. This is the name of the key. In future, it may be used to find the key.

Mastersession MAC calculation

In this example we calculate the MAC using "MASTERSESSION" and "CMACwithAES128".

Message to send (with indentation and new lines):

{ 
"requestType": "PaymentTerminalSaleTransaction", 
"storeId": "64200001", 
"terminalId": "54200001", 
"transactionOrigin": "RETAIL", 
"merchantTransactionId": "MTI-R-260723113032548", 
"paymentMethod": { 
	"paymentCardProtected": { 
		"encryptedData": 		"uUpyI4AUPxg++kJg76CuLWQ5hvORfplUkoY8hR/HRNbDctEIniBAPYKuwLGanCZHwXF8zD0enrdI8F+YsilTpN77Rq1FUzyJIyfsOpLSw3x3dd6EZPyrFktuT/ZYZG8z3RzgNszNZVV5RRPgRFpoUrUeq82nS+UamUa6tjCQJ5kZLMnPT0JqIF6UeSUFNOgyS7E/2zi8vCawAEffCYJ2+A==", 
		"key": { 
			"derivationAlgo": "MASTERSESSION", 
			"version": "20260714", 
			"encryptionAlgo": "AES128CBC", 
			"index": "171718", 
			"name": "MsTestKey" 
		} 
	} 
}, 
"transactionAmount": { 
	"total": "1", 
	"currency": "EUR" 
}, 
"order": { 
	"orderId": "R-260723113032548" 
}, 
"terminalRequestData": { 
	"offlineIndicator": false, 
	"posEntryMode": "CONTACT_EMV", 
	"emvData": "ggJ8AJUFAIAAgACcAQCfAgYAAAAAGACfJgiopLKhUxCKS58nAYCfMwPg+MifNAMEAwKfNgIAqp83BJkCd22fBgegAAAAAxAQ", 
	"cardholderPresentIndicator": true, 
	"cardPresentIndicator": true, 
	"singleTapPinPerformed": false, 
	"attendanceContext": "ATTENDED", 
	"onlineReason": "TERMINAL_FORCED" 
}, 
"pointOfSaleDevice": { 
	"serialNumber": "3223900008", 
	"capabilities": { 
		"cardholderVerificationCapabilities": [ 
			"OFFLINE_PIN", 
			"ONLINE_PIN", 
			"NO_VERIFICATION" 
], 
		"cardReadingCapabilities": [ 
			"CONTACTLESS_EMV", 
			"CONTACT_EMV", 
			"MAGNETIC_STRIPE", 
			"MAGNETIC_STRIPE_FALLBACK", 
			"MAGNETIC_STRIPE_INCOMPLETE", 
			"CONTACTLESS_MAGSTRIPE" 
], 
		"terminalType": "MPOS", 
		"pinCapability": "HARDWARE", 
		"features": [ 
			"SINGLE_TAP_PIN_SUPPORT" 
] 
}, 
	"terminalProvider": "TestProvider", 
	"softwareProvider": "TestSwProvider", 
	"softwareVersion": "1.0.0.0", 
	"model": "restapiTest" 
	} 
}

The hex dump of the message:

0000: 7B 22 72 65 71 75 65 73 | 74 54 79 70 65 22 3A 22 {"requestType":" 
0010: 50 61 79 6D 65 6E 74 54 | 65 72 6D 69 6E 61 6C 53 PaymentTerminalS 
0020: 61 6C 65 54 72 61 6E 73 | 61 63 74 69 6F 6E 22 2C aleTransaction", 
0030: 22 73 74 6F 72 65 49 64 | 22 3A 22 36 34 32 30 30 "storeId":"64200 
0040: 30 30 31 22 2C 22 74 65 | 72 6D 69 6E 61 6C 49 64 001","terminalId 
0050: 22 3A 22 35 34 32 30 30 | 30 30 31 22 2C 22 74 72 ":"54200001","tr 
0060: 61 6E 73 61 63 74 69 6F | 6E 4F 72 69 67 69 6E 22 ansactionOrigin" 
0070: 3A 22 52 45 54 41 49 4C | 22 2C 22 6D 65 72 63 68 :"RETAIL","merch 
0080: 61 6E 74 54 72 61 6E 73 | 61 63 74 69 6F 6E 49 64 antTransactionId 
0090: 22 3A 22 4D 54 49 2D 52 | 2D 32 36 30 37 32 33 31 ":"MTI-R-2607231 
00a0: 31 33 30 33 32 35 34 38 | 22 2C 22 70 61 79 6D 65 13032548","payme 
00b0: 6E 74 4D 65 74 68 6F 64 | 22 3A 7B 22 70 61 79 6D ntMethod":{"paym 
00c0: 65 6E 74 43 61 72 64 50 | 72 6F 74 65 63 74 65 64 entCardProtected 
00d0: 22 3A 7B 22 65 6E 63 72 | 79 70 74 65 64 44 61 74 ":{"encryptedDat 
00e0: 61 22 3A 22 75 55 70 79 | 49 34 41 55 50 78 67 2B a":"uUpyI4AUPxg+ 
00f0: 2B 6B 4A 67 37 36 43 75 | 4C 57 51 35 68 76 4F 52 +kJg76CuLWQ5hvOR 
0100: 66 70 6C 55 6B 6F 59 38 | 68 52 2F 48 52 4E 62 44 fplUkoY8hR/HRNbD 
0110: 63 74 45 49 6E 69 42 41 | 50 59 4B 75 77 4C 47 61 ctEIniBAPYKuwLGa 
0120: 6E 43 5A 48 77 58 46 38 | 7A 44 30 65 6E 72 64 49 nCZHwXF8zD0enrdI 
0130: 38 46 2B 59 73 69 6C 54 | 70 4E 37 37 52 71 31 46 8F+YsilTpN77Rq1F 
0140: 55 7A 79 4A 49 79 66 73 | 4F 70 4C 53 77 33 78 33 UzyJIyfsOpLSw3x3 
0150: 64 64 36 45 5A 50 79 72 | 46 6B 74 75 54 2F 5A 59 dd6EZPyrFktuT/ZY 
0160: 5A 47 38 7A 33 52 7A 67 | 4E 73 7A 4E 5A 56 56 35 ZG8z3RzgNszNZVV5 
0170: 52 52 50 67 52 46 70 6F | 55 72 55 65 71 38 32 6E RRPgRFpoUrUeq82n 
0180: 53 2B 55 61 6D 55 61 36 | 74 6A 43 51 4A 35 6B 5A S+UamUa6tjCQJ5kZ 
0190: 4C 4D 6E 50 54 30 4A 71 | 49 46 36 55 65 53 55 46 LMnPT0JqIF6UeSUF 
01a0: 4E 4F 67 79 53 37 45 2F | 32 7A 69 38 76 43 61 77 NOgyS7E/2zi8vCaw 
01b0: 41 45 66 66 43 59 4A 32 | 2B 41 3D 3D 22 2C 22 6B AEffCYJ2+A==","k 
01c0: 65 79 22 3A 7B 22 64 65 | 72 69 76 61 74 69 6F 6E ey":{"derivation 
01d0: 41 6C 67 6F 22 3A 22 4D | 41 53 54 45 52 53 45 53 Algo":"MASTERSES 
01e0: 53 49 4F 4E 22 2C 22 76 | 65 72 73 69 6F 6E 22 3A SION","version": 
01f0: 22 32 30 32 36 30 37 31 | 34 22 2C 22 65 6E 63 72 "20260714","encr 
0200: 79 70 74 69 6F 6E 41 6C | 67 6F 22 3A 22 41 45 53 yptionAlgo":"AES 
0210: 31 32 38 43 42 43 22 2C | 22 69 6E 64 65 78 22 3A 128CBC","index": 
0220: 22 31 37 31 37 31 38 22 | 2C 22 6E 61 6D 65 22 3A "171718","name": 
0230: 22 4D 73 54 65 73 74 4B | 65 79 22 7D 7D 7D 2C 22 "MsTestKey"}}}," 
0240: 74 72 61 6E 73 61 63 74 | 69 6F 6E 41 6D 6F 75 6E transactionAmoun 
0250: 74 22 3A 7B 22 74 6F 74 | 61 6C 22 3A 22 31 22 2C t":{"total":"1", 
0260: 22 63 75 72 72 65 6E 63 | 79 22 3A 22 45 55 52 22 "currency":"EUR" 
0270: 7D 2C 22 6F 72 64 65 72 | 22 3A 7B 22 6F 72 64 65 },"order":{"orde 
0280: 72 49 64 22 3A 22 52 2D | 32 36 30 37 32 33 31 31 rId":"R-26072311 
0290: 33 30 33 32 35 34 38 22 | 7D 2C 22 74 65 72 6D 69 3032548"},"termi 
02a0: 6E 61 6C 52 65 71 75 65 | 73 74 44 61 74 61 22 3A nalRequestData": 
02b0: 7B 22 6F 66 66 6C 69 6E | 65 49 6E 64 69 63 61 74 {"offlineIndicat 
02c0: 6F 72 22 3A 66 61 6C 73 | 65 2C 22 70 6F 73 45 6E or":false,"posEn 
02d0: 74 72 79 4D 6F 64 65 22 | 3A 22 43 4F 4E 54 41 43 tryMode":"CONTAC 
02e0: 54 5F 45 4D 56 22 2C 22 | 65 6D 76 44 61 74 61 22 T_EMV","emvData" 
02f0: 3A 22 67 67 4A 38 41 4A | 55 46 41 49 41 41 67 41 :"ggJ8AJUFAIAAgA 
0300: 43 63 41 51 43 66 41 67 | 59 41 41 41 41 41 47 41 CcAQCfAgYAAAAAGA 
0310: 43 66 4A 67 69 6F 70 4C | 4B 68 55 78 43 4B 53 35 CfJgiopLKhUxCKS5 
0320: 38 6E 41 59 43 66 4D 77 | 50 67 2B 4D 69 66 4E 41 8nAYCfMwPg+MifNA 
0330: 4D 45 41 77 4B 66 4E 67 | 49 41 71 70 38 33 42 4A MEAwKfNgIAqp83BJ 
0340: 6B 43 64 32 32 66 42 67 | 65 67 41 41 41 41 41 78 kCd22fBgegAAAAAx 
0350: 41 51 22 2C 22 63 61 72 | 64 68 6F 6C 64 65 72 50 AQ","cardholderP 
0360: 72 65 73 65 6E 74 49 6E | 64 69 63 61 74 6F 72 22 resentIndicator" 
0370: 3A 74 72 75 65 2C 22 63 | 61 72 64 50 72 65 73 65 :true,"cardPrese 
0380: 6E 74 49 6E 64 69 63 61 | 74 6F 72 22 3A 74 72 75 ntIndicator":tru 
0390: 65 2C 22 73 69 6E 67 6C | 65 54 61 70 50 69 6E 50 e,"singleTapPinP 
03a0: 65 72 66 6F 72 6D 65 64 | 22 3A 66 61 6C 73 65 2C erformed":false, 
03b0: 22 61 74 74 65 6E 64 61 | 6E 63 65 43 6F 6E 74 65 "attendanceConte 
03c0: 78 74 22 3A 22 41 54 54 | 45 4E 44 45 44 22 2C 22 xt":"ATTENDED"," 
03d0: 6F 6E 6C 69 6E 65 52 65 | 61 73 6F 6E 22 3A 22 54 onlineReason":"T 
03e0: 45 52 4D 49 4E 41 4C 5F | 46 4F 52 43 45 44 22 7D ERMINAL_FORCED"} 
03f0: 2C 22 70 6F 69 6E 74 4F | 66 53 61 6C 65 44 65 76 ,"pointOfSaleDev 
0400: 69 63 65 22 3A 7B 22 73 | 65 72 69 61 6C 4E 75 6D ice":{"serialNum 
0410: 62 65 72 22 3A 22 33 32 | 32 33 39 30 30 30 30 38 ber":"3223900008 
0420: 22 2C 22 63 61 70 61 62 | 69 6C 69 74 69 65 73 22 ","capabilities" 
0430: 3A 7B 22 63 61 72 64 68 | 6F 6C 64 65 72 56 65 72 :{"cardholderVer 
0440: 69 66 69 63 61 74 69 6F | 6E 43 61 70 61 62 69 6C ificationCapabil 
0450: 69 74 69 65 73 22 3A 5B | 22 4F 46 46 4C 49 4E 45 ities":["OFFLINE 
0460: 5F 50 49 4E 22 2C 22 4F | 4E 4C 49 4E 45 5F 50 49 _PIN","ONLINE_PI 
0470: 4E 22 2C 22 4E 4F 5F 56 | 45 52 49 46 49 43 41 54 N","NO_VERIFICAT 
0480: 49 4F 4E 22 5D 2C 22 63 | 61 72 64 52 65 61 64 69 ION"],"cardReadi 
0490: 6E 67 43 61 70 61 62 69 | 6C 69 74 69 65 73 22 3A ngCapabilities": 
04a0: 5B 22 43 4F 4E 54 41 43 | 54 4C 45 53 53 5F 45 4D ["CONTACTLESS_EM 
04b0: 56 22 2C 22 43 4F 4E 54 | 41 43 54 5F 45 4D 56 22 V","CONTACT_EMV" 
04c0: 2C 22 4D 41 47 4E 45 54 | 49 43 5F 53 54 52 49 50 ,"MAGNETIC_STRIP 
04d0: 45 22 2C 22 4D 41 47 4E | 45 54 49 43 5F 53 54 52 E","MAGNETIC_STR 
04e0: 49 50 45 5F 46 41 4C 4C | 42 41 43 4B 22 2C 22 4D IPE_FALLBACK","M 
04f0: 41 47 4E 45 54 49 43 5F | 53 54 52 49 50 45 5F 49 AGNETIC_STRIPE_I 
0500: 4E 43 4F 4D 50 4C 45 54 | 45 22 2C 22 43 4F 4E 54 NCOMPLETE","CONT 
0510: 41 43 54 4C 45 53 53 5F | 4D 41 47 53 54 52 49 50 ACTLESS_MAGSTRIP 
0520: 45 22 5D 2C 22 74 65 72 | 6D 69 6E 61 6C 54 79 70 E"],"terminalTyp 
0530: 65 22 3A 22 4D 50 4F 53 | 22 2C 22 70 69 6E 43 61 e":"MPOS","pinCa 
0540: 70 61 62 69 6C 69 74 79 | 22 3A 22 48 41 52 44 57 pability":"HARDW 
0550: 41 52 45 22 2C 22 66 65 | 61 74 75 72 65 73 22 3A ARE","features": 
0560: 5B 22 53 49 4E 47 4C 45 | 5F 54 41 50 5F 50 49 4E ["SINGLE_TAP_PIN 
0570: 5F 53 55 50 50 4F 52 54 | 22 5D 7D 2C 22 74 65 72 _SUPPORT"]},"ter 
0580: 6D 69 6E 61 6C 50 72 6F | 76 69 64 65 72 22 3A 22 minalProvider":" 
0590: 54 65 73 74 50 72 6F 76 | 69 64 65 72 22 2C 22 73 TestProvider","s 
05a0: 6F 66 74 77 61 72 65 50 | 72 6F 76 69 64 65 72 22 oftwareProvider" 
05b0: 3A 22 54 65 73 74 53 77 | 50 72 6F 76 69 64 65 72 :"TestSwProvider 
05c0: 22 2C 22 73 6F 66 74 77 | 61 72 65 56 65 72 73 69 ","softwareVersi 
05d0: 6F 6E 22 3A 22 31 2E 30 | 2E 30 2E 30 22 2C 22 6D on":"1.0.0.0","m 
05e0: 6F 64 65 6C 22 3A 22 72 | 65 73 74 61 70 69 54 65 odel":"restapiTe 
05f0: 73 74 22 7D 7D                                    st"}}

The AES128 CMAC calculated for the above message is:

74305947679E045F191630778DF1BDF1

The size for a MAC is 8 bytes, so we pick only the first 8 bytes of the cacluated CMAC:

74305947679E045F

Base64 encoded this MAC is:

dDBZR2eeBF8=

So, the header message-authentication-value for the HTTP request to IPG has to look like:

dDBZR2eeBF8=;MASTERSESSION;CMACwithAES128;171717;MsTestKey;20260714