# Configure device settings

Learn about the available settings and how to configure them.

## Overview

Device settings are configured in the Unity Portal when you first set up a new POS. They're then automatically downloaded to the device when it first connects. You can update a device's settings in the Portal at any time and the modified settings will automatically be updated on the device.

Cloud invocation uses the same Unity Portal device settings as a local POS+ integration. Configure the device once, then invoke it through the cloud device API using the device's `merchantPointOfSaleId`. See [Get started](/guides/point-of-sale/pos-plus/cloud/api/get-started).

For cloud invocation:

- Set **Communication protocol** to `Cloud`.
- Set **Adaptor mode** to `PXP` for the PXP cloud device API. Use `Oracle OPI` for Oracle Opera Cloud (coming soon).


This page covers:

- [Available settings](#available-settings)
- [Receive status packets](#receive-status-packets)
- [Enable DCC](#enable-dcc)
- [Enable gratuity and service charges](#enable-gratuity-and-service-charges)


## Available settings

### General settings

#### POS settings

| Name | Description |
|  --- | --- |
| Status | The current status of the POS device. |
| POS ID | The unique identifier for the point-of-sale device. This is set at device creation and can't be changed later. |
| Device model | The device model. |
| Serial number | The serial number of the device. |
| Communication protocol | The communication protocol used to transfer data to and from the device. For cloud invocation, set this to `Cloud`. Other values such as `TCP` or `HTTP` apply to local integrations. |
| Adaptor mode | The adaptor used for cloud communication. For the PXP cloud device API, set this to `PXP`. For Oracle Opera Cloud, set this to `Oracle OPI`. |
| Communication endpoint | The URL that PXP should communicate with. |
| Commercial model | The commercial model. This can be `One-time fee`, `Recurring fee`, or `One-time & Recurring fee`. |


#### Host URLs

| Name | Description |
|  --- | --- |
| Instore notification URL | The URL that PXP sends device logs to. |
| Store & forward URL | The URL that PXP sends transactions to for processing, if store and forward is enabled. |
| Transaction URL | The URL that PXP sends transactions to. |
| Reporting URL | The URL that PXP sends reports to. |
| Status Packet URL | The URL that PXP sends status updates to. [Learn more](#receive-status-packets). |


#### Logging settings

| Name | Description |
|  --- | --- |
| Verbose logging | Whether verbose logging is enabled for this device. |
| Maximum log size (MB) | The maximum size that a log can reach, in megabytes. Once this size is reached, the old log will be discarded and a new log will be created. |
| Log file clean up days | The number of days after which PXP will delete the log data. |
| Device log level | The device log level. This can be one of:`None`: no information is logged.`Information`: all activity is logged.`Exception`: only errors or exceptions that caused issues with a transaction are logged.`Health`  |


### Feature settings

#### General

| Name  | Description  | Default value  |
|  --- | --- | --- |
| Return status packets | Receive status updates about the customer's payment journey. This will only work if you have a status packet webhook URL configured. [Learn more](#receive-status-packets). |  |
| Language selection  | Allow customers to choose a display language for the device. |  |
| Gratuity | Allow customers to add a gratuity. [Learn more](#enable-gratuity-and-service-charges). |  |
| Service charge | Enable service charges. [Learn more](#enable-gratuity-and-service-charges). |  |
| P2PE | Enable point-to-point encryption. |  |
| Accessibility mode | Enable accessibility mode. |  |
| Currency | The default currency. | `GBP` |
| On-device limit | The on-device limit. | `100.00` |
| Contactless limit | The contactless payment limit. | `50.00` |
| Floor limit | The floor limit. | `0.00` |
| CVM limit | The CVM limit. | `50.00` |
| Refund limit | The refund limit. [Learn more](/guides/point-of-sale/pos-plus/cloud/api/refund). |  |


#### Receipt settings

| Name  | Description  | Default value  |
|  --- | --- | --- |
| Print Merchant Receipt | Print a merchant receipt, in addition to the customer receipt. |  |
| Certification Mode | Provides additional EMV details when running a certification on behalf of an acquirer. **This should not be enabled when live.** |  |


#### DCC settings

| Name  | Description  | Default value  |
|  --- | --- | --- |
| Enabled | Enable Dynamic Currency Conversion for this device. When enabled, eligible transactions will automatically present currency choice options to international customers. [Learn more](/guides/point-of-sale/pos-plus/dcc). |  |
| DCC on Pre-auths | Allow DCC to be offered on estimated authorisations. |  |
| DCC on Capture | Allow DCC to be offered on captures. |  |


#### Terminal capabilities

| Name  | Description  | Default value  |
|  --- | --- | --- |
| Keyed | Allow card payments where card details are manually keyed in. |  |
| MOTO | Allow Mail Order/Telephone Order payments. |  |
| Swiped | Accept card payments with swipe (magnetic strip). |  |
| Contact Chip (ICC) | Accept card payments with chip. |  |
| On-Line PIN | Accept card payments with online Personal Identification Number (PIN). |  |
| Plaintext PIN (Offline) | Accept card payments with a plaintext offline Personal Identification Number (PIN). |  |
| Paper Signature | Accept card payments with signature. |  |
| Offline PIN (Encrypted) | Accept card payments with an encrypted offline Personal Identification Number (PIN). |  |
| No CVM Required | Accept card payments without requiring any card verification. |  |
| Static Data Authentication (SDA) | Enable Static Data Authentication (SDA). This is a basic security mechanism used in EMV chip cards where the card contains a digital signature created by the issuing bank that remains constant (static) for the life of the card. |  |
| Dynamic Data Authentication (DDA) | Enable Dynamic Data Authentication (DDA). This is a security mechanism used in EMV chip card transactions where the payment terminal verifies the authenticity of the card by performing a real-time cryptographic challenge-response authentication. During this process, the chip card generates a unique digital signature using its private key for each transaction, and the terminal validates this signature using the card's public key certificate. This makes it extremely difficult for fraudsters to clone or counterfeit cards, since each transaction requires a new and unique cryptographic proof of authenticity. |  |
| Card Capture Capability | Enables you to physically retain (capture) a customer's card. For example, if you suspect fraudulent activities. |  |
| Combined DDA/AC Generation (CDA) | Enable combined Dynamic Data Authentication (DDA) and Application Cryptogram (AC) generation. DDA verifies the authenticity of the chip card by validating its digital signature, while AC generation creates a unique cryptogram for each transaction to ensure its security and prevent replay attacks. This combined process enhances transaction security by verifying both the card's legitimacy and the transaction's integrity in one step. |  |


### Store and Forward settings

| Name  | Description  | Default value  |
|  --- | --- | --- |
| Store and Forward | Enable Store and Forward for this device. [Learn more](/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions#store-and-forward). |  |
| Transaction amount threshold | The threshold amount up to which to store a transaction for offline processing. Transactions with an amount above this threshold won't be stored. | `0` |
| Days Until Ftp Upload | The number of days after which PXP will upload a file to FTP. | `7` |
| Throttling limit | The maximum number of transaction we can send in one go. | `0` |
| Process interval(s) | The interval between processes, in seconds. | `0` |


## Receive status packets

By activating the `Return status packets` feature, you can receive details about customer interactions that take place on the device in real time. This means you can find out exactly where the customer is on the payment journey and can assist with any issues, without having to look at the POS device.

Once configured, you'll receive status updates to your chosen webhook URL in the following format:

```json
{
  "statusUpdate": {
    "deviceIsDisplaying": "PinOk",
    "customerInteraction": "None",
    "merchantPOSId": "POS-001",
    "merchantTransactionId": "TXN-001",
    "eventId": "41b43c87-59c0-4b2e-9e10-09f939a5860c",
    "timeStamp": "2025-01-27T08:51:02.826445+00:00"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `statusUpdate`object | Details about the status update. |
| `statusUpdate.deviceIsDisplaying`string (enum) | The screen displayed on the device.Possible values:`None``AppSelection``AuthorisingTransaction``CardRemovedTimeout``ChooseDcc``EnterCardInfo``EnterPin``GratuitySelection``InsertCard``InsertOrTapCard``InsertTapOrSwipeCard``LastEnterPin``PaymentCompleted``PaymentDeclined``PaymentError``PinEntryFailed``PinOk``PosError``ProcessingTransaction``RemoveAndReinsertCard``RemoveCard``ReSwipeCard``RetryEnterPin``SeePhoneInstruction``SwipeCard``SwipeOrTapCard``TapCard``TransactionCancelledByShopper` |
| `statusUpdate.customerInteraction`string (enum) | The interaction that the customer had with the device.Possible values:`None``CardInserted``CardTapped``CardSwiped``CardRemoved``CardSwipedFail``CardInsertedFail``AppSelected``CancelPressed``CardPresentedFail``CardInsertedSwipedFail``EnteringCardInfo``EnteringPin``DccAccepted``DccRejected``GratuityEntered``GratuityIgnored` |
| `statusUpdate.merchantPOSId`string | The unique identifier for the point-of-sale device, as assigned in the Unity Portal (POS ID). |
| `statusUpdate.merchantTransactionId`string | The unique identifier for this transaction, as assigned by you. |
| `statusUpdate.eventId`string (UUID) | The unique identifier associated with this event. |
| `statusUpdate.timeStamp`string (date-time) | The date and time when the status update was generated, in ISO 8601 format. |


#### Device display statuses

The following table describes the possible device display statuses.

| Display status  | Displayed... | Screenshot |
|  --- | --- | --- |
| `AppSelection` | When using a card supporting multiple applications on one device. |  |
| `AuthorisingTransaction` | When the transaction is being authorised. |  |
| `CardRemovedTimeout` | When the card hasn't been removed, but has already timed out. | N/A. This a result from the device with no specific display screen. |
| `ChooseDcc` | When allowing the customer to select a currency. |  |
| `EnterCardInfo` | When manual card entry is required. |  |
| `EnterPin` | When the customer enters their PIN for the first time. |  |
| `GratuitySelection` | When the customer is prompted to add a gratuity. |  |
| `InsertCard` | When the customer inserts their card for the first time. |  |
| `InsertOrTapCard` | When transactions are initiated on a device configured only for insert and tap transactions. |  |
| `InsertTapOrSwipeCard` | When transactions are initiated on a device configured for insert, tap, or swipe transactions. |  |
| `LastEnterPin` | After verifying the offline PIN failed for the second time. |  |
| `PaymentCompleted` | When the payment is completed. |  |
| `PaymentDeclined` | After a payment was declined. |  |
| `PaymentError` | When a payment error occurs. | N/A. This a result from the device with no specific display screen. |
| `PinEntryFailed` | After verifying the online PIN failed. | N/A. This a result from the device with no specific display screen. |
| `PinOk` | After verifying the offline PIN successfully. | N/A. This a result from the device with no specific display screen. |
| `PosError` | When an exceptions occurs while using the POS device. | N/A. This a result from the device with no specific display screen. |
| `ProcessingTransaction` | When the transaction is being processed. |  |
| `RemoveAndReinsertCard` | When prompting the customer to remove and reinsert their card. | N/A. This a result from the device with no specific display screen. |
| `RemoveCard` | When prompting the customer to remove their card. |  |
| `ReSwipeCard` | After swiping the card failed. |  |
| `RetryEnterPin` | After verifying the offline PIN failed for the first time. |  |
| `SeePhoneInstruction` | When the device instructs the customer to check their phone. | N/A. This a result from the device with no specific display screen. |
| `SwipeCard` | When the customer swipes their card for the first time. |  |
| `SwipeOrTapCard` | When transactions are initiated on a device configured only for swipe and tap transactions. |  |
| `TapCard` | When transactions are initiated on a device configured only for tap transactions. | N/A. This a result from the device with no specific display screen. |
| `TransactionCancelledByShopper` | When the transaction is cancelled using the Cancel button. | N/A. This a result from the device with no specific display screen. |


### Add a status packet URL

To add a status packet URL that updates will be sent to:

1. In the Unity Portal, go to **Merchant setup > Sites**.
2. Select the site associated with the device.
3. In the *Services* tab, find the *Pos service* and click **Edit**.
4. Click **General settings**.
5. Under *Host URLs*, enter a **Status Packet URL**.

6. Click **Save** in the top right.


Your status packet URL is now configured and you're ready to activate the feature.

You can override the status packet URL configured in the Unity Portal by including the `statusCallbackUrl` parameter in your API request when initiating a transaction or modification. This allows you to use different webhook URLs for specific transactions. For more information, see the [API reference](/apis/cloud-device-transaction).

### Activate the feature

To activate the feature for a specific device:

1. In the Unity Portal, go to **Merchant setup > Sites**.
2. Select the site associated with the device.
3. In the *Services* tab, find the *Pos service* and click **Edit**.
4. Click on the device that you want to activate the feature for.
5. Click **Feature settings**.
6. Under *General*, switch the **Return status packets** toggle on.

7. Click **Save** in the top right.


The feature is now active for this device. You'll start receiving status updates to your configured status packet URL.

## Enable DCC

Dynamic Currency Conversion (DCC) allows your customers to pay in their card's native currency when making purchases in a foreign country. This feature provides transparency about exchange rates and can generate additional revenue through commission fees and markups.

Before you can use DCC, you need to enable it in the Unity Portal and configure your POS devices.

DCC availability depends on your acquirer and their partnership with FX rate providers. Contact your account manager to confirm DCC is available for your region.

This feature is available for S1F2, S1F4 Pro, and S1P2 devices.

### Enable DCC for your site

Before terminals can use DCC, the DCC service must be enabled and configured at the site level, and a rates provider must be selected. This ensures all devices at a location use the same rates provider and DCC settings.

1. In the Unity Portal, go to **Merchant groups** > **Sites**.
2. Select the site where you want to enable DCC.
3. In the **Features** section, toggle **Dynamic Currency Conversion** to **On**.
4. From the **Rates Provider** drop-down, select your FX rates provider.
5. Configure your preferred DCC behaviour for different transaction types (see [Transaction settings](#transaction-settings)).
6. Click **Save** in the top right.


The rates provider you select must be compatible with your acquirer. For example, if you use Elavon as your acquirer, you must select Elavon as your rates provider.

### Transaction settings

Different transaction types require specific DCC handling. Configure how DCC behaves for authorisations, captures, and refunds to match your business needs.

#### Authorisations and captures

When a customer authorises a payment with DCC (such as at hotel check-in), the capture will automatically use the latest exchange rates at the time of capture (check-out).

The ability to show rates to the customer at capture time is a future enhancement.

If a customer wishes to change their currency choice, the merchant must void or cancel the original authorisation and perform a new transaction.

#### Refunds

DCC behaves differently for refunds depending on the refund type:

* **Linked refunds:** If a purchase was made with DCC, the refund must be processed in the same currency (cardholder currency). The system will automatically apply the original currency.
* **Standalone refunds:** DCC isn't supported for standalone refunds. These must be processed in your local merchant currency.


### Enable DCC on your devices

Once DCC is configured at the site level, you need to enable it for individual terminals in the DCC feature settings:

1. In the Unity Portal, go to **Merchant setup > Sites**.
2. Select the site associated with the device.
3. In the *Services* tab, find the *Pos service* and click **Edit**.
4. Click on the device that you want to activate the feature for.
5. Click **Feature settings**.
6. Under *DCC settings*, switch the **Enabled** toggle on.
7. Click **Save** in the top right.


The device will automatically download the updated configuration during its next sync.

### Verify your configuration

After enabling DCC, test your configuration by:

1. Processing a test transaction with a card that has a different currency from your merchant currency.
2. Verifying the DCC prompt appears on the device screen.
3. Confirming both currency options are displayed correctly.
4. Completing the transaction and checking the receipt includes all DCC information.


Check the *DCC Statistics* section of your dashboard to monitor DCC opportunities and acceptance rates. [Learn more](/guides/get-started/dashboard#dcc-statistics).

For common DCC issues, see [Troubleshooting](/guides/point-of-sale/pos-plus/cloud/api/troubleshooting#dynamic-currency-conversion-dcc).

## Enable gratuity and service charges

Gratuity and service charges allow you to add additional fees to purchase transactions, providing flexible pricing models for hospitality venues with transparent fee communication. These features are particularly useful for situations where you need to reward service staff or apply percentage-based fees.

For cloud invocation, gratuity and service charges offer flexible implementation options depending on where you want to manage them.

#### Gratuity

Gratuity allows customers to add a tip when making purchases. Tips can be handled in two ways:

* **Managed on your cloud ePOS:** Your application handles tip selection and sends the tip amount in the transaction request to the device. The tip is displayed on the printed receipt but the tip selection interface is not shown on the POS+ device.
* **Managed on the POS+ device:** The device displays your configured tip percentage options to the customer, who can select a percentage, enter a custom amount, or proceed without a tip. The tip amount is automatically included in the transaction total and returned in a separate field of the API response to your cloud ePOS.


#### Service charges

Service charges allow you to add percentage-based fees to transactions with two different approaches:

* **Mandatory service charges:** A fixed percentage automatically added to the transaction total. Mandatory service charges can be sent in your transaction request to the device to be included on the receipt. The amount goes to the employer and is reported as service charge amounts in the Unity Portal. For example, a 10% service charge for group bookings of more than 8 people.
* **Voluntary service charges:** A suggested percentage that the customer can accept or decline. Voluntary service charges can be sent in your transaction request to the device, and the customer will be presented with the option to accept or decline it on the POS+ device. If accepted, the amount is added to the total and appears as gratuity on the receipt. If declined, the transaction proceeds with only the original amount. Accepted voluntary service charges must be provided to employees like tips and are reported as gratuity amounts in the Unity Portal (in accordance with regional regulations, such as UK tipping law).


Both features are only available for purchase transactions—they're not supported for refunds, authorisations, or other transaction types.

You can't send `gratuity` and `serviceCharge` together on the same request.

Before you can use gratuity or service charges, you need to enable them in the Unity Portal and configure your POS+ devices.

These features are available for S1F2, S1F4 Pro, and S1P2 devices.

### Enable gratuity

#### Enable gratuity for your site

Before devices can offer gratuity options, the feature must be enabled and configured at the site level. This ensures all devices at a location use the same tip percentage options when device-based tip collection is used.

1. In the Unity Portal, go to **Merchant groups** > **Sites**.
2. Select the site where you want to enable gratuity.
3. In the *Services* tab, find the *Pos service* and click **Edit**.
4. Click **General POS service settings**.
5. In the *Gratuity* section, toggle **Gratuity** to **On**.
6. Configure your three pre-selected tip percentages (see [Tip percentage configuration](#tip-percentage-configuration)).
7. Click **Save** in the top right.


Gratuity is now enabled for all devices associated with this site. You can disable it at the device level if needed. See [Enable or disable gratuity on a device](#enable-or-disable-gratuity-on-a-device).

##### Tip percentage configuration

When tips are managed on the POS+ device, you can configure three predefined tip percentages that will be displayed to customers during checkout. These percentages provide quick-select options for common tipping amounts.

* Each percentage value must be unique.
* Values will automatically be displayed from lowest to highest.
* The options will appear with 1, 2, and 3 stars to indicate the tip levels.


Example: If you configure 10%, 15%, and 20%, customers will see these three options plus a custom amount option at the payment screen.

If tips are managed on your cloud ePOS and sent in the transaction request, these percentage configurations are not used. However, the feature must still be enabled at the site level.

#### Enable or disable gratuity on a device

Once gratuity is configured at the site level, it's enabled for all devices under the site.

To disable or enable it at the device level:

1. In the Unity Portal, go to **Merchant setup > Sites**.
2. Select the site associated with the device.
3. In the *Services* tab, find the *Pos service* and click **Edit**.
4. Click on the device that you want to manage the feature for.
5. Click **Feature settings**.
6. In the *General* section, toggle the **Gratuity** switch.
7. Click **Save** in the top right.


The device will automatically download the updated configuration during its next sync.

Disabling gratuity at the site level will turn off the feature for all devices. If the feature is enabled at the site level, you can control it individually for each device.

### Enable service charges

#### Enable service charges for your site

Before devices can apply service charges, the feature must be enabled at the site level. This ensures all devices at a location can use service charge functionality.

1. In the Unity Portal, go to **Merchant groups** > **Sites**.
2. Select the site where you want to enable service charges.
3. In the *Services* tab, find the *Pos service* and click **Edit**.
4. Click **General POS service settings**.
5. In the *Service charge* section, toggle the **Service charge** to **On**.
6. Click **Save** in the top right.


Service charges are now enabled for all devices associated with this site. You can disable them at the device level if needed. See [Enable or disable service charges on a device](#enable-or-disable-service-charges-on-a-device).

#### Enable or disable service charges on a device

Once service charges are configured at the site level, they're enabled for all devices under the site.

To disable or enable them at the device level:

1. In the Unity Portal, go to **Merchant setup > Sites**.
2. Select the site associated with the device.
3. In the *Services* tab, find the *Pos service* and click **Edit**.
4. Click on the device that you want to manage the feature for.
5. Click **Feature settings**.
6. In the *General* section, toggle the **Service charge** switch.
7. Click **Save** in the top right.


The device will automatically download the updated configuration during its next sync.

### API integration

When integrating gratuity and service charges with your cloud ePOS, you have flexibility in how you handle these fees. See [Initiate POS transactions](/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions) for request shapes.

#### Sending tip amounts to the device

When tips are managed on your cloud ePOS, include the gratuity amount in `amounts.gratuity` on the initiate request. The device will process the transaction and print a receipt showing the tip separately. The tip selection interface won't be shown on the POS+ device.

#### Receiving tip amounts from the device

When tips are managed on the POS+ device, the customer selects the tip amount on the device during checkout. The API response includes the tip amount in a separate field. Your application should:

* Capture and store the tip amount for your records.
* Display the tip amount in your app's transaction history.
* Use the tip data for staff payroll or reporting purposes.


#### Sending mandatory service charges to the device

When you need to apply mandatory service charges, include the service charge in `amounts.serviceCharge` on the initiate request. The device will process the transaction with the service charge included and print a receipt showing the charge separately.

#### Sending voluntary service charges to the device

When you want to offer customers the option to add a service charge, include the suggested service charge in `amounts.serviceCharge` and set `optional` to `true`. The device will present the option to the customer. If the customer accepts, the amount is added to the total and appears as gratuity on the receipt. The API response will include whether the charge was accepted and the final amount.

### Verify your configuration

After enabling gratuity or service charges, test your configuration.

#### Testing gratuity

**When tips are managed on the device:**

1. Process a test purchase transaction without sending a tip amount in your request.
2. Verify the gratuity prompt appears with your configured percentage options on the device.
3. Select a tip amount and complete the transaction.
4. Check the receipt includes the tip amount separately from the purchase amount.
5. Verify the API response includes the tip amount in a separate field.


**When tips are managed on your app:**

1. Process a test purchase transaction with a tip amount included in your request.
2. Verify the transaction processes without showing a tip selection screen on the device.
3. Check the receipt includes the tip amount separately from the purchase amount.


#### Testing service charges

**Mandatory service charges:**

1. Process a test purchase transaction with a mandatory service charge included in your request.
2. Verify the service charge is included in the transaction total.
3. Check the receipt displays the service charge amount separately from the purchase amount.


**Voluntary service charges:**

1. Process a test purchase transaction with a voluntary service charge included in your request.
2. Verify the device presents the customer with the option to accept or decline the charge.
3. Test both accepting and declining to confirm the correct behaviour.
4. Check that accepted voluntary service charges appear as gratuity on the receipt.
5. Verify the API response indicates whether the charge was accepted.


### Reporting

Gratuity and service charge data is captured across multiple reporting tools:

* **Transaction reports:** The Unity Portal includes tip and service charge amounts for each transaction in your standard reports. See our [Reporting](/guides/reporting) section for more information.
* **End of day reports:** EOD summaries include all tips and service charges captured during the day.
* **API responses:** Tip amounts are included in payment responses for integration with your own reporting systems.


For common gratuity and service charge issues, see [Troubleshooting](/guides/point-of-sale/pos-plus/cloud/api/troubleshooting#gratuity-and-service-charges).