API Authentication

The main method of API authentication that should be used for the Account Updater API is HMAC authentication.

This authentication method requires calculating specific values and constructing an HMAC header. This authentication method is required in the production environment.

The guide below will walk you through how to create an HMAC authorization header to utilize the Account Updater API.

If you're just testing in a development environment and want to test without implementing HMAC authentication in your test environment you can test using a basic authentication header. You can view the details of that method here.

Creating an HMAC Authentication Header

To send a request using HMAC authentication you must 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 will be generated for you as you begin your integration.

id=api_0c169931aa624727a6d7202ab1e9d320

2. Define value for 'timestamp' property

The timestamp property needs 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 are just using a randomly generated string.

nonce=duvqfsPbl3eiOnW2oOLri7Chfp

4. Calculate the ContentHash value

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

It will be 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:

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 linebreaks (\n) within the body then those must be present in the string that is hashed to create the ContentHash. In short, if the request body sent were to be hashed, it must match the ContentHash exactly.

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: duvqfsPbl3eiOnW2oOLri7Chfp
• timestamp: 1664932648
• ContentHash: 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 would be:

POST /api/v4/accounts/220614966801/webhooks/wbh_5249941f13564471b3be9f96a6d532c1\duvqfsPbl3eiOnW2oOLri7Chfp\n1664932648\n\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

In a more human-readable format the string-to-hash would look like this:

GET /api/v4/accounts/220614966801/webhooks/wbh_5249941f13564471b3be9f96a6d532c1
duvqfsPbl3eiOnW2oOLri7Chfp
1664932648

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

6. Calculate the 'response' property

The 'response' property is calculated by using an 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:

6bf6b48e1794489598bbef89aab69948

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

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

response="ad449c72a625fbf1b2186cd3b51726c306cae330788858983dc4f5f14a1f91c6"

7. Construct the Authorization Header

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

Authorization: Hmac id="api_0c169931aa624727a6d7202ab1e9d320", nonce="duvqfsPbl3eiOnW2oOLri7Chfp", timestamp="1664932648", response="ad449c72a625fbf1b2186cd3b51726c306cae330788858983dc4f5f14a1f91c6"

Using a Basic Authentication Header

The basic authentication header is simpler to build but is not as secure as HMAC authentication. For this reason, we include it as an option for testing, but it cannot be used when moving your integration to production.

To construct a basic authentication header you need your API id, and secret.

In this example my values are:

id= api_0c169931aa624727a6d7202ab1e9d320

secret=6bf6b48e1794489598bbef89aab69948

These two values then need to be put into a string, separated by a colon. After that you can base64 encode them to get the authentication header value.

api_0c169931aa624727a6d7202ab1e9d320:6bf6b48e1794489598bbef89aab69948

This is the resulting value after base64 encoding the credentials.

YXBpXzBjMTY5OTMxYWE2MjQ3MjdhNmQ3MjAyYWIxZTlkMzIwOjZiZjZiNDhlMTc5NDQ4OTU5OGJiZWY4OWFhYjY5OTQ4

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

authorization: Basic YXBpXzBjMTY5OTMxYWE2MjQ3MjdhNmQ3MjAyYWIxZTlkMzIwOjZiZjZiNDhlMTc5NDQ4OTU5OGJiZWY4OWFhYjY5OTQ4

🚧

Note

As stated in the introduction, this option is only available in the testing environment.