Skip to main content

Additional security

Ensuring the security of your API should be a top priority in any production environment. At IXOPAY, we understand this need and provide a robust security system to safeguard your data. Our API security includes basic measures such as TLS 1.2 and HTTP Basic Authentication to establish secure communication. Additionally, we offer a signature mechanism that offers an extra layer of protection for API requests and callbacks. The authenticity of messages is guaranteed by utilizing HMAC with SHA2-512 as the hashing algorithm in the signature mechanism.

Here is a summary of the security measures that our APIs offer:

  • TLS 1.2 or later: This cryptographic protocol provides secure communication between the client and server by encrypting all data transmitted over the network.
  • HTTP Basic Authentication: This authentication mechanism requires a valid username and password combination for access to the API.
  • Signatures: HMAC-SHA512 is used to generate signatures for each message sent over the API. These signatures help to ensure the authenticity and integrity of API requests and callbacks.

Signatures

An aspect of the security measures offered by the IXOPAY platform API is the signature mechanism. Signatures are a way of ensuring the authenticity and integrity of API requests and callbacks. A signature is a hashed value that is included in all API responses and callbacks from the platform. Merchants can also sign their own requests to the APIs, which the IXOPAY platform will attempt to verify. It is recommended (but not required) that merchants check the signature of callbacks since this is the only form of communication where no TLS certificate can prove the identity of IXOPAY.

The signature is sent and received in the X-Signature HTTP header. To generate the signature, HMAC (Hash-based Message Authentication Code) using SHA2-512 as the hashing algorithm is used. The secret key for the HMAC is the shared secret configured on your connector.

info

To validate or create signatures, a correct RFC 7231 HTTP Date header is required. As a fallback for certain HTTP libraries, an equivalent X-Date header can be used on the request as well and will take precedence over the Date header.

To implement the signature mechanism, merchants need to compute the signature, validate callback signatures, and sign requests. These steps will be covered in the following sections.

Computing the signature

To compute the signature for a request or callback, you need to follow a specific process. Here are the steps you need to take:

  1. Construct the message string: To construct the message string, you need to concatenate several values together in a specific order. The values are the HTTP method, the SHA512 hash of the request's body, the Content-Type header value, the timestamp as sent in the Date header, and the Request URI.s
    SHA512_BODY="$(echo -n "$BODY" | sha512sum | cut -d " " -f1)"
    MESSAGE="$METHOD\n$SHA512_BODY\n$CONTENT_TYPE\n$DATE\n$REQUEST_URI"
  2. Calculate the HMAC: Once you have the message string, you need to calculate the HMAC using the shared secret provided by your connector.
    HMAC=$(echo -n "$MESSAGE" | openssl dgst -sha512 -binary -hmac "$SHARED_SECRET")
  3. Base64 encode the HMAC: The final step is to Base64 encode the binary HMAC value.
    SIGNATURE=$(echo -n "$HMAC" | base64 -w 0)

After following these three steps, you should have a valid signature that can be included in the X-Signature header of your API request.

Validating callback signatures

To validate the signature of a callback notification, you need to rebuild the signature using the shared secret provided to you, along with any other credentials, as explained in the Computing the signature section. This calculated signature must be compared to the one provided in the X-Signature header of the notification request.

info

It is recommended (but not required) that merchants check the signature of callbacks since this is the only form of communication where no TLS certificate can prove the identity of IXOPAY.

To verify the signature, first, obtain the required data from the notification request and compute the signature following the steps outlined in the Computing the signature section. If the resulting signature matches the X-Signature header provided in the notification request, you can trust the callback.

Here's an example that shows how to validate the signature of a callback:

# See other languages

Signing requests

Signing requests is an optional step that merchants can take to add an additional layer of security to their API requests. To sign a request, you need to follow the same process as described in the Computing the signature section.

Once you have computed the signature using the steps described in Computing the signature, you need to include it in the request headers as the value of the X-Signature header. Here is an example code snippet in PHP that demonstrates how to sign a request:

# See other languages

By including the X-Signature header in your requests, you can ensure that the IXOPAY platform will only accept requests that have been properly signed with the shared secret provided to you during integration.

Signature testing

To evaluate the correctness of your signature algorithm implementation, it is recommended to employ the signature testing tool presented below. Utilizing this tool, you may execute tests to verify the accuracy of your signature algorithm in a controlled environment. The signature testing tool can be found displayed below.

Signature testing tool

Input your signature details in the "Signature parameters" section and check if the signature output in the "Signature output" matches your generated signature.

info

This tool does not verify the validity of the API key, shared secret or the payload itself.

Securely use your real API keys and shared secret without any data being submitted to our servers. The testing tool operates exclusively within your browser using JavaScript.

Signature parameters

Signature output