In-Store (POS) API Troubleshooting List
This page lists common POS API errors along with their possible root causes to help you quickly identify and resolve integration issues. Use this as a reference during development or debugging to streamline troubleshooting and ensure a smooth integration process.
Common Authorization Scenarios
| Error Message | Potential Root Causes | How to Mitigate |
|---|---|---|
| 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'); |
Common Not Found Errors
| Error Message | Potential Root Causes | How to Mitigate |
|---|---|---|
| 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. |
Common Bad Request Errors
| Error Message | Potential Root Causes | How to Mitigate |
|---|---|---|
| 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 |
Common Validation Errors
| Error Message | Potential Root Causes | How to Mitigate |
|---|---|---|
| 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. |
Common Conflict Error
| Error Message | Potential Root Causes | How to Mitigate |
|---|---|---|
| Invalid ReferenceId. ReferenceId provided is already assigned to an existing resource. | ReferenceId is already assigned to an existing transaction. | Use different ReferenceId. |
Updated 3 days ago