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.
To send a request using HMAC authentication you must construct an Authorization header containing the following properties.
|id||This property must be set to a PayConex API ID.|
|nonce||A nonce is a unique random string. If a nonce is encountered more than once during a 15-minute period the API call is rejected. It is your responsibility to ensure that the nonce is unique.|
|timestamp||A Unix timestamp. Our service will reject API calls with a timestamp older than 15 minutes.|
|response||The response property is an HMAC-SHA256 hash (in hexadecimal format) created from a string (string-to-hash below) of various API request properties. The string is hashed using a PayConex API Secret Key value. See the following information for a detailed description of how to construct the string that must be hashed and included in this 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.
The timestamp property needs to be a valid UNIX timestamp.
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.
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:
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.
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:
|HttpVerb||HTTP method used for the API request.|
|CanonicalizedResource||Should be the HTTP Request URI, without protocol, port, and domain parts. Example:|
|nonce||The value of the nonce will be the same value that was set in the authorization header nonce property discussed above.|
|timestamp||The value of the timestamp will be the same value that was set in the authorization header timestamp property discussed above.|
|ContentHash||An SHA-256 hash (in hexadecimal format) of the HTTP request body will be sent. Our services expect the whole body in its entirety to be hashed. This includes any leading and trailing whitespaces that may have been included when you created your JSON request body. If possible the best and easiest practice is to insure that you have removed all whitespace and newline characters from the JSON or query string data that will be sent with your request.|
For this example our values are as follows:
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:
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
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:
The result of hashing the "string-to-hash" generated in this example is:
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"
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:
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.
This is the resulting value after base64 encoding the credentials.
This is how the authorization header should look when passed with your API request.
authorization: Basic YXBpXzBjMTY5OTMxYWE2MjQ3MjdhNmQ3MjAyYWIxZTlkMzIwOjZiZjZiNDhlMTc5NDQ4OTU5OGJiZWY4OWFhYjY5OTQ4
As stated in the introduction, this option is only available in the testing environment.
Updated about 1 year ago
Learn more about the API end-points by reviewing the definitions guide next!