Digest Calculation
The digest is a parameter that ensures the source and integrity of the request/response, ensuring that the message has not been tampered with since the digest was calculated. 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 alphanumeric 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 and must be stored securely within the merchant’s platform.
If the digest is calculated incorrectly, then the message cannot be identified correctly and will result in the request being rejected.
Request Digest
The following steps detail how to calculate the digest correctly and how it will be transmitted.
The digest must be calculated on the exact form of the message that 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 message and then Base64 encode it (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 encoding (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 message and then Base64 encode it (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 encoding (not chunked, using UTF-8) from the concatenation of the previous step.
- Extract the value of the HTTP header named X-MERCHANT-DIGEST and compare the value with that from the previous step.
If the response digest calculation fails, please inform the support department immediately with the transaction identifiers.