Our PayConex™ V4 API supports two robust authentication methods that ensure the security of both access and transactions. The first method, known as 'basic' authentication, is straightforward and easy to implement. It utilizes a username and password to verify API requests. The second method, HMAC (hash-based message authentication code) authentication, provides an added layer of security by using a secret key to generate a unique hash for each request. This maintains the integrity and authenticity of the requests, providing enhanced protection for sensitive transaction data.

Basic Authentication

🚧

Note

We use the basic authentication method in all our request samples as it simplifies testing and helps you quickly become familiar with the PayConex™ V4 API. Keep in mind that this option is only available in the certification environment.

The basic authentication header is simpler to build than an HMAC header but provides you with fewer layers of security.

To construct a basic authentication header, you need the id and secret of an API key.

📘

Note

See our guides on API Key Management for an overview of how to get and use API keys.

In this example, our values are as follows:

id="api_0c169931aa624727a6d7202ab1e9d320"

secret="6bf6b48e1794489598bbef89aab69948"

These two values then need to be concatenated into a string, separated by a colon, and encoded via Base64 to get the authentication header value.

Base64("api_0c169931aa624727a6d7202ab1e9d320:6bf6b48e1794489598bbef89aab69948")

This is the resulting value of the Base64-encoded credentials:

"YXBpXzBjMTY5OTMxYWE2MjQ3MjdhNmQ3MjAyYWIxZTlkMzIwOjZiZjZiNDhlMTc5NDQ4OTU5OGJiZWY4OWFhYjY5OTQ4"

This is how the authorization header should look when passed with your API request:

Authorization: Basic YXBpXzBjMTY5OTMxYWE2MjQ3MjdhNmQ3MjAyYWIxZTlkMzIwOjZiZjZiNDhlMTc5NDQ4OTU5OGJiZWY4OWFhYjY5OTQ4

HMAC Authentication

The guide below walks you through the process of creating an HMAC authorization header.

In the following example, we utilize the PayConex™ V4 API endpoint to get a Webhook configuration. The process is the same for all PayConex™ V4 API endpoints.

If you are having trouble creating this header, you can have a look at or even use our HMAC script example: HMAC Script implemented in JavaScript, Python, Go and Ruby.

Creating a HMAC Authentication Header

To send a request using HMAC authentication you need to construct an authorization header containing the following properties:

1. Define value for 'id' property

The 'id' property is the API ID value provided for the PayConex™ account. An API ID and secret are generated for you when you begin your integration.

id=api_0c169931aa624727a6d7202ab1e9d320

2. Define value for 'timestamp' property

The 'timestamp' property has to be a valid UNIX timestamp.

timestamp=1664932648

3. Define value for 'nonce' property

The nonce can be any random string, but it can only be used once. In this example, we just use a randomly generated string.

nonce=42bb8a1624ce4273adf2f81a3af564386b91512a71f74cf6b2766edaa0d70e67

4. Calculate the 'ContentHash' value

The ContentHash is an SHA-256 hash (in hexadecimal format) of the HTTP request body.

It is used as one element in the next step to create the "string-to-hash".

In this step, use an SHA-256 function to hash the request body.

The request used for this example is actually empty as we are sending a GET request. If no request body is submitted, the resulting content hash is the SHA-256 value of an empty string.

In this case, the resulting ContentHash value is as follows:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

🚧

Note

The string that is hashed in this example is actually an empty string. When hashing the request body, if you intend to include spaces and line breaks (\n) within the body, these must be present in the string that is hashed to create the ContentHash. In short, if the request body sent is to be hashed, it must match the ContentHash exactly.

For example, in our scripts we make sure to json-stringify the body and use the same one in the request.

JavaScript

const body = JSON.stringify({
  "bfTokenReference": "bft_aab...",
  "posProfile": "MOTO",
  "amounts": {
    "total": "5",
    "currency": "USD"
  }
})

const ContentHash = CryptoJS.SHA256(body)

const canonicalRequest = ""
    + method + " " + url + "\n"
    + nonce + "\n"
    + timestamp + "\n"
    + "\n"
    + ContentHash

const response = CryptoJS.HmacSHA256(canonicalRequest, API_KEY_SECRET)

const authHeader = "Hmac "
    + "id=\"" + API_KEY_ID + "\""
    + ", nonce=\"" + nonce + "\""
    + ", timestamp=\"" + timestamp + "\""
    + ", response=\"" + response + "\""

fetch(`https://api-cert.payconex.net/api/v4/accounts/${accountId}/payments/sale`, {
  "method": "POST",
  "headers": {
    "Authorization": authHeader
  },
  "body": body
})

5. Build the "string-to-hash"

The response property value is created by building a "string-to-hash" and then hashing the string with an HMAC-SHA256 hash function.

The "string-to-hash" is made up of four elements:

For this example, our values are as follows:

• HttpVerb: GET
• CanonicalizedResource: /api/v4/accounts/220614966801/webhooks/wbh_5249941f13564471b3be9f96a6d532c1
• nonce: 42bb8a1624ce4273adf2f81a3af564386b91512a71f74cf6b2766edaa0d70e67
• timestamp: 1664932648
• ContentHash for empty body: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

A valid "string-to-hash" must follow this format:

HttpVerb + " " + CanonicalizedResource + "\n" + nonce + "\n" + timestamp + "\n" + "\n" + ContentHash;

Given the values we defined above, our string-to-hash is as follows:

GET /api/v4/accounts/220614966801/webhooks/wbh_5249941f13564471b3be9f96a6d532c1\42bb8a1624ce4273adf2f81a3af564386b91512a71f74cf6b2766edaa0d70e67\n1664932648\n\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

In a more human-readable format, the string-to-hash would look as follows:

GET /api/v4/accounts/220614966801/webhooks/wbh_5249941f13564471b3be9f96a6d532c1
42bb8a1624ce4273adf2f81a3af564386b91512a71f74cf6b2766edaa0d70e67
1664932648

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

6. Calculate the 'response' property

The 'response' property is calculated using a HMAC-SHA256 hashing (in hexadecimal format) function.

The key used for the HMAC-SHA256 function is the API secret key generated for your PayConex™ account.

In this case, that value is as follows:

6bf6b48e1794489598bbef89aab69948

Creating the response property value at this point is as easy as running the string through a HMAC-SHA256 hashing function. Most programming languages have packaged HMAC-SHA256 functions. Alternatively, they are easy to acquire via package managers like NPM (JavaScript/NodeJS), Gradle/Maven (Java) or PIP (Python).

The result of hashing the "string-to-hash" generated in this example is as follows:

response="9c478d98a80468e42c7acdcd070b7a531042725b28752e631d25118099f9460a"

7. Construct the Authorization Header

Now that all the above elements have been calculated, it is time to build the HMAC Authorization header.

Authorization: Hmac id="api_0c169931aa624727a6d7202ab1e9d320", nonce="42bb8a1624ce4273adf2f81a3af564386b91512a71f74cf6b2766edaa0d70e67", timestamp="1664932648", response="9c478d98a80468e42c7acdcd070b7a531042725b28752e631d25118099f9460a"