Hash MAC-Authentication in Request

To protect against unauthorised manipulation of your payment transactions, the Pay-Jet Cockpit checks with the aid of a Hash Message Authentication Code (HMAC) whether your payment enquiry is authentic and has not been manipulated. For this purpose you transfer an HMAC value to the Cockpit with each transaction in the parameter MAC.

Background: Unlike the HMAC procedure every encoding method has the disadvantage that there is a matching decoding method. Anyone who possesses the correct key or cracks the encryption can read and manipulate the data. Therefore, no encryption method is ever 100% safe. In the case of the Hash procedure, conversely, decoding is impossible, so that a Hash value can confirm the authenticity of the message free of doubt.

The Pay-Jet Cockpit uses a Hash Message Authentication Code (HMAC) to check the authenticity of your payments. The HMAC SHA-256 algorithm is used with a 32-digit key length (256 bits) for this. The additional password makes the HMAC procedure particularly safe.

The following table describes how you can generate the Hash values for your payment:

Step

Task

1

Please log on to Pay-Jet Support, which supplies you with the Hash password.

2

The HMAC value is calculated with the aid of the password and several parameter values. For the calculation, the parameters PayID, TransID, MerchantID, Amount and Currency are used and separated with asterisks:

PayID*TransID*MerchantID*Amount*Currency 

KeyValueComments
PayIdReferenced PayIdMay be empty, e.g. for creating an initial payment process or risk management request; is used with subsequent requests like capture/refund.
TransIdYour transactionId to reference / identify your requestYour own reference to identify each request / payment process.
MerchantIdYour MerchantId assigned to you by Pay-JetYour MerchantId identifiying this request.
AmountAmount in smallest unit of currency, e.g. 123=1,23Amount of this request; may be empty if not used, e.g. for status inquiries.
CurrencyCurrency of payment process in ISO 4217, e.g. EUR, USD, GBPCurrency of this request; may be empty if not used, e.g. for status inquiries.
YourHmacPasswortYour HMAC-password assigned to you by Pay-JetYour HMAC-password assigned to a specific MID; if you have different MIDs you will have different HMAC passwords, too.

Notice: If a transaction does not support all of these parameters, you can simply omit the missing value.

For example, there is no PayID yet with the first transaction, so you do not have to transfer this. The PayID is a component of the Hash calculation in subsequent transactions:

Samples for MAC calculationFormulaResult
without PayId, with amount/currency
HmacSHA256("*TID-4453732122167114558*yourMerchantId*1234*EUR", "mySecret")
38CED807E293FC634A6C36FFAEA7BD2687038D40615781918AEF2DE7BB9A9903
without PayId, without TransId, with amount/currencyHmacSHA256("**yourMerchantId*1234*EUR", "mySecret")ECBCAB7361CFFE1694D2E893280AED0FEEC2FCF518A736009D38CBD65F0DC68B
with PayId, without amount/currencyHmacSHA256("fe3f002e19814eea8aa733ec4fdacafe*TID-4453732122167114558*yourMerchantId**", "mySecret")5A3ED13E4BF3492166E8E9B5898F372735B6FDCBFFC41B2AB4574A9A6FC9B734

3

Use the HMAC SHA-256 algorithm, which nearly all programming languages support, in order to calculate the Hash value with the password and the parameter values.

4

Use the MAC parameter to transfer the hexadecimal encoded Hash value to the Cockpit with each transaction in the encoded data field.

 Notice: Note that the MAC parameter is obligatory for all subsequent transactions (e.g. capture, credit note) if it was transferred with the first transaction (e.g. authorisation).

Important: The Cockpit rejects transactions with wrong or missing HMAC values promptly without further processing, because this is an indication of hacker attacks. Therefore, transactions which the Cockpit rejects with the error codes 20100044 or 20120044 do not appear in Pay-Jet Backoffice.

Listing with HMAC examples

Request without PayID:

MerchantID=YourMerchantID&TransID=100000001&Amount=11&Currency=EUR&URLSuccess=https://www.shop.de/ok.html&URLFailure=https://www.shop.de/failed.html&OrderDesc=My purchase

String for MAC generation:

*100000001*Test*11*EUR

Request with MAC:

MerchantID=YourMerchantID&TransID=100000001&Amount=11&Currency=EUR&URLSuccess=https://www.shop.de/ok.html&URLFailure=https://www.shop.de/failed.html&OrderDesc=My purchase&MAC=A0E3A8BB9473CF4D3F91181E0859650A9AF3F4AD0AE1E839AC7B750247A2E947

Request without TransID:

MerchantID=YourMerchantID&PayID=8ee4e922c39446ac9ee66095a4a4b475&Amount=100&Currency=USD

String for MAC generation:

8ee4e922c39446ac9ee66095a4a4b475**Test*100*USD

Request with MAC:

MerchantID=YourMerchantID&PayID=8ee4e922c39446ac9ee66095a4a4b475&Amount=100&Currency=USD&MAC=F1EB4A8BB9473CF4D3F91181F0859659A9AF3F4AD0AE1E839AC7B750247A2D636



  • No labels