Skip to content
Point-of-Sale devices
/
/
Add a POS device

POS service API (1.0.0)

This is an API reference for the Point of Sale service, which allows you to manage point of sale devices, including their settings, activation, and configuration.

Download OpenAPI description
point-of-sale.json
point-of-sale.yaml
Languages
Servers
Production environment

https://api-services.pxp.io/api/v1/

Sandbox environment

https://api-services.test.pxp.io/api/v1/

Manage POS devices

Operations

Add a POS device

Request

This endpoint is used to initiate a new point of sale device for a specific site. It creates the device with the provided configuration settings.

Path
sitestringrequired

The ID of the site where the point of sale will be deployed.

Example: SITE-1
Bodyapplication/jsonrequired

Configuration details for the new point of sale device.

serialNumberstringrequired

The serial number of the point of sale device

Example: "SN1234567890"
merchantPointOfSaleIdstringrequired

The unique merchant identifier for the point of sale device.

Example: "POS-12345"
deviceModelstring(DeviceModels)required

The model of the point of sale device.

Enum"CastlesSaturn1000""ZebraTC510K"
Example: "CastlesSaturn1000"
communicationProtocolstring(CommunicationProtocols)required

The protocol used by the point of sale device.

Value"HTTP"
Example: "HTTP"
communicationEndpointstring or null(CommunicationEndpoint)

The URL or network endpoint where the point of sale device actively listens for incoming connections and communications from the merchant system.

Example: "http://pos.example.com"
authenticationSettingsobject(AuthenticationSettings)required

The authentication settings for a point of sale device.

authenticationSettings.​hmacKeystringrequired

The single hmac key used in association with the point of sale device to authenticate.

Example: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
hostUrlsArray of objects or null(HostUrl)

The endpoint URLs used by the PXP point of sale application.

Example: [{"url":"https://transaction.example.com","urlType":"Transaction"}]
logSettingsobject(LogSettings)

The log settings for a point of sale device.

featureSettingsobject(FeatureSettings)

The feature settings for a point of sale device.

storeAndForwardSettingsobject(StoreAndForwardSettings)

The store and forward settings for a point of sale device.

curl -i -X POST \
  https://api-services.pxp.io/api/v1/point-of-sales/SITE-1 \
  -H 'Content-Type: application/json' \
  -d '{
    "serialNumber": "SN1234567890",
    "merchantPointOfSaleId": "POS-12345",
    "deviceModel": "CastlesSaturn1000",
    "communicationProtocol": "HTTP",
    "communicationEndpoint": "http://pos.example.com",
    "authenticationSettings": {
      "hmacKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    },
    "hostUrls": [
      {
        "url": "https://transaction.example.com",
        "urlType": "Transaction"
      }
    ],
    "logSettings": {
      "verboseLoggingEnabled": true,
      "maximumLogSize": 10485760,
      "logFileCleanUpDays": 30
    },
    "featureSettings": {
      "statusPacketsEnabled": true,
      "languageSelectionEnabled": true,
      "gratuityEnabled": false,
      "onlinePinEnabled": true,
      "keyedEnabled": false,
      "dccEnabled": false
    },
    "storeAndForwardSettings": {
      "storeAndForwardEnabled": true,
      "transactionAmountThreshold": 10000,
      "throttlingLimit": 100,
      "processInterval": 300,
      "x509PrivateKey": "MIIBVgIBADANBgkqhkiG9w0BAQEFAASC...",
      "x509PublicKey": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...",
      "keyGenerated": "2023-09-01T12:00:00Z"
    }
  }'

Responses

Successfully initiated the point of sale device.

Bodyapplication/json
statusstring(Status)

The status of the point of sale device.

Enum"New""Pending""Active""Disabled"
Example: "Active"
sitestring

The ID of the site where the point of sale will be deployed.

Example: "SITE-1"
merchantPointOfSaleIdstring

The unique merchant identifier for the point of sale device.

Example: "POS-12345"
pointOfSaleIdinteger(int64)

The unique system identifier for the point of sale device.

