# Troubleshooting

Resolve common issues with cloud device API setup, device features, and transactions.

## Overview

Cloud device troubleshooting covers authentication failures, device registration and connectivity, feature configuration (such as DCC, gratuity, and keyed entry), status packets, and unexpected transaction outcomes.

Before you work through the checks below, confirm you have completed [Get started](/guides/point-of-sale/pos-plus/cloud/api/get-started), [Manage POS devices](/guides/point-of-sale/pos-plus/cloud/api/manage-devices), and [Configure device settings](/guides/point-of-sale/pos-plus/cloud/api/configure-settings).

This page covers:

- **Dynamic Currency Conversion (DCC):** When DCC isn't offered or the wrong currency appears.
- **Gratuity and service charges:** Tip and service charge display, receipt, and response issues.
- **Authentication:** HMAC signature failures and `401` responses.
- **Device connectivity:** Registration stuck in New or Pending, Cloud status, and timed-out initiate calls.
- **Status packets:** Missing in-journey updates versus merchant webhooks.
- **Transaction outcomes:** `Refused` and `Error` states, and keyed entry not appearing.


## Dynamic Currency Conversion (DCC)

For setup steps, see [Enable DCC](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#enable-dcc).

| Issue  | Next steps |
|  --- | --- |
| DCC isn't being offered to customers. | If DCC isn't appearing for eligible transactions:1. Check your site configuration: Verify DCC is enabled at the site level and a rates provider is selected.
2. Check your device configuration: Ensure DCC is enabled on the specific device.
3. Verify card eligibility: Confirm the card meets all eligibility criteria (different currency, supported scheme, above CVM limit if contactless).
4. Check the rate provider connectivity: If the device can't reach the rates provider, DCC won't be offered. Check your network connection and contact support if the issue persists.

 |
| The incorrect currency is displayed. | This is typically a testing issue where the BINs need to be configured on the FX provider. Contact your FX provider to ensure the card BINs are properly configured. |


## Gratuity and service charges

For setup steps, see [Enable gratuity and service charges](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#enable-gratuity-and-service-charges).

| Issue  | Next steps |
|  --- | --- |
| Gratuity option isn't appearing on the device. | If the tip selection screen isn't showing when tips should be managed on the device:1. Check your site configuration: Verify that gratuity is enabled at the site level and all three tip percentages are configured.
2. Check your device configuration: Ensure that gratuity is enabled on the specific device.
3. Verify your API request: Ensure you're not sending a tip amount in your request, which would bypass the device tip selection.
4. Verify the transaction type: Confirm that you're processing a purchase transaction (gratuity isn't available for other transaction types).
5. Check your device sync: Ensure that the device has synced recently to receive the latest configuration.

 |
| Tip amounts sent from the app aren't appearing on receipts. | Verify that gratuity is enabled at both the site and device level. Ensure your API request includes the tip amount in the correct field format. |
| Tip amounts aren't included in API responses. | When tips are managed on the device, check that your integration captures all response fields. Verify that gratuity is enabled for the device processing the transaction. |
| Tip percentages aren't displaying correctly on the device. | Verify your site configuration includes three unique percentage values. If you recently changed the percentages, ensure the device has synced to receive the updated configuration. This only applies when tips are managed on the device. |
| Service charges sent from the app aren't appearing on receipts. | Verify that service charges are enabled at both the site and device level. Ensure your API request includes the service charge in the correct field format. |
| Service charge amounts aren't calculating correctly. | Verify that you're sending the correct value (percentage or amount) in your API request. Check the receipt to confirm the calculation is based on the original purchase amount. |
| Voluntary service charges aren't appearing as gratuity on receipts. | Ensure you've specified the charge as voluntary/optional in your API request. Verify the customer accepted the voluntary service charge on the device during checkout. Check the API response to confirm acceptance. |


## Authentication

| Issue  | Next steps |
|  --- | --- |
| Requests return `401` Unauthorised. | Confirm you are signing with the site HMAC key from the Unity Portal, using the cloud device path (for example `api/v1/cloud-device/{merchantPointOfSaleId}/transactions`) without a leading slash in the HMAC payload. Check that the timestamp is current and that `Authorization` and `X-Request-Id` are set as described in [Get started](/guides/point-of-sale/pos-plus/cloud/api/get-started). |
| Signature verification fails intermittently. | Ensure every request uses a new `X-Request-Id`, that the body string used for the HMAC matches the body you send byte-for-byte, and that clocks are not drifting far from UTC. |


## Device connectivity

| Issue  | Next steps |
|  --- | --- |
| The device never leaves  or . | Set the device to Pending in the portal, power on the terminal, connect it to the internet, and open the POS+ app so it can register. Confirm **Communication protocol** is `Cloud` and **Adaptor mode** is `PXP` (or `Oracle OPI` for Opera). See [Add a device](/guides/point-of-sale/pos-plus/cloud/api/manage-devices#add-a-device). |
| Cloud status is Disconnected or Unavailable in terminal diagnostics. | Confirm the device has network access, the POS Hub service is enabled for the site, and the app version supports live diagnostics. Refresh or restart the app after Hub registration. See [View terminal diagnostics](/guides/point-of-sale/pos-plus/cloud/api/manage-devices#view-terminal-diagnostics). |
| Initiate calls time out or the device does not present a payment journey. | Check Cloud status in diagnostics, confirm `merchantPointOfSaleId` / `pointOfInteraction.pointOfSaleId` match the active device, verify the terminal is online, and that **Communication protocol** is `Cloud` with the correct **Adaptor mode**. |


## Status packets

| Issue  | Next steps |
|  --- | --- |
| No status packets arrive at the webhook. | Enable **Return status packets** for the device, configure a Status Packet URL (or pass `statusCallbackUrl` on the request), and confirm your endpoint is reachable from the internet. See [Receive status packets](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#receive-status-packets). |
| Status packets arrive but merchant webhooks do not (or the reverse). | Status packets report in-journey device screens; merchant webhooks report final transaction outcomes. Configure both if you need both. See [Webhooks](/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions#webhooks) and [Manage webhooks](/guides/get-started/manage-webhooks). |


## Transaction outcomes

| Issue  | Next steps |
|  --- | --- |
| Response `state` is `Refused`. | Treat the HTTP `200` as a completed attempt that the issuer declined. Inspect `stateData` and `providerResponse.merchantAdvice`, then decide whether to retry with a different card or follow the advice code. See [Initiate POS transactions](/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions#initiate-a-initiate-transaction). |
| Response `state` is `Error`. | Inspect `stateData` (for example timeout or malfunction). Check device connectivity and whether Store and Forward applies. See the Error response example on [Initiate POS transactions](/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions#initiate-a-initiate-transaction). |
| Keyed entry is not offered on the device. | Enable the **Keyed** terminal capability and send `pointOfInteraction.invokeKeyed` as `true`. See [Configure device settings](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#terminal-capabilities) and [Invoke keyed](/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions#invoke-keyed). |