In-Store (POS) API Troubleshooting List

Terminal Access Denied. Insufficient permissions to act on this terminal.

Wrong Terminal ID

Confirm whether Terminal ID used is same with what ShopBack provided (eg: check for typo or additional blank space). Else, check with ShopBack team.

Missing
Authorization
Header. Field is required in all requests.

The Authorization header is not
be included in the request

Ensure that you have included a valid Authorization header
✖ This is wrong
Date: 2022-09-13T08:40:47.000Z
Content-Type: application/json
✔ This is right
Authorization: SB1-HMAC-SHA256 {accessKeyId}:{Hmac}
Date: 2022-09-13T08:40:47.000Z
Content-Type: application/json

Invalid Auth
Header. Unable
to recognize
Auth Code.

The prefix of “SB1-HMAC-
SHA256” is missing

Ensure that SB1-HMAC-SHA256 is included as the prefix for the Authorization header
✖ This is wrong
Authorization: {accessKeyId}:{Hmac}
✔ This is right
Authorization: SB1-HMAC-SHA256 {accessKeyId}:{Hmac}

Hmac signature
has expired,
please generate
a new signature.

The timestamp provided is not a
UTC timestamp (e.g. ends in
+08:00), or

The server timestamp is not accurately following real world timestamp (difference in ~1 minute)

Ensure the timestamp is in UTC time and follows the format:
https://momentjs.com/docs/#/displaying/as-iso-string/
✖ This is wrong
2022-09-13T08:40:47.000+08:00
✔ This is right
2022-09-13T08:40:47.000Z

Invalid
accessKeyId
provided.

The credentials being used are not
valid credentials for the chosen
environment (e.g. sandbox vs
production)

Confirm whether accessKeyId used is same with what ShopBack provided (eg: check for typo, additional blank space, environment). Else, check with ShopBack team.

Invalid
signature.
Failed to match
HMAC signatures.

There is a problem with the data
being used to generate the HMAC.
This could include:

1. The credentials being used are not valid credentials for the chosen environment (e.g. sandbox vs production)
2. Failing to alphabetically sort the keys
3. Failing to stringify the JSON object correctly
4. Stringify the JSON object twice
5. Using the wrong content-type header
6. Converting the hmac output to base64 instead of hex

Before stringifying the payload, ensure that it is dictionary (alphabetically) sorted

✖ This is wrong
{
referenceId: '352c530dd7f747161a5e6c990c720bec',
currency: 'SGD',
posId: '802c987em7f747269a5e6c260c630kpl',
amount: 1000
}
✔ This is right
{
amount: 1000,
currency: 'SGD',
posId: '802c987em7f747269a5e6c260c630kpl',
referenceId: '352c530dd7f747161a5e6c990c720bec'
}