Example: 123456789
Response
application/json
{
  "status": "Active",
  "site": "SITE-1",
  "merchantPointOfSaleId": "POS-12345",
  "pointOfSaleId": 123456789
}

Retrieve a POS device

Request

This endpoint retrieves the details of a specific point of sale device by its merchant ID.

Path
sitestringrequired

The ID of the site where the point of sale is located.

Example: SITE-1
merchantPointOfSaleIdstringrequired

The unique merchant identifier for the point of sale device.

Example: POS-12345
curl -i -X GET \
  https://api-services.pxp.io/api/v1/point-of-sales/SITE-1/POS-12345

Responses

Successfully retrieved the point of sale device details.

Bodyapplication/json
sitestring

The ID of the site where the point of sale will be deployed.

Example: "SITE-1"
serialNumberstring

The serial number of the point of sale device

Example: "SN1234567890"
merchantPointOfSaleIdstring

The unique merchant identifier for the point of sale device.

Example: "POS-12345"
pointOfSaleIdinteger(int64)

The unique system identifier for the point of sale device.

Example: 123456789
deviceModelstring(DeviceModels)

The model of the point of sale device.

Enum"CastlesSaturn1000""ZebraTC510K"
Example: "CastlesSaturn1000"
communicationProtocolstring(CommunicationProtocols)

The protocol used by the point of sale device.

Value"HTTP"
Example: "HTTP"
communicationEndpointstring or null(CommunicationEndpoint)

The URL or network endpoint where the point of sale device actively listens for incoming connections and communications from the merchant system.

Example: "http://pos.example.com"
authenticationSettingsobject(AuthenticationSettings)

The authentication settings for a point of sale device.

hostUrlsArray of objects or null(HostUrl)

The endpoint URLs used by the PXP point of sale application

Example: [{"url":"https://transaction.example.com","urlType":"Transaction"}]
logSettingsobject(LogSettings)

The log settings for a point of sale device.

featureSettingsobject(FeatureSettings)

The feature settings for a point of sale device.

storeAndForwardSettingsobject(StoreAndForwardSettings)

The store and forward settings for a point of sale device.

statusstring(Status)

The status of the point of sale device.

