{ "openapi": "3.0.3", "info": { "title": "POS service API", "description": "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.", "version": "1.0.0" }, "servers": [ { "url": "https://api-services.pxp.io/api/v1", "description": "Production environment" }, { "url": "https://api-services.test.pxp.io/api/v1", "description": "Sandbox environment" } ], "paths": { "/point-of-sales/{site}": { "post": { "tags": [ "Manage POS devices" ], "x-hideReplay": true, "summary": "Add a POS device", "description": "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.", "operationId": "add-pos-device", "parameters": [ { "name": "site", "in": "path", "required": true, "description": "The ID of the site where the point of sale will be deployed.", "example": "SITE-1", "schema": { "type": "string" } } ], "requestBody": { "description": "Configuration details for the new point of sale device.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePointOfSaleRequest" } } } }, "responses": { "200": { "description": "Successfully initiated the point of sale device.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePointOfSaleResponse" } } } } } } }, "/point-of-sales/{site}/{merchantPointOfSaleId}": { "get": { "tags": [ "Manage POS devices" ], "x-hideReplay": true, "summary": "Retrieve a POS device", "description": "This endpoint retrieves the details of a specific point of sale device by its merchant ID.", "operationId": "retrieve-pos-device", "parameters": [ { "name": "site", "in": "path", "required": true, "example": "SITE-1", "description": "The ID of the site where the point of sale is located.", "schema": { "type": "string" } }, { "name": "merchantPointOfSaleId", "in": "path", "required": true, "example": "POS-12345", "description": "The unique merchant identifier for the point of sale device.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the point of sale device details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPointOfSaleResponse" } } } } } }, "delete": { "tags": [ "Manage POS devices" ], "x-hideReplay": true, "summary": "Delete a POS device", "description": "This endpoint deletes a specific point of sale device.", "operationId": "delete-pos-device", "parameters": [ { "name": "site", "in": "path", "required": true, "example": "SITE-1", "description": "The ID of the site where the point of sale is located.", "schema": { "type": "string" } }, { "name": "merchantPointOfSaleId", "in": "path", "required": true, "example": "POS-12345", "description": "The unique merchant identifier for the point of sale device.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted the point of sale device." } } }, "put": { "tags": [ "Manage POS devices" ], "x-hideReplay": true, "summary": "Update a POS device", "description": "This endpoint updates the details of a specific point of sale device.", "operationId": "update-pos-device", "parameters": [ { "name": "site", "in": "path", "example": "SITE-1", "required": true, "description": "The ID of the site where the point of sale is located.", "schema": { "type": "string" } }, { "name": "merchantPointOfSaleId", "in": "path", "required": true, "example": "POS-12345", "description": "The unique merchant identifier for the point of sale device.", "schema": { "type": "string" } } ], "requestBody": { "description": "Updated configuration details for the point of sale device.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePointOfSaleRequest" } } } }, "responses": { "200": { "description": "Successfully updated the point of sale device." } } } }, "/point-of-sales/{serialNumber}/activate": { "put": { "tags": [ "Manage POS devices" ], "x-hideReplay": true, "summary": "Activate a POS device", "description": "This endpoint activates a point of sale device using its serial number.", "operationId": "activate-pos-device", "parameters": [ { "name": "serialNumber", "in": "path", "required": true, "example": "SN1234567890", "description": "The serial number of the point of sale device to activate.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully activated the point of sale device." } } } }, "/point-of-sales/{ownerType}/{ownerId}/all": { "get": { "tags": [ "Manage POS devices" ], "x-hideReplay": true, "summary": "Retrieve all POS devices", "description": "This endpoint retrieves all point of sale devices for a specific owner (site, merchant, or merchant group).", "operationId": "retrieve-all-pos-devices", "parameters": [ { "name": "ownerType", "in": "path", "required": true, "description": "The type of owner for which to retrieve point of sale devices.", "schema": { "type": "string", "enum": [ "SITE", "MERCHANT", "MERCHANTGROUP" ] }, "example": "SITE" }, { "name": "ownerId", "in": "path", "required": true, "description": "The unique identifier of the owner (site ID, merchant ID, or merchant group ID).", "schema": { "type": "string" }, "example": "SITE-1" } ], "responses": { "200": { "description": "Successfully retrieved the list of point of sale devices.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetPointOfSaleResponse" } } } } } } } }, "/point-of-sales/{pointOfSaleId}/authentication-settings": { "post": { "tags": [ "Authentication settings" ], "x-hideReplay": true, "summary": "Create authentication settings", "description": "This endpoint creates authentication settings for a specific point of sale device.", "operationId": "create-authentication-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The authentication settings to apply to the point of sale device.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuthenticationSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully created the authentication settings." } } }, "get": { "tags": [ "Authentication settings" ], "x-hideReplay": true, "summary": "Get authentication settings", "description": "This endpoint retrieves the authentication settings for a specific point of sale device.", "operationId": "get-authentication-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "description": "The unique system identifier for the point of sale device.", "example": 123456789, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Successfully retrieved the authentication settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAuthenticationSettingsResponse" } } } } } }, "put": { "tags": [ "Authentication settings" ], "x-hideReplay": true, "summary": "Update authentication settings", "description": "This endpoint updates the authentication settings for a specific point of sale device.", "operationId": "update-authentication-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "description": "The unique system identifier for the point of sale device.", "example": 12345789, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The updated authentication settings.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAuthenticationSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully updated the authentication settings." } } } }, "/point-of-sales/{pointOfSaleId}/feature-settings": { "post": { "tags": [ "Feature settings" ], "x-hideReplay": true, "summary": "Create feature settings", "description": "This endpoint creates feature settings for a specific point of sale device.", "operationId": "create-feature-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "description": "The unique system identifier for the point of sale device.", "example": 123456789, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The feature settings to apply to the point of sale device.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFeatureSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully created the feature settings." } } }, "get": { "tags": [ "Feature settings" ], "x-hideReplay": true, "summary": "Get feature settings", "description": "This endpoint retrieves the feature settings for a specific point of sale device.", "operationId": "get-feature-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Successfully retrieved the feature settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFeatureSettingsResponse" } } } } } }, "put": { "tags": [ "Feature settings" ], "x-hideReplay": true, "summary": "Update feature settings", "description": "This endpoint updates the feature settings for a specific point of sale device.", "operationId": "update-feature-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "description": "The unique system identifier for the point of sale device.", "example": 123456789, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The updated feature settings.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFeatureSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully updated the feature settings." } } } }, "/point-of-sales/{site}/general-settings": { "post": { "tags": [ "General settings" ], "x-hideReplay": true, "summary": "Create general settings", "description": "This endpoint creates general settings for a specific site.", "operationId": "create-general-settings", "parameters": [ { "name": "site", "in": "path", "example": "SITE-1", "required": true, "description": "The ID of the site where the settings will be applied.", "schema": { "type": "string" } } ], "requestBody": { "description": "The general settings to apply to the site.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGeneralSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully created the general settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGeneralSettingsResponse" } } } } } } }, "/point-of-sales/{pointOfSaleId}/general-settings": { "get": { "tags": [ "General settings" ], "x-hideReplay": true, "summary": "Get general settings", "description": "This endpoint retrieves the general settings for a specific point of sale device.", "operationId": "get-general-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "description": "The unique system identifier for the point of sale device.", "example": 123456789, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Successfully retrieved the general settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGeneralSettingsResponse" } } } } } }, "put": { "tags": [ "General settings" ], "x-hideReplay": true, "summary": "Update general settings", "description": "This endpoint updates the general settings for a specific point of sale device.", "operationId": "update-general-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "description": "The unique system identifier for the point of sale device.", "example": 123456789, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The updated general settings.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGeneralSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully updated the general settings." } } } }, "/point-of-sales/{pointOfSaleId}/log-settings": { "post": { "tags": [ "Log settings" ], "x-hideReplay": true, "summary": "Create log settings", "description": "This endpoint creates log settings for a specific point of sale device.", "operationId": "create-log-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The log settings to apply to the point of sale device.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLogSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully created the log settings." } } }, "get": { "tags": [ "Log settings" ], "x-hideReplay": true, "summary": "Get log settings", "description": "This endpoint retrieves the log settings for a specific point of sale device.", "operationId": "get-log-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Successfully retrieved the log settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLogSettingsResponse" } } } } } }, "put": { "tags": [ "Log settings" ], "x-hideReplay": true, "summary": "Update log settings", "description": "This endpoint updates the log settings for a specific point of sale device.", "operationId": "update-log-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The updated log settings.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLogSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully updated the log settings." } } } }, "/point-of-sales/{pointOfSaleId}/store-and-forward-settings": { "post": { "tags": [ "Store and Forward settings" ], "x-hideReplay": true, "summary": "Create Store and Forward settings", "description": "This endpoint creates store and forward settings for a specific point of sale device.", "operationId": "create-store-and-forward-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "description": "The unique system identifier for the point of sale device.", "example": 123456789, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The store and forward settings to apply to the point of sale device.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStoreAndForwardSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully created the store and forward settings." } } }, "get": { "tags": [ "Store and Forward settings" ], "x-hideReplay": true, "summary": "Get Store and Forward settings", "description": "This endpoint retrieves the store and forward settings for a specific point of sale device.", "operationId": "get-store-and-forward-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Successfully retrieved the store and forward settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStoreAndForwardSettingsResponse" } } } } } }, "put": { "tags": [ "Store and Forward settings" ], "x-hideReplay": true, "summary": "Update Store and Forward settings", "description": "This endpoint updates the store and forward settings for a specific point of sale device.", "operationId": "update-store-and-forward-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The updated store and forward settings.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStoreAndForwardSettingsRequest" } } } }, "responses": { "200": { "description": "Successfully updated the store and forward settings." } } } }, "/point-of-sales/{pointOfSaleId}/host-url-settings": { "post": { "tags": [ "URL settings" ], "x-hideReplay": true, "summary": "Create host URL settings", "description": "This endpoint creates host URL settings for a specific point of sale device.", "operationId": "create-host-url-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "The host URL settings to apply to the point of sale device.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHostUrlRequest" } } } }, "responses": { "200": { "description": "Successfully created the host URL settings." } } } }, "/point-of-sales/{pointOfSaleId}/{urlType}/host-url-settings": { "get": { "tags": [ "URL settings" ], "x-hideReplay": true, "summary": "Get host URL settings", "description": "This endpoint retrieves specific host URL settings for a point of sale device by URL type.", "operationId": "get-host-url-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123465789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } }, { "name": "urlType", "in": "path", "required": true, "description": "The type of URL (e.g., Transaction, StoreAndForward, InStoreNotification).", "schema": { "$ref": "#/components/schemas/HostUrlTypes" } } ], "responses": { "200": { "description": "Successfully retrieved the host URL settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetHostUrlResponse" } } } } } }, "put": { "tags": [ "URL settings" ], "x-hideReplay": true, "summary": "Update host URL settings", "description": "This endpoint updates specific host URL settings for a point of sale device by URL type.", "operationId": "update-host-url-settings", "parameters": [ { "name": "pointOfSaleId", "in": "path", "required": true, "example": 123456789, "description": "The unique system identifier for the point of sale device.", "schema": { "type": "integer", "format": "int64" } }, { "name": "urlType", "in": "path", "required": true, "description": "The type of URL (e.g., Transaction, StoreAndForward, InStoreNotification).", "schema": { "$ref": "#/components/schemas/HostUrlTypes" } } ], "requestBody": { "description": "The updated host URL settings.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHostUrlRequest" } } } }, "responses": { "200": { "description": "Successfully updated the host URL settings." } } } } }, "components": { "schemas": { "AuthenticationSettings": { "type": "object", "required": [ "hmacKey" ], "description": "The authentication settings for a point of sale device.", "properties": { "hmacKey": { "type": "string", "description": "The single hmac key used in association with the point of sale device to authenticate.", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" } } }, "CreateAuthenticationSettingsRequest": { "type": "object", "required": [ "hmacKey" ], "description": "The request to create authentication settings for a point of sale device.", "properties": { "hmacKey": { "type": "string", "description": "The single hmac key used in association with the point of sale device to authenticate.", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" } } }, "CreateFeatureSettingsRequest": { "type": "object", "description": "The request to create feature settings for a point of sale device.", "properties": { "merchantPointOfSaleId": { "type": "string", "nullable": true, "description": "The unique merchant identifier for the point of sale device.", "example": "POS-12345" }, "statusPacketsEnabled": { "type": "boolean", "nullable": true, "description": "Indicates whether status packets, which provide real-time updates about the device's status, are enabled for the point of sale device.", "example": true }, "languageSelectionEnabled": { "type": "boolean", "nullable": true, "description": "Specifies whether the language selection feature is enabled, allowing users to choose their preferred language during transactions.", "example": true }, "gratuityEnabled": { "type": "boolean", "nullable": true, "description": "Indicates whether the gratuity (tip) feature is enabled, allowing customers to add a tip to their transactions.", "example": false }, "onlinePinEnabled": { "type": "boolean", "nullable": true, "description": "Specifies whether the online PIN feature is enabled, requiring customers to enter their PIN for card transactions.", "example": true }, "keyedEnabled": { "type": "boolean", "nullable": true, "description": "Indicates whether the keyed entry feature is enabled, allowing manual entry of card details for transactions.", "example": false } } }, "CreateGeneralSettingsRequest": { "type": "object", "description": "The request to create general settings for a site.", "required": [ "serialNumber", "deviceModel", "communicationProtocol" ], "properties": { "serialNumber": { "type": "string", "description": "The serial number of the point of sale device to activate.", "example": "SN1234567890" }, "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "nullable": true, "example": "POS-12345" }, "deviceModel": { "$ref": "#/components/schemas/DeviceModels" }, "communicationProtocol": { "$ref": "#/components/schemas/CommunicationProtocols" }, "communicationEndpoint": { "$ref": "#/components/schemas/CommunicationEndpoint" } } }, "CreateGeneralSettingsResponse": { "type": "object", "description": "The response after creating general settings for a site.", "properties": { "status": { "$ref": "#/components/schemas/Status" }, "site": { "type": "string", "description": "The ID of the site where the point of sale will be deployed.", "example": "SITE-1" }, "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "example": "POS-12345" }, "pointOfSaleId": { "description": "The unique system identifier for the point of sale device.", "type": "integer", "format": "int64", "example": 123456789 } } }, "CreateHostUrlRequest": { "type": "object", "description": "The request to create a host URL for a point of sale device.", "properties": { "url": { "type": "string", "nullable": true, "example": "https://transaction.example.com" }, "urlType": { "$ref": "#/components/schemas/HostUrlTypes" } } }, "CreateLogSettingsRequest": { "type": "object", "description": "The request to create log settings for a point of sale device.", "properties": { "verboseLoggingEnabled": { "type": "boolean", "description": "Indicates whether verbose logging is enabled for the point of sale device. When enabled, more detailed logs are generated, which can be useful for debugging and troubleshooting.", "nullable": true, "example": true }, "maximumLogSize": { "type": "integer", "format": "int32", "description": "The maximum size of the log file in bytes. Once the log file reaches this size, older log entries may be removed or archived to prevent exceeding the size limit.", "example": 10485760, "nullable": true }, "logFileCleanUpDays": { "type": "integer", "format": "int32", "nullable": true, "description": "The number of days after which log files are cleaned up or archived. This helps manage storage by removing or archiving logs that are older than the specified number of days.", "example": 30 } } }, "CreatePointOfSaleRequest": { "type": "object", "description": "The request to create a new point of sale device.", "required": [ "serialNumber", "merchantPointOfSaleId", "deviceModel", "communicationProtocol", "authenticationSettings" ], "properties": { "serialNumber": { "type": "string", "description": "The serial number of the point of sale device", "example": "SN1234567890" }, "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "example": "POS-12345" }, "deviceModel": { "$ref": "#/components/schemas/DeviceModels" }, "communicationProtocol": { "$ref": "#/components/schemas/CommunicationProtocols" }, "communicationEndpoint": { "$ref": "#/components/schemas/CommunicationEndpoint" }, "commercialModel": { "$ref": "#/components/schemas/CommercialModel", "nullable": true, "description": "The commercial model for the point of sale device pricing." }, "authenticationSettings": { "$ref": "#/components/schemas/AuthenticationSettings" }, "hostUrls": { "type": "array", "description": "The endpoint URLs used by the PXP point of sale application.", "items": { "$ref": "#/components/schemas/HostUrl" }, "nullable": true, "example": [ { "url": "https://transaction.example.com", "urlType": "Transaction" } ] }, "logSettings": { "$ref": "#/components/schemas/LogSettings" }, "featureSettings": { "$ref": "#/components/schemas/FeatureSettings" }, "storeAndForwardSettings": { "$ref": "#/components/schemas/StoreAndForwardSettings" } } }, "CreatePointOfSaleResponse": { "type": "object", "description": "The response after creating a new point of sale device.", "properties": { "status": { "$ref": "#/components/schemas/Status" }, "site": { "type": "string", "description": "The ID of the site where the point of sale will be deployed.", "example": "SITE-1" }, "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "example": "POS-12345" }, "pointOfSaleId": { "type": "integer", "description": "The unique system identifier for the point of sale device.", "format": "int64", "example": 123456789 } } }, "CreateStoreAndForwardSettingsRequest": { "type": "object", "description": "The request to create store and forward settings for a point of sale device.", "properties": { "storeAndForwardEnabled": { "type": "boolean", "description": "Specifies whether the store and forward feature should be enabled for the point of sale device. This feature allows transactions to be temporarily stored locally when there is no network connectivity and then forwarded to the server once connectivity is restored.", "nullable": true, "example": true }, "transactionAmountThreshold": { "type": "integer", "format": "int32", "description": "Defines the maximum transaction amount (in the smallest currency unit, such as cents) that can be processed using the store and forward feature. Transactions that exceed this threshold will not be stored for later forwarding.", "nullable": true, "example": 10000 }, "throttlingLimit": { "type": "integer", "format": "int32", "description": "Sets the maximum number of transactions that can be processed within a specific time frame when the store and forward feature is enabled. This helps to manage the flow of transactions once network connectivity is restored.", "nullable": true, "example": 100 }, "processInterval": { "type": "integer", "format": "int32", "description": "Specifies the time interval (in seconds) between attempts to process and forward stored transactions once network connectivity is available.", "nullable": true, "example": 300 }, "x509PrivateKey": { "type": "string", "nullable": true, "description": "The private key used for encrypting stored transaction data. This key is part of the X.509 certificate standard, which is used to ensure secure communications.", "example": "MIIBVgIBADANBgkqhkiG9w0BAQEFAASC..." }, "x509PublicKey": { "type": "string", "nullable": true, "description": "The public key associated with the private key, used in conjunction with the X.509 certificate for encryption and secure communication.", "example": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE..." }, "keyGenerated": { "type": "string", "format": "date-time", "nullable": true, "description": "The date and time when the encryption keys were generated, formatted according to the ISO 8601 standard.", "example": "2023-09-01T12:00:00Z" } } }, "CommercialModel": { "enum": [ "Onetime", "Recurring", "Financed", "Both" ], "type": "string", "description": "The commercial model for the point of sale device pricing.", "example": "Onetime" }, "DeviceModels": { "enum": [ "CastlesSaturn1000", "ZebraTC510K" ], "type": "string", "description": "The model of the point of sale device.", "example": "CastlesSaturn1000" }, "FeatureSettings": { "type": "object", "description": "The feature settings for a point of sale device.", "properties": { "statusPacketsEnabled": { "type": "boolean", "description": "Indicates whether status packets, which provide real-time updates about the device's status, are enabled for the point of sale device.", "example": true, "nullable": true }, "languageSelectionEnabled": { "type": "boolean", "description": "Whether the language selection feature is enabled, allowing users to choose their preferred language during transactions.", "example": true, "nullable": true }, "gratuityEnabled": { "type": "boolean", "description": "Whether the gratuity (tip) feature is enabled, allowing customers to add a tip to their transactions.", "example": false, "nullable": true }, "onlinePinEnabled": { "type": "boolean", "description": "Whether the online PIN feature is enabled, requiring customers to enter their PIN for card transactions.", "example": true, "nullable": true }, "keyedEnabled": { "type": "boolean", "description": "Whether the keyed entry feature is enabled, allowing manual entry of card details for transactions.", "example": false, "nullable": true }, "dccEnabled": { "type": "boolean", "description": "Whether the Dynamic Currency Conversion (DCC) feature is enabled, allowing customers to pay in their local card currency.", "example": false, "nullable": true } } }, "GetAuthenticationSettingsResponse": { "type": "object", "description": "The response containing authentication settings for a point of sale device.", "properties": { "hmacKey": { "type": "string", "nullable": true, "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" } } }, "GetFeatureSettingsResponse": { "type": "object", "description": "The response containing feature settings for a point of sale device.", "properties": { "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "example": "POS-12345" }, "statusPacketsEnabled": { "type": "boolean", "description": "Indicates whether status packets, which provide real-time updates about the device's status, are enabled for the point of sale device." }, "languageSelectionEnabled": { "type": "boolean", "description": "Specifies whether the language selection feature is enabled, allowing users to choose their preferred language during transactions." }, "gratuityEnabled": { "type": "boolean", "description": "Indicates whether the gratuity (tip) feature is enabled, allowing customers to add a tip to their transactions." }, "onlinePinEnabled": { "type": "boolean", "description": "Specifies whether the online PIN feature is enabled, requiring customers to enter their PIN for card transactions." }, "keyedEnabled": { "type": "boolean", "description": "Indicates whether the keyed entry feature is enabled, allowing manual entry of card details for transactions." } } }, "GetGeneralSettingsResponse": { "type": "object", "description": "The response containing general settings for a point of sale device.", "properties": { "site": { "type": "string", "description": "The ID of the site where the point of sale will be deployed.", "example": "SITE-1" }, "serialNumber": { "type": "string", "description": "The serial number of the point of sale device", "example": "SN1234567890" }, "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "example": "POS-12345" }, "pointOfSaleId": { "description": "The unique system identifier for the point of sale device.", "type": "integer", "format": "int64", "example": 123456789 }, "deviceModel": { "$ref": "#/components/schemas/DeviceModels" }, "communicationProtocol": { "$ref": "#/components/schemas/CommunicationProtocols" }, "communicationEndpoint": { "description": "The URL or network endpoint where the point of sale device actively listens for incoming connections and communications from the merchant system.", "type": "string", "example": "http://pos.example.com" }, "commercialModel": { "$ref": "#/components/schemas/CommercialModel", "nullable": true, "description": "The commercial model for the point of sale device pricing." }, "inUse": { "type": "boolean", "description": "Indicates whether the point of sale device is currently in use.", "example": false }, "status": { "$ref": "#/components/schemas/Status" }, "createdOn": { "type": "string", "format": "date-time", "example": "2023-09-01T12:00:00Z" }, "updatedOn": { "type": "string", "format": "date-time", "nullable": true, "example": "2023-09-10T15:00:00Z" } } }, "GetHostUrlResponse": { "type": "object", "description": "The response containing host URL settings for a point of sale device.", "properties": { "url": { "type": "string", "nullable": true, "example": "https://transaction.example.com" }, "urlType": { "$ref": "#/components/schemas/HostUrlTypes" } } }, "GetLogSettingsResponse": { "type": "object", "description": "The response containing log settings for a point of sale device.", "properties": { "verboseLoggingEnabled": { "type": "boolean", "description": "Indicates whether verbose logging is enabled for the point of sale device. When enabled, more detailed logs are generated, which can be useful for debugging and troubleshooting.", "example": true }, "maximumLogSize": { "type": "integer", "format": "int32", "description": "The maximum size of the log file in bytes. Once the log file reaches this size, older log entries may be removed or archived to prevent exceeding the size limit.", "example": 10485760 }, "logFileCleanUpDays": { "type": "integer", "format": "int32", "description": "The number of days after which log files are cleaned up or archived. This helps manage storage by removing or archiving logs that are older than the specified number of days.", "example": 30 } } }, "GetPointOfSaleResponse": { "type": "object", "description": "The response containing point of sale device details.", "properties": { "site": { "type": "string", "description": "The ID of the site where the point of sale will be deployed.", "example": "SITE-1" }, "serialNumber": { "type": "string", "description": "The serial number of the point of sale device", "example": "SN1234567890" }, "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "example": "POS-12345" }, "pointOfSaleId": { "description": "The unique system identifier for the point of sale device.", "type": "integer", "format": "int64", "example": 123456789 }, "deviceModel": { "$ref": "#/components/schemas/DeviceModels" }, "communicationProtocol": { "$ref": "#/components/schemas/CommunicationProtocols" }, "communicationEndpoint": { "$ref": "#/components/schemas/CommunicationEndpoint" }, "commercialModel": { "$ref": "#/components/schemas/CommercialModel", "nullable": true, "description": "The commercial model for the point of sale device pricing." }, "authenticationSettings": { "$ref": "#/components/schemas/AuthenticationSettings" }, "hostUrls": { "type": "array", "description": "The endpoint URLs used by the PXP point of sale application", "items": { "$ref": "#/components/schemas/HostUrl" }, "nullable": true, "example": [ { "url": "https://transaction.example.com", "urlType": "Transaction" } ] }, "logSettings": { "$ref": "#/components/schemas/LogSettings" }, "featureSettings": { "$ref": "#/components/schemas/FeatureSettings" }, "storeAndForwardSettings": { "$ref": "#/components/schemas/StoreAndForwardSettings" }, "status": { "$ref": "#/components/schemas/Status" }, "createdOn": { "type": "string", "format": "date-time", "example": "2023-09-01T12:00:00Z" }, "updatedOn": { "type": "string", "format": "date-time", "nullable": true, "example": "2023-09-10T15:00:00Z" } } }, "GetStoreAndForwardSettingsResponse": { "type": "object", "description": "The response containing store and forward settings for a point of sale device.", "properties": { "storeAndForwardEnabled": { "type": "boolean", "description": "Indicates whether the store and forward feature is enabled for the point of sale device. This feature allows transactions to be temporarily stored locally when there is no network connectivity and forwarded to the server once connectivity is restored.", "example": true }, "transactionAmountThreshold": { "type": "integer", "format": "int32", "description": "Specifies the maximum transaction amount (in the smallest currency unit, such as cents) that can be processed using the store and forward feature. Transactions exceeding this amount will not be stored for later forwarding.", "example": 10000 }, "throttlingLimit": { "type": "integer", "format": "int32", "description": "Defines the maximum number of transactions that can be processed in a given time frame when the store and forward feature is enabled. This helps to manage the flow of transactions when connectivity is restored.", "example": 100 }, "processInterval": { "type": "integer", "format": "int32", "description": "Indicates the interval (in seconds) between attempts to process and forward stored transactions once network connectivity is available.", "example": 300 }, "x509PrivateKey": { "type": "string", "nullable": true, "description": "The private key used for encryption of stored transaction data. This key is part of the X.509 certificate standard used for secure communications.", "example": "MIIBVgIBADANBgkqhkiG9w0BAQEFAASC..." }, "x509PublicKey": { "type": "string", "nullable": true, "description": "The public key associated with the private key, used in the X.509 certificate for encryption and secure communication.", "example": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE..." }, "keyGenerated": { "type": "string", "format": "date-time", "description": "The date and time when the encryption keys were generated, formatted in ISO 8601.", "example": "2023-09-01T12:00:00Z" } } }, "HostUrl": { "type": "object", "description": "The host URL settings for a point of sale device.", "properties": { "url": { "type": "string", "nullable": true, "example": "https://transaction.example.com" }, "urlType": { "$ref": "#/components/schemas/HostUrlTypes" } } }, "HostUrlTypes": { "enum": [ "Transaction", "StoreAndForward", "InStoreNotification", "DCC" ], "type": "string", "description": "The type of URL.", "example": "Transaction" }, "CommunicationProtocols": { "enum": [ "HTTP" ], "type": "string", "description": "The protocol used by the point of sale device.", "example": "HTTP" }, "CommunicationEndpoint": { "type": "string", "nullable": true, "description": "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" }, "LogSettings": { "type": "object", "description": "The log settings for a point of sale device.", "properties": { "verboseLoggingEnabled": { "type": "boolean", "nullable": true, "description": "Indicates whether verbose logging is enabled for the point of sale device. When enabled, more detailed logs are generated, which can be useful for debugging and troubleshooting.", "example": true }, "maximumLogSize": { "type": "integer", "format": "int32", "nullable": true, "description": "The maximum size of the log file in bytes. Once the log file reaches this size, older log entries may be removed or archived to prevent exceeding the size limit.", "example": 10485760 }, "logFileCleanUpDays": { "type": "integer", "format": "int32", "nullable": true, "description": "The number of days after which log files are cleaned up or archived. This helps manage storage by removing or archiving logs that are older than the specified number of days.", "example": 30 } } }, "Status": { "enum": [ "New", "Pending", "Active", "Disabled" ], "type": "string", "description": "The status of the point of sale device.", "example": "Active" }, "StoreAndForwardSettings": { "type": "object", "description": "The store and forward settings for a point of sale device.", "properties": { "storeAndForwardEnabled": { "type": "boolean", "description": "Indicates whether the store and forward feature is enabled for the point of sale device. This feature allows transactions to be stored locally when there is no network connectivity and then forwarded to the server once connectivity is restored.", "example": true, "nullable": true }, "transactionAmountThreshold": { "type": "integer", "format": "int32", "description": "The maximum transaction amount, in the smallest currency unit (such as cents), that can be processed using the store and forward feature. Transactions exceeding this threshold will not be stored for later forwarding.", "example": 10000, "nullable": true }, "throttlingLimit": { "type": "integer", "format": "int32", "description": "The maximum number of transactions that can be processed within a specified time frame when the store and forward feature is enabled. This setting helps control the flow of transactions once network connectivity is restored.", "example": 100, "nullable": true }, "processInterval": { "type": "integer", "format": "int32", "description": "The time interval, in seconds, between attempts to process and forward stored transactions once network connectivity is available.", "example": 300, "nullable": true }, "x509PrivateKey": { "type": "string", "nullable": true, "description": "The private key used for encrypting stored transaction data. This key is part of the X.509 certificate standard, which is used to ensure secure communications.", "example": "MIIBVgIBADANBgkqhkiG9w0BAQEFAASC..." }, "x509PublicKey": { "type": "string", "nullable": true, "description": "The public key associated with the private key, used in conjunction with the X.509 certificate for encryption and secure communication.", "example": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE..." }, "keyGenerated": { "type": "string", "format": "date-time", "description": "The date and time when the encryption keys were generated, formatted according to the ISO 8601 standard.", "example": "2023-09-01T12:00:00Z", "nullable": true } } }, "UpdateAuthenticationSettingsRequest": { "type": "object", "description": "The request to update authentication settings for a point of sale device.", "properties": { "hmacKey": { "type": "string", "nullable": true, "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" } } }, "UpdateFeatureSettingsRequest": { "type": "object", "description": "The request to update feature settings for a point of sale device.", "properties": { "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "nullable": true, "example": "POS-12345" }, "statusPacketsEnabled": { "type": "boolean", "description": "Indicates whether status packets, which provide real-time updates about the device's status, are enabled for the point of sale device.", "example": true, "nullable": true }, "languageSelectionEnabled": { "type": "boolean", "description": "Specifies whether the language selection feature is enabled, allowing users to choose their preferred language during transactions.", "example": true, "nullable": true }, "gratuityEnabled": { "type": "boolean", "description": "Indicates whether the gratuity (tip) feature is enabled, allowing customers to add a tip to their transactions.", "example": false, "nullable": true }, "onlinePinEnabled": { "type": "boolean", "description": "Specifies whether the online PIN feature is enabled, requiring customers to enter their PIN for card transactions.", "example": true, "nullable": true }, "keyedEnabled": { "type": "boolean", "description": "Indicates whether the keyed entry feature is enabled, allowing manual entry of card details for transactions.", "example": false, "nullable": true } } }, "UpdateGeneralSettingsRequest": { "type": "object", "description": "The request to update general settings for a point of sale device.", "properties": { "site": { "type": "string", "description": "The ID of the site where the point of sale will be deployed.", "example": "SITE-1", "nullable": true }, "serialNumber": { "type": "string", "description": "The serial number of the point of sale device", "example": "SN1234567890", "nullable": true }, "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "nullable": true, "example": "POS-12345" }, "deviceModel": { "$ref": "#/components/schemas/DeviceModels" }, "communicationProtocol": { "$ref": "#/components/schemas/CommunicationProtocols" }, "communicationEndpoint": { "$ref": "#/components/schemas/CommunicationEndpoint" }, "status": { "$ref": "#/components/schemas/Status" } } }, "UpdateHostUrlRequest": { "type": "object", "description": "The request to update host URL settings for a point of sale device.", "properties": { "url": { "type": "string", "nullable": true, "example": "https://transaction.example.com" } } }, "UpdateLogSettingsRequest": { "type": "object", "description": "The request to update log settings for a point of sale device.", "properties": { "verboseLoggingEnabled": { "type": "boolean", "description": "Indicates whether verbose logging is enabled for the point of sale device. When enabled, more detailed logs are generated, which can be useful for debugging and troubleshooting.", "example": true, "nullable": true }, "maximumLogSize": { "type": "integer", "format": "int32", "description": "The maximum size of the log file in bytes. Once the log file reaches this size, older log entries may be removed or archived to prevent exceeding the size limit.", "example": 10485760, "nullable": true }, "logFileCleanUpDays": { "type": "integer", "format": "int32", "description": "The number of days after which log files are cleaned up or archived. This helps manage storage by removing or archiving logs that are older than the specified number of days.", "example": 30, "nullable": true } } }, "UpdatePointOfSaleRequest": { "type": "object", "description": "The request to update a point of sale device's details.", "properties": { "status": { "$ref": "#/components/schemas/Status" }, "site": { "type": "string", "description": "The ID of the site where the point of sale will be deployed.", "example": "SITE-1", "nullable": true }, "serialNumber": { "type": "string", "description": "The serial number of the point of sale device", "example": "SN1234567890", "nullable": true }, "merchantPointOfSaleId": { "type": "string", "description": "The unique merchant identifier for the point of sale device.", "nullable": true, "example": "POS-12345" }, "deviceModel": { "$ref": "#/components/schemas/DeviceModels" }, "communicationProtocol": { "$ref": "#/components/schemas/CommunicationProtocols" }, "communicationEndpoint": { "$ref": "#/components/schemas/CommunicationEndpoint" }, "authenticationSettings": { "$ref": "#/components/schemas/AuthenticationSettings" }, "hostUrls": { "type": "array", "description": "The endpoint URLs used by the PXP point of sale application", "items": { "$ref": "#/components/schemas/HostUrl" }, "nullable": true, "example": [ { "url": "https://transaction.example.com", "urlType": "Transaction" } ] }, "logSettings": { "$ref": "#/components/schemas/LogSettings" }, "featureSettings": { "$ref": "#/components/schemas/FeatureSettings" }, "storeAndForwardSettings": { "$ref": "#/components/schemas/StoreAndForwardSettings" } } }, "UpdateStoreAndForwardSettingsRequest": { "type": "object", "description": "The request to update store and forward settings for a point of sale device.", "properties": { "storeAndForwardEnabled": { "type": "boolean", "description": "Specifies whether the store and forward feature should remain enabled or be disabled for the point of sale device. This feature allows transactions to be stored locally when there is no network connectivity and then forwarded to the server once connectivity is restored.", "example": true, "nullable": true }, "transactionAmountThreshold": { "type": "integer", "format": "int32", "description": "Defines the maximum transaction amount (in the smallest currency unit, such as cents) that can be processed using the store and forward feature. Transactions exceeding this amount will not be stored for later forwarding.", "example": 10000, "nullable": true }, "throttlingLimit": { "type": "integer", "format": "int32", "description": "Sets the maximum number of transactions that can be processed within a specific time frame when the store and forward feature is enabled. This helps to control the flow of transactions once network connectivity is restored.", "example": 100, "nullable": true }, "processInterval": { "type": "integer", "format": "int32", "description": "Specifies the time interval (in seconds) between attempts to process and forward stored transactions once network connectivity is available.", "example": 300, "nullable": true }, "x509PrivateKey": { "type": "string", "nullable": true, "description": "The private key used for encrypting stored transaction data. This key is part of the X.509 certificate standard, which is used to ensure secure communications.", "example": "MIIBVgIBADANBgkqhkiG9w0BAQEFAASC..." }, "x509PublicKey": { "type": "string", "nullable": true, "description": "The public key associated with the private key, used in conjunction with the X.509 certificate for encryption and secure communication.", "example": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE..." }, "keyGenerated": { "type": "string", "format": "date-time", "description": "The date and time when the encryption keys were generated, formatted according to the ISO 8601 standard.", "example": "2023-09-01T12:00:00Z", "nullable": true } } } } } }