{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","coming-soon","admonition"]},"type":"markdown"},"seo":{"title":"How it works","description":"Transform your commerce with PXP's unified platform—seamless payments, real-time insights, and global growth in one powerful integration.","lang":"en-UK","siteUrl":"https://developer.pxp.io"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"how-it-works","__idx":0},"children":["How it works"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn how cloud invocation reaches a POS+ device from a cloud ePOS or Oracle Opera Cloud."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cloud invocation lets your back-office or cloud POS call a payment terminal without a local device IP connection. Your system sends the request to PXP over the internet. Unity routes it to the POS+ device at the merchant site through the same POS Hub and device cloud connectivity used across cloud POS+ offerings."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use cloud invocation when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your ePOS or PMS runs in the cloud and can't (or shouldn't) open a direct network path to each terminal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Terminals sit on a store or hotel LAN that isn't reachable from your central application."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want one Unity-hosted path to POS+ devices across sites, instead of managing per-site local integrations."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cloud invocation is aimed at cloud ePOS providers, hospitality and retail platforms, and merchants whose payment journey starts in a cloud application rather than on a device-local merchant app."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"two-ways-to-invoke-a-device","__idx":2},"children":["Two ways to invoke a device"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We support two entry points into the same cloud invocation infrastructure:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PXP cloud device API"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Oracle Opera Cloud ",{"$$mdtype":"Tag","name":"ComingSoon","attributes":{"noSpace":false},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both can drive card-present payments on a POS device. They differ in who owns the API your application calls and how you authenticate."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pxp-cloud-device-api","__idx":3},"children":["PXP cloud device API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the Unity Gateway cloud device REST API with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PXP-POS"]}," HMAC authentication. The request and response shapes match POS+ card flows (intents, amounts, modifications, card-on-file fields), with cloud-specific paths under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/cloud-device/{merchantPointOfSaleId}/…"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Typical use cases:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A cloud ePOS or middleware you control, integrating directly with PXP."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Multi-site retail or hospitality platforms that already use Unity and want terminal invocation without a local POS+ LAN client."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom or third-party systems that prefer a PXP REST API over an Oracle payment interface."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/get-started"},"children":["Get started"]}," to learn about credentials, HMAC signing, and the initiate and modify endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"oracle-opera-cloud","__idx":4},"children":["Oracle Opera Cloud"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hotels running Oracle Opera Cloud start payments from the Opera workstation (for example, pay at reception). The request travels from Opera Cloud through OPI Cloud into PXP's Oracle OPI integration, which then invokes the POS+ device over the same cloud path. Authentication uses Oracle's mTLS or OPI Cloud model rather than PXP-POS HMAC on your side."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Typical use cases:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Opera Cloud hotels that need card-present payments at reception without a local link from the workstation to the terminal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Hotel stay flows that need pre-authorisation, incremental top-up, and completion, plus card-not-present follow-ups (tokenised MITs) handled by Unity without sending those steps to the device."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Merchants migrating from on-premise Opera or ANYpay POS to Opera Cloud."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Opera Cloud configuration and supported features are covered in the Oracle Opera section (coming soon). That offering uses the same underlying cloud invocation services as the PXP API; only the entry point differs."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rest of this page describes the PXP cloud device API only: how requests are shaped and which intents and modifications you use. For Oracle Opera Cloud setup and what that integration supports, see the Oracle Opera guides when they are published."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":5},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete these steps before you send cloud device requests:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/manage-devices#add-a-device"},"children":["Add and activate the device"]}," in the Unity Portal with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Communication protocol"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cloud"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Adaptor mode"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PXP"]},", and note its POS ID (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantPointOfSaleId"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/configure-settings"},"children":["Configure device settings"]}," for anything your flow needs (for example status packets, DCC, or gratuity and service charges)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Follow ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/get-started"},"children":["Get started"]}," to authenticate with PXP-POS HMAC."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sending-a-request-pxp-cloud-device-api","__idx":6},"children":["Sending a request (PXP cloud device API)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To initiate a transaction, call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/cloud-device/{merchantPointOfSaleId}/transactions"]}," and provide the amount, currency, and transaction method. The transaction method is made up of three elements:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["entry type"]},", which describes the origin of the transaction. For cloud device card-present flows this is typically ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Instore"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Moto"]}," where keyed / card-on-file rules require it)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["funding type"]},", which describes how the transaction is funded. For these flows this is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Card"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["intent"]},", which describes the purpose of the transaction and the money flow. Each intent dictates a specific flow and which modifications you can run later."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unity authenticates the call with your PXP-POS HMAC signature, then delivers the payment journey to the device identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantPointOfSaleId"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pointOfInteraction.pointOfSaleId"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"intents","__idx":7},"children":["Intents"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you initiate a cloud device transaction, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent"]}," to describe the purpose of the payment."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Intent"},"children":["Intent"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorisation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reserve funds on the customer's card. Capture, increment, or void the authorisation later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EstimatedAuthorisation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reserve funds for an estimated amount, such as a hotel stay or other variable charges. Use incremental authorisation to raise the amount, then final capture when the final amount is known."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Purchase"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorise and capture funds in one step when the amount is known."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Refund"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return funds to a customer for a previous purchase. To refund an existing purchase by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemTransactionId"]},", you use the modifications endpoint. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/refund"},"children":["Refund"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["StandaloneRefund"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return funds to a customer with no original transaction. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions"},"children":["Initiate POS transactions"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Verification"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirm that a card is legitimate and active without reserving funds or completing a purchase. Useful when you need to validate a card before the final amount is known."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To change an existing transaction after initiation, use the modifications endpoint. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/capture"},"children":["Capture"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/final-capture"},"children":["Final capture"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/incremental-authorisation"},"children":["Incremental authorisation"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/refund"},"children":["Refund"]},", and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/void"},"children":["Void"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-features","__idx":8},"children":["Request features"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These fields appear on initiation (and some modification) requests. The matching device or site setting must already be enabled. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/configure-settings"},"children":["Configure device settings"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Gratuity and service charges:"]}," Send a tip in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts.gratuity"]},", or a fee in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts.serviceCharge"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["percentage"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["optional"]}," as needed). You can't send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gratuity"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceCharge"]}," together on the same request. Full request shapes are on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions"},"children":["Initiate POS transactions"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["DCC:"]}," When DCC is enabled for the site and device, the terminal can offer currency conversion during the payment journey. Approved responses may include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dccData"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Status packets:"]}," Optionally set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusCallbackUrl"]}," on the request to override the portal webhook URL for that transaction. Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/configure-settings#receive-status-packets"},"children":["status packets"]}," for in-journey device updates and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/point-of-sale/pos-plus/cloud/api/initiate-transactions#webhooks"},"children":["merchant webhooks"]}," for final authorised, captured, cancelled, and refused outcomes."]}]}]},"headings":[{"value":"How it works","id":"how-it-works","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Two ways to invoke a device","id":"two-ways-to-invoke-a-device","depth":2},{"value":"PXP cloud device API","id":"pxp-cloud-device-api","depth":3},{"value":"Oracle Opera Cloud","id":"oracle-opera-cloud","depth":3},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Sending a request (PXP cloud device API)","id":"sending-a-request-pxp-cloud-device-api","depth":2},{"value":"Intents","id":"intents","depth":3},{"value":"Request features","id":"request-features","depth":3}],"frontmatter":{"seo":{"title":"How it works"}},"lastModified":"2026-10-23T10:26:44.303Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/point-of-sale/pos-plus/cloud/how-it-works","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}