Enum"New""Pending""Active""Disabled"
Example: "Active"
createdOnstring(date-time)
Example: "2023-09-01T12:00:00Z"
updatedOnstring or null(date-time)
Example: "2023-09-10T15:00:00Z"
Response
application/json
{
  "site": "SITE-1",
  "serialNumber": "SN1234567890",
  "merchantPointOfSaleId": "POS-12345",
  "pointOfSaleId": 123456789,
  "deviceModel": "CastlesSaturn1000",
  "communicationProtocol": "HTTP",
  "communicationEndpoint": "http://pos.example.com",
  "authenticationSettings": {
    "hmacKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  },
  "hostUrls": [
    { … }
  ],
  "logSettings": {
    "verboseLoggingEnabled": true,
    "maximumLogSize": 10485760,
    "logFileCleanUpDays": 30
  },
  "featureSettings": {
    "statusPacketsEnabled": true,
    "languageSelectionEnabled": true,
    "gratuityEnabled": false,
    "onlinePinEnabled": true,
    "keyedEnabled": false,
    "dccEnabled": false
  },
  "storeAndForwardSettings": {
    "storeAndForwardEnabled": true,
    "transactionAmountThreshold": 10000,
    "throttlingLimit": 100,
    "processInterval": 300,
    "x509PrivateKey": "MIIBVgIBADANBgkqhkiG9w0BAQEFAASC...",
    "x509PublicKey": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...",
    "keyGenerated": "2023-09-01T12:00:00Z"
  },
  "status": "Active",
  "createdOn": "2023-09-01T12:00:00Z",
  "updatedOn": "2023-09-10T15:00:00Z"
}

Delete a POS device

Request

This endpoint deletes a specific point of sale device.

Path
sitestringrequired

The ID of the site where the point of sale is located.

Example: SITE-1
merchantPointOfSaleIdstringrequired

The unique merchant identifier for the point of sale device.

Example: POS-12345
curl -i -X DELETE \
  https://api-services.pxp.io/api/v1/point-of-sales/SITE-1/POS-12345

Responses

Successfully deleted the point of sale device.

Update a POS device

Request

This endpoint updates the details of a specific point of sale device.

Path
sitestringrequired

The ID of the site where the point of sale is located.

Example: SITE-1
merchantPointOfSaleIdstringrequired

The unique merchant identifier for the point of sale device.

Example: POS-12345
Bodyapplication/jsonrequired

Updated configuration details for the point of sale device.

statusstring(Status)

The status of the point of sale device.

Enum"New""Pending""Active""Disabled"
Example: "Active"
sitestring or null

The ID of the site where the point of sale will be deployed.

Example: "SITE-1"
serialNumberstring or null

The serial number of the point of sale device

Example: "SN1234567890"
merchantPointOfSaleIdstring or null

The unique merchant identifier for the point of sale device.

Example: "POS-12345"
deviceModelstring(DeviceModels)

The model of the point of sale device.

Enum"CastlesSaturn1000""ZebraTC510K"
Example: "CastlesSaturn1000"
communicationProtocolstring(CommunicationProtocols)

The protocol used by the point of sale device.

Value"HTTP"
Example: "HTTP"
communicationEndpointstring or null(CommunicationEndpoint)

The URL or network endpoint where the point of sale device actively listens for incoming connections and communications from the merchant system.

Example: "http://pos.example.com"
authenticationSettingsobject(AuthenticationSettings)

The authentication settings for a point of sale device.

hostUrlsArray of objects or null(HostUrl)

The endpoint URLs used by the PXP point of sale application

Example: [{"url":"https://transaction.example.com","urlType":"Transaction"}]
logSettingsobject(LogSettings)

The log settings for a point of sale device.

featureSettingsobject(FeatureSettings)

The feature settings for a point of sale device.

storeAndForwardSettingsobject(StoreAndForwardSettings)

The store and forward settings for a point of sale device.

curl -i -X PUT \
  https://api-services.pxp.io/api/v1/point-of-sales/SITE-1/POS-12345 \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "Active",
    "site": "SITE-1",
    "serialNumber": "SN1234567890",
    "merchantPointOfSaleId": "POS-12345",
    "deviceModel": "CastlesSaturn1000",
    "communicationProtocol": "HTTP",
    "communicationEndpoint": "http://pos.example.com",
    "authenticationSettings": {
      "hmacKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    },
    "hostUrls": [
      {
        "url": "https://transaction.example.com",
        "urlType": "Transaction"
      }
    ],
    "logSettings": {
      "verboseLoggingEnabled": true,
      "maximumLogSize": 10485760,
      "logFileCleanUpDays": 30
    },
    "featureSettings": {
      "statusPacketsEnabled": true,
      "languageSelectionEnabled": true,
      "gratuityEnabled": false,
      "onlinePinEnabled": true,
      "keyedEnabled": false,
      "dccEnabled": false
    },
    "storeAndForwardSettings": {
      "storeAndForwardEnabled": true,
      "transactionAmountThreshold": 10000,
      "throttlingLimit": 100,
      "processInterval": 300,
      "x509PrivateKey": "MIIBVgIBADANBgkqhkiG9w0BAQEFAASC...",
      "x509PublicKey": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...",
      "keyGenerated": "2023-09-01T12:00:00Z"
    }
  }'

Responses

Successfully updated the point of sale device.

Activate a POS device

Request

This endpoint activates a point of sale device using its serial number.

Path
serialNumberstringrequired

The serial number of the point of sale device to activate.

Example: SN1234567890
curl -i -X PUT \
  https://api-services.pxp.io/api/v1/point-of-sales/SN1234567890/activate

Responses

Successfully activated the point of sale device.

Authentication settings

Operations

Feature settings

Operations

General settings

Operations

Log settings

Operations

Store and Forward settings

Operations

URL settings

Operations
©2025 PXP Financial. PXP Financial Registered Office: The Corn Mill - 1 Roydon Road - Stanstead Abbotts - Hertfordshire - SG12 8XL - United Kingdom Phone +44 2038850598. PXP Financial is Authorised By The Financial Conduct Authority And Our Financial Services Register Number is 504318.