The payload must be a JSON object and stringified as one → there should be no new line characters in the stringified version
✖ This is wrong
{\n amount: 4000,\n country:"SG",\n currency:"SGD",\n posId:"6c1682a7-a9a4-492d-bb3f-884cb06c9f0e",\n qrType:"base64",\n referenceId:"93f47910-4035-
434b-9c86-5cf96b829489"\n}
✔ This is right
{"amount":4000,"country":"SG","currency":"SGD","posId":"6c1682a7-a9a4-492d-bb3f-884cb06c9f0e","qrType":"base64","referenceId":"93f47910-4035-434b-9c86-5cf96b829489"}

When performing a POST, ensure that the payload is not stringified twice if using the boilerplate code
✖ This is wrong
"{"amount":4000,"country":"SG","currency":"SGD","posId":"6c1682a7-
a9a4-492d-bb3f-884cb06c9f0e","qrType":"base64","referenceId":"93f47910-
4035-434b-9c86-5cf96b829489"}"
✔ This is right
{"amount":4000,"country":"SG","currency":"SGD","posId":"6c1682a7-a9a4-492d-bb3f-884cb06c9f0e","qrType":"base64","referenceId":"93f47910-4035-434b-9c86-5cf96b829489"}

The Content-Type header should be set to application/json:
✖ This is wrong
Content-Type: application/x-www-form-urlencoded
✔ This is right
Content-Type: application/json

• *The HMAC signature should be a “Hex” value, not a base64 value
  Use hmac.digest(“hex”) - i.e. a hex string representation**
  ✖ This is wrong
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(request_data);
  return hmac.digest('base64');
  ✔ This is right
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(request_data);
  return hmac.digest('hex');

Invalid posId. Unable to find matching posId.

PosId does not exist or is not completely setup yet.

Confirm that posId used is correct with what ShopBack provided. Else, check with ShopBack team.

Invalid
referenceId.
Unable to find an existing
payment record
with the
referenceId
provided.

ReferenceId does not exist.

Confirm that referenceId used exists.

Invalid Date Header. Date Header has to be ISO-8601 format.

The format of the timestamp does not conform to ISO-8601 in the following format YYYY-MM-DDTHH:mm:ss.000Z

• *The date timestamp should follow this format:
  YYYY-MM-DDTHH:mm:ss.000Z**
  https://momentjs.com/docs/#/displaying/as-iso-string/
  ✖ This is wrong
  2022-09-13T08:40:47Z
  ✔ This is right
  2022-09-13T08:40:47.000Z

Hmac validation Error. Please
ensure all required parameters are
provided with the specified types

Missing required parameters

Ensure all required parameters are
provided with the specified types

Invalid referenceId.
Unable to find an existing payment record
with the referenceId provided.

ReferenceId does not exist

Ensure referenceId used exists or the same with the previous completed transaction.

Unable to refund order when it is
not in captured state.

Order is not in captured state

Ensure order status is in captured state (not pending, abandoned)

Unable to cancel order when it is not in captured state.

Order is not in captured state

Ensure order status is in captured state (not pending, abandoned)

Invalid country to currency pair. Currency is not supported in specified country.

Currency is different from supported country

Ensure currency is same with supported country.

For example
‣ Country MY is paired with currency MYR
‣ Country SG is paired with currency SGD

Invalid country code. Please use the 2 letter country code according to ISO3166 standard.

2 letter country code does not follow ISO3166 standard

Singapore: SG
Malaysia: MY
Australia: AU

Invalid currency
code. Please use
the 3 letter
currency code
according to
ISO4217
standard.

3 letter currency code does not follow ISO4217 standard

Singapore: SGD
Malaysia: MYR
Australia: AUD

Invalid qrType.
Accepted types
are "base64" or
"payload".

qrType used is different from "base64" or
"payload"

Ensure qrType used is "base64" or
"payload".

Invalid posId.
Please provide a
string value.

posId used does not exist

Confirm whether posId used is same with what ShopBack provided (eg: check for typo or additional blank space)

Invalid
referenceId.
Please provide a
string value.

referenceId does not follow string format

Ensure referenceId used is in the string value.

Invalid reason.
Please provide
a string value.

reason does not follow string format

Ensure reason is in the string value.

Invalid amount.
Please provide
an integer
value.

The amount is not specified in the smallest denomination of the currency for the transaction

All amounts in the API are quoted as a whole number (no decimal places) i.e. in the lowest denomination of the currency.

For example
‣ SGD 2.99 would be written as 299
‣ SGD 20 would be written as 2000

For the amount SGD 29.00
✖ This is wrong
"amount": 29
"amount": 29.00
✔ This is right
"amount": 2900

Invalid amount.
Please provide a
positive number.

The amount is not specified in the smallest denomination of the currency for the transaction

All amounts in the API are quoted as a whole number (no decimal places) i.e. in the lowest denomination of the currency.

For example
‣ SGD 2.99 would be written as 299
‣ SGD 20 would be written as 2000

For the amount SGD 29.00
✖ This is wrong
"amount": 29
"amount": 29.00
✔ This is right
"amount": 2900

Invalid amount.
Amount has to be at least 100

Amount is lower than minimum amount.

Do not send amount that is lower than minimum amount.

Invalid amount.
Amount has to be at most 150000

Amount has exceeded maximum amount.

Send amount that is lower than maximum amount.

Invalid ReferenceId. ReferenceId provided is already assigned to an existing resource.

ReferenceId is already assigned to an existing transaction.

Use different ReferenceId.