# Setup

Configure the Unity Portal, activate your terminal, and connect Oracle Simphony EMC.

## Overview

Follow these steps to connect Oracle Simphony to PXP POS+. PXP or your implementer completes the Unity Portal steps, then your team or an Oracle partner completes the Simphony EMC steps.

Simphony initiates payments and POS+ captures the card. See [How it works](/guides/point-of-sale/pos-plus/oracle/how-it-works) for integration options and the payment sequence. Pay at Counter sends requests from a Windows workstation to a separate PED. Pay at Table sends requests locally on the same S1F4 Pro. See [Pay at Counter](/guides/point-of-sale/pos-plus/oracle/pay-at-counter) and [Pay at Table](/guides/point-of-sale/pos-plus/oracle/pay-at-table).

## Before you start

Gather these before you configure Unity or EMC:

- Oracle Simphony v19.1 or later (v19.9 recommended)
- Payment terminal with POS+ pre-installed
- Merchant ID and site ID from PXP (or created in the Unity Portal)
- Site ID must be ≤ 15 characters (used in Simphony as `{merchantId}|{siteId}`)
- Simphony EMC access


## Step 1: Configure Unity

### Merchant and site

Set up the merchant hierarchy as follows:

1. In the Unity Portal, create or verify the merchant group, merchant, and site.
2. Ensure the site ID is 15 characters or fewer.
3. Note the merchant ID and site ID. Simphony needs them in the format `{merchantId}|{siteId}`. For example, `MERCHANT_1|SITE_1`.


### Add and activate a device

Each Castles terminal needs a Unity POS record with POS+ adaptor type set to Oracle SPI. Once activated, the device downloads its settings and generates the TLS certificate Simphony uses to connect.

#### Add a device in the Unity Portal

Create the POS record with these steps:

1. Go to **Merchant setup > Sites** and select the site for this terminal.
2. Open the **Services** tab and click **Edit** on the *Pos service* row.
3. Click **New POS**.
4. Under *General settings*, set *POS+ adaptor type* to **Oracle SPI**.
5. Make a note of the **POS ID**. This becomes the Simphony **Workstation Number**. It can't be changed after creation.
6. Configure other settings as required. See [Device settings](/guides/point-of-sale/pos-plus/oracle/device-settings).
7. Click **Save**.


The device state is .

Oracle Simphony uses TLS certificate authentication, not the HMAC key shown for the POS service. You don't need the HMAC key for Simphony payment flows.

