Digest Calculation
Server to Server Digest Calculation
The digest is a parameter that ensures the source of the request or response and the integrity of transit of the message and to correctly identify origin of the message. The digest is present for messages sent directly to and directly from the Payen Platform in server to server communication.
The digest is calculated using a password. This password is alpha numeric and will be provided by the Payen Platform to each merchant. The password must never be transmitted in any of the request or response messages.
If the digest is calculated incorrectly then the message cannot be identified correctly and will result in the request being rejected.
Request Digest Calculation
The following steps detail how to calculate the digest correctly and how it will be transmitted.
The message must be used in the exact form in which it will be sent, if any formatting is applied before transmission then this is how it must be used in the digest calculation.
- Calculate a SHA-512 message digest of the request and Base64 encode (not chunked, using UTF-8).
- Concatenate the output of the Base64 encoded digest from step 1 and the secure merchant password.
- Perform another SHA-512 message digest and Base64 encode (not chunked, using UTF-8) from the concatenation of the previous step.
- Set the value of a HTTP header named X-MERCHANT-DIGEST to the Base64 encoded digest value from the previous step.
An example of a digest calculation is as follows:
| Step | Example |
|---|---|
| Example message | <?xml version=”1.0” encoding=”UTF-8” ?><creditRequest></creditRequest> |
| Password | PASSWORD |
| Base64 Encoded SHA-512 Message Digest of original XML(Step 1) | ZedAAfqK+nWSCuZfJ/hH2J/x9RCtX6DpYGHdINhJamArHA6E0Vzbt7Y3oqItK8K90rtbFSR80HYq5OtjGFwOTg== |
| Concatenate Password to Base64 in previous step | ZedAAfqK+nWSCuZfJ/hH2J/x9RCtX6DpYGHdINhJamArHA6E0Vzbt7Y3oqItK8K90rtbFSR80HYq5OtjGFwOTg==PASSWORD |
| Base64 Encoded SHA-512 Message Digest of previous step | q1wwnMnCBd1wfM/9F7YLkHExhXz8olR1Nwi0APnl42qgzZgucJM+TFZq2Y648ew9/EdapUtUKitLUqZVeQaiYg== |
Response Digest
The calculation of the response digest works in the same way as the request digest except that the merchant will need to extract the digest value created by the Payen Platform. The following steps detail how the response digest will be calculated and validated.
- Calculate a SHA-512 message digest of the response and Base64 encode (not chunked, using UTF-8).
- Concatenate the output of the Base64 encoded digest from step 1 and the secure merchant password.
- Perform another SHA-512 message digest and Base64 encode (not chunked, using UTF-8) from the concatenation of previous step.
- Extract the value of the HTTP header named X-MERCHANT-DIGEST and compare the value with that from previous step.
If the response digest calculation fails, please inform the support department immediately with the transaction identifiers.
Browser to Server Digest Calculation
Request Digest Calculation
The following steps detail how to calculate the digest correctly and how it will be transmitted.
- Concatenate the merchant ID, the obtained request key and the secure merchant password.
- Calculate a SHA-512 message digest of the concatenation from step 1 and Base64 encode (not chunked, using UTF-8).
- Add the output of step 2 as an additional parameter to the request named "digest"
An example of a digest calculation is as follows:
| Step | Example |
|---|---|
| merchantid | 10000001 |
| Request Key | 034abf78e80a45a5884af0429293bf0a |
| Password | PASSWORD |
| Concatenated Value (Step 1) | 10000001034abf78e80a45a5884af0429293bf0aPASSWORD |
| Base64 Encoded SHA-512Message Digest (Step 2) | WWdW1mJe+33JmVTcI8N7dqhU2m7L06c8fGMD+UhblSBfm5kELNGIIXg/zt+SklPr/tUDgDil0NQaJeSy578jJw== |
Response Digest Calculation
The calculation of the response digest works in the same way as the request digest except that the merchant will need to extract the digest value created by the Payen Platform. The following steps detail how the response digest will be calculated and validated.
- Concatenate the merchant reference, the returned response key and the secure merchant password.
- Calculate aSHA-512 message digest of the concatenation from step 1 and Base64 encode (not chunked, using UTF-8).
- Compare the output of step 2 with the returned "digest" parameter
If the response digest calculation fails, please inform the support department immediately with the transaction identifiers.
Request Digest Calculation (for return from Third Party)
The following steps detail how to calculate the digest correctly and how it will be transmitted.
- Take all parameters from the request received and sort alphabetically, capitals have a greater precedence over lowercase. Ensure to include the merchantId as part of these parameters.
- Concatenate all parameters in the sorted order and append the merchant secret.
- Calculate theSHA-512 message digest of the concatenation from step 2 and Base64 encode (not chunked, using UTF-8).
- Add the output of step 3as an additional parameter to the request named "digest"
An example of a digest calculation is as follows:
| Step | Example |
|---|---|
| merchantId | 10000001 |
| paymentMethodType | PAYPAL |
| status | PAID |
| token | EC-5X266322BK0751512 |
| Concatenated Value (Step 1) | Z2KJ8KFPHUGES1000002PAYPALPAIDEC-5X266322BK0751512Pa55w0rd |
| Base64 Encoded SHA-512 Message Digest (Step 2) | 9uNAtk/7SkvrsS9OgN8j+wVhAhooBBT3jW7NXT4kDVvN4D4A9Gtcp3PsLiKPBTBXxdt5gq6xNM9gvXYmGvcA0g== |