Integration

Integrate with the POS+ API to process payments directly from your Castles device.

Step 1: Get your credentials

Before performing a transaction, obtain the following credentials:

HMAC key: Used for authentication and to create the HMAC signature for each API request.
Merchant credentials: Your merchant ID, site ID, and point-of-sale ID, as assigned by PXP.
POS server URL: The address of the payment server. This is a combination of the IP address of the device and port 8181.

HMAC key

To find your HMAC key:

In the Unity Portal, go to Merchant setup > Sites.
Select a site.
In the Services tab, find the Pos service row.
Click Edit.
The HMAC key is displayed in the top left. Click the copy icon () to copy it to your clipboard.

Merchant credentials

Merchant ID

To find your merchant ID:

In the Unity Portal, go to Merchant setup > Merchants.
Select a merchant.
In the General information tab, look for Merchant ID.

Site ID

To find your site ID:

In the Unity Portal, go to Merchant setup > Sites.
Select a site.
In the General information tab, look for Site ID.

Point-of-sale ID

In the Unity Portal, go to Merchant setup > Sites.
Select a site.
In the Services tab, find the Pos service row.
Click Edit.
Select a device.
Click General settings.
In the POS settings section, look for POS ID.

POS server URL

The POS server URL is constructed from your Castles device's IP address and port 8181.

Get your device's IP address

You'll need to obtain your device's IP address first. You can do this manually or programmatically.

To get the device's IP address manually:

Go to the Settings option on your device.
Select Network and Internet.
Choose the Internet option.
Click on the settings of your connected Wi-Fi and scroll down to view the IP address.

Construct the POS server URL

Once you have the IP address, construct your POS server URL:

http://{IpAddress}:8181/api/v1/pos-transactions

Where:

{IpAddress} is the IP address from your device.
8181 is the open port for the endpoint.
api/v1/pos-transactions is the transaction endpoint.

For example:

http://192.168.10.108:8181/api/v1/pos-transactions

Step 2: Prepare your API request

With your credentials ready, prepare your API request payload. The following example shows an in-store purchase transaction:

{
  "merchant": "{merchantId}",
  "site": "{siteId}",
  "pointOfInteraction": {
    "pointOfSaleId": "{posId}",
    "language": "en",
    "storeAndForwardType": "None"
  },
  "merchantTransactionId": "{merchantTransactionId}",
  "merchantTransactionDate": "2025-11-04T12:00:00.000Z",
  "amounts": {
    "transaction": 100.00,
    "currencyCode": "USD",
    "gratuity": null
  },
  "transactionMethod": {
    "entryType": "Instore",
    "fundingType": "Card",
    "intent": "Purchase"
  },
  "merchantDeeplink": "myapp://payment/result"
}

Step 3: Generate an HMAC signature

The POS+ API uses HMAC (Hash-based Message Authentication Code) with SHA256 for authentication to ensure secure communication and data integrity.

For each API request, you need to:

Create a unique request ID (UUID or GUID).
Generate a timestamp (Unix timestamp in seconds).
Combine the timestamp, request ID, request path, and request body.
Use your HMAC key to create an HMAC-SHA256 signature.

HMAC signature format

The signature is calculated using the following data:

{timestamp}{requestId}{requestPath}{requestBody}

Where:

{timestamp} is the current Unix timestamp in seconds.
{requestId} is a unique UUID for the request.
{requestPath} is the API path (e.g., api/v1/pos-transactions).
{requestBody} is the JSON request body as a string.

Implementation examples

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;

namespace Pxp.Pos.Sdk.Utils
{
  public static class HttpRequestMessageExtensions
  {
    public static HttpRequestMessage BuildHMACAuthentication(
      this HttpRequestMessage request,
      string requestBody,
      string apiKey,
      string endpoint)
    {
      var uri = new Uri(endpoint);
      var requestPath = uri.AbsolutePath.Trim('/');
      var requestId = Guid.NewGuid().ToString();
      var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
      var hmacRequestData = $"{timestamp}{requestId}{requestPath}{requestBody}";
      var hmacResult = ComputeHmacSha256(hmacRequestData, apiKey);
      var authHeader = $"PXP-HMAC1 {timestamp}:{hmacResult}";
      
      request.Headers.Add("Authorization", authHeader);
      request.Headers.Add("X-Request-Id", requestId);
      
      return request;
    }

    private static string ComputeHmacSha256(string data, string key)
    {
      using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key)))
      {
        var hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(data));
        return BitConverter.ToString(hashBytes).Replace("-", "").ToUpper();
      }
    }
  }
}

Step 4: Add HTTP headers

Include the HMAC signature and request ID in your HTTP headers:

Header	Description	Format
`Authorization`	The HMAC signature, consisting of the authentication scheme (`PXP-HMAC1`), timestamp, and HMAC value.	`PXP-HMAC1 {timestamp}:{hmac}`
`X-Request-Id`	The unique request ID (UUID) that you generated.	`{requestId}`