Pay at Table
For All-in-One on S1F4 Pro, create the workstation in Simphony EMC first and use the Workstation ID as the POS ID in the Unity Portal. See [Pay at Table](/guides/point-of-sale/pos-plus/oracle/pay-at-table#android-workstation-emc).

#### Activate the device

Bring the terminal online and activate it as follows:

1. Set the device status to  (**Actions > Pending**).

2. Turn on the terminal and connect it to the internet.
3. Open the **POS+** app. The device registers with Unity and its state changes to .
4. The device downloads Portal settings, including the Oracle SPI adaptor type.
5. POS+ generates a **client TLS certificate** used when Simphony connects to the terminal.


### Acquirer and DCC

Complete acquirer setup with these actions:

1. Route the site to a [supported acquirer](/guides/point-of-sale/pos-plus/oracle/how-it-works#acquirers).
2. If you use DCC, enable it at acquirer level. [Learn about DCC](/guides/point-of-sale/pos-plus/dcc).


### Root CA certificate 

TLS with certificate-based authentication is coming soon. Download the PXP root CA from the Unity Portal and configure it in Oracle Simphony to enable TLS when this becomes available. In the meantime, Operators must set the workstation connection status to **HTTPS without validation**.

Install trust material with these steps:

1. Download the **PXP root CA certificate** from the Unity Portal Administrator settings.
2. Provide the certificate file to whoever configures Simphony workstations.
3. Install it in Simphony so the workstation trusts POS+ TLS certificates.


Certificate lifecycle
POS+ generates a client certificate when the device activates and renews it automatically before expiry. Install the PXP root CA on Simphony workstations so they trust POS+ certificates. You don't need to manage terminal certificates manually unless the trust store changes. See [TLS authentication](#tls-authentication).

## Step 2: Configure Simphony (EMC)

Configure these values in Simphony EMC to match Unity Portal. See [Unity to Simphony mapping](#unity-to-simphony-mapping) for the full reference.

### Payment driver

Configure the payment driver as follows:

1. Log in to **EMC**.
2. Go to **Setup > Payment Drivers**.
3. Set **Merchant Number** to `{merchantId}|{siteId}` matching Unity exactly.


### Workstation

Configure the workstation as follows:

1. Go to **Setup > Workstations**.
2. Create or open the workstation for this checkout position.
3. Set **Workstation Number** to the Unity Portal's **POS ID**.
4. Configure the **connectivity endpoint** to point at the Castles device:


```
https://{pedId}:8181/api/v1/pos-transactions-oracle
```

Use the PED identifier or network address supplied for your deployment. For Pay at Counter, this is typically the Castles payment terminal on your local network. For Pay at Table (All-in-One), use the endpoint value provided during onboarding for local SPI traffic on the same device.

1.  Configure **TLS** for 1-way certificate authentication using the PXP root CA. In the meantime, set the workstation connection status to **HTTPS without validation**.


### Gratuity (optional)

Configure tip percentage options in EMC if your venue uses gratuity. See [Gratuity and service charges](/guides/point-of-sale/pos-plus/oracle/gratuity-and-service-charges).

### Service Host (if applicable)

Under the workstation **General** tab, set **Service Host** to the IP address of the Simphony host that should receive POS callbacks. For a standard Pay at Counter Windows workstation, use the Windows PC IP address.

## Network requirements

Oracle Simphony communicates with POS+ over your local network. Ensure the paths below are open before go-live testing.

### Pay at Counter

Keep this network path open for counter deployments:

| From | To | Port  | Protocol | Purpose |
|  --- | --- | --- | --- | --- |
| Simphony Windows workstation | Payment terminal (PED) | `8181` | HTTPS | SPI payment requests |


Also confirm these local network requirements:

- The Windows PC and PED are on the same network (or routed so they can reach each other).
- Firewalls allow inbound traffic to the PED on port `8181` from the Simphony workstation.


### Pay at Table (All-in-One)

Allow these paths for All-in-One traffic:

| From | To | Port  | Protocol | Purpose |
|  --- | --- | --- | --- | --- |
| Simphony Android client | POS+ on same device | `8181` | HTTPS | Local SPI payment requests |
| Android device | Back-office Simphony host (if used) | `8080` | TCP | Service Host communication |


Also confirm these local network requirements:

- Port `8181` is available locally on the S1F4 Pro for POS+.
- If your deployment uses a central Simphony host, allow bidirectional traffic on `8080` between the Android device and that host.
- Confirm both devices can reach each other before transaction testing.


## TLS authentication 

TLS with certificate-based authentication is coming soon. Download the PXP root CA from the Unity Portal and configure it in Oracle Simphony to enable TLS when this becomes available. In the meantime, operators must set the workstation connection status to **HTTPS without validation**.

Oracle Simphony uses 1-way TLS certificate authentication:

| Party | Role |
|  --- | --- |
| POS+ | Presents a client certificate when Simphony connects. |
| Simphony | Validates the certificate using the PXP root CA installed during setup. |


Use these values when reviewing TLS setup and renewal:

| Item | Detail |
|  --- | --- |
| Authentication | 1-way TLS. POS+ presents the certificate. |
| Trust | Install PXP root CA on Simphony workstations or devices. |
| Certificate renewal | Automatic on the PED. No manual terminal certificate management. |


## Unity to Simphony mapping

Map Unity Portal values to Simphony EMC using this reference:

| Unity Portal  | Simphony EMC | Format / notes |
|  --- | --- | --- |
| Merchant ID + Site ID | Site ID | `{merchantId}\|{siteId}` (pipe separator) |
| POS ID | Workstation Number | Exact match required |
| PED endpoint | Connectivity endpoint | `https://{pedId}:8181/api/v1/pos-transactions-oracle` |
| Root CA file  | TLS trust store | PXP root CA from the Unity Portal Administrator settings. In the meantime, set the workstation connection status to **https without validation**. |


## Step 3: Test

Validate the integration with these checks:

1. Confirm [network requirements](#network-requirements) are met for your integration path.
2. Run a test purchase in Simphony and complete payment on the Castles terminal.
3. Verify the transaction appears in the Unity Portal and your acquirer reporting.


Repeat staging tests before production go-live.