Hash HMAC-Authentication in Notify
The shop must verify that a notification request really comes from | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Platform-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
. Otherwise an attacker can initialise a transaction and then falsify this notification. A shop operator will not manually check whether a corresponding transaction was performed in each case. Therefore, the module must do this automatically.
Currently, the notification request is only encrypted. However, this encryption does not guarantee the authenticity of a message. It only guarantees that a message cannot be listened in on. Therefore, this safety measure is insufficient.
As a result, the response parameter MAC is used, which is formed via the same algorithm as the MAC in request. Only the data parameters differ.
The following data pattern applies here for hash generation: PayID*TransID*MerchantID*Status*Code
The MAC parameter is only returned to the URLSuccess or URLFailure and for URLNotify.
Your integration must check whether the response received is authentic.
The following table describes how you can generate the Hash values to validate | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Platform-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
response that you received:
Step | Task |
|---|
1 | Please log on to | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Helpdesk-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
, 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, Status and Code are used and separated with asterisks: PayID*TransID*MerchantID*Status*Code
| Key | Value | Comments |
|---|
| PayID | Referenced PayID | PayID returned by | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Platform-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
| | TransID | Your transactionId to reference / identify your request | Your own reference to identify each request / payment process. | | MerchantID | Your MerchantID assigned to you by | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Partner-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
| Your MerchantID identifiying this request. Please use the value of parameters MID from | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Platform-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
notification request. | | Status | Status in response | Status of response, e.g. AUTHORIZED, FAILED, OK, ... | | Code | Code in response | Code of response, e.g. 00000000, 22720040, ... | | YourHmacPasswort | Your HMAC-password assigned to you by | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Partner-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
| Your HMAC-password assigned to a specific MID; if you have different MIDs you will have different HMAC passwords, too. |
| Samples for MAC calculation | Formula | Result |
|---|
| Authorized payment | HmacSHA256("7bbb448155234d8cbee323778952ce28*TID-12033175321270170232*YourMerchantID*AUTHORIZED*00000000", "mySecret") | F1DE7608013C1E3FD3CC9964A049E26703137C0A6F29448545C700B4695EABE5 | | Failed payment | HmacSHA256("7bbb448155234d8cbee323778952ce28*TID-12033175321270170232*YourMerchantID*FAILED*22720040", "mySecret") | 1D9A8AAA306316359B8192070237670950DB77073F9F34ED7EB483D9B59DE1DD |
|
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 | Verify - the MAC-value from
| Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Platform-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
response that you received - with the MAC value that you calculated yourself
to ensure that the message you have received is authentic. |
The MAC parameter is only returned to the URLSuccess or URLFailure and for Notifys.
| Note |
|---|
Important: Your system has to ensure that a notification request has really be sent by | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Platform-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
. Therefore the received values for PayID, TransID, MerchantID, Status and Code have to be hashed using your HMAC-password and this HMAC-value must be identical with MAC-value from request. If these values do not match the request must not be processed.
Important: To calculate HMAC-value please use the value of parameter MID which has be sent by | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Platform-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
.
|
| Note |
|---|
Important: Password (like HMAC-password) must never be sent via email, because email is not a secure way of data transmission. If passwords are sent or forwarded via email new passwords need to be established at the expense of the merchant or will be changed with next release of MerchantID-changes. | Multiexcerpt include |
|---|
| SpaceWithExcerpt | EN |
|---|
| MultiExcerptName | Partner-Name |
|---|
| PageWithExcerpt | Wording |
|---|
|
| Multiexcerpt include |
|---|
| SpaceWithExcerpt | DE |
|---|
| MultiExcerptName | Partner-Name |
|---|
| PageWithExcerpt | DE:Wording |
|---|
|
expressly points out the risk of further use of such compromised MIDs. If a merchant continues to use such a compromised MID, he himself bears the liability risk for possible losses caused by the compromised passwords. |
