Skip to main content

Authenticating your Request

Authentication Request

Authentication is completed via a POST request to the test URL shown below.

Security Risk

The Key below must always be stored securely. You can manage your keys if one is compromised.

The POST must contain the below data.

Authentication Request
Field NameStateData TypeDescription
merchantIdMandatoryIntegerThe Merchant ID provided to you during onboarding, or following the creation of your test account. This is NOT your 'mid', it is a value unique to axept® Cloud Connect.
keyIdMandatoryIntegerThis is the ID allocated to the merchant using the authentication key generation process.
keyMandatoryStringThis is the key / password generated using the authentication key generation process and associated with the Key ID.

Authentication Response

A successful response will be 200 - OK and will contain the following two fields:

Authentication Response
Field NameData TypeDescription
TokenStringThe JWT Bearer token. You should store or cache this to authenticate future requests.
ExpiresAtStringThe UTC Datetime that the Bearer Token will expire at

Bearer Token Validity

Issued Bearer tokens are only valid for a given period, as indicated by the expiration date / time. Your POS system needs to manage when to request a bearer token. A new token should be requested in the following scenarios:

  • Your POS system does not have a JWT bearer token e.g. the first request since start-up / reboot
  • The JWT bearer token is due to expire or has already expired.

It is recommended that your POS system employs a thread-safe caching mechanism, which will auto-evict the cached bearer token. If the cache does not contain the bearer token when needed, it re-authenticates with axept® Connect Cloud and caches the issued bearer token. If the cache does contain the bearer token, it can be used for the subsequent authenticated operation.

Error Responses

ErrorIssueAction
400Bad RequestThis represents a syntax error. Check the format of all fields and ensure they are correct then retry
401UnathorizedThe supplied data was formatted correctly but the supplied merchantId, keyId and key were not valid. Check your values and then retry.

Example Code

Example Request

{
"merchantId": 12345,
"keyId": 12,
"key": "R2lJMTMzZ1RCVy60T1h4V3FNshy="
}

Example 200 Response

{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IjEzMzI3IiwibmJmIjoxNjgxMTE2MTg5LCJleHAiOjE2ODExMTc5ODksImlhdCI6MTY4MTExNjE4OSwiaXNzIjoiaHR0cHM6Ly9vcHRvbWFueS1heGVwdGNvbm5lY3RjbG91ZG1lcmNoYW50LXBwZS5henVyZXdlYnNpdGVzLm5ldCIsImF1ZCI6ImF4ZXB0Q29ubmVjdENsb3VkLW1lcmNoYW50LWNsaWVudCJ9.WZddPEsxS7drQfvsvR0oGn5dity32_cYQ52aFjcDwTU",
"expiresAt": "2023-01-31T11:28:09Z"
}