Overview

Your merchant app communicates with each PXP POS+ device using the local REST API. The POS+ device communicates with the Unity Gateway, which allows it to access two core services: the Card service and the POS service.

Note that the location of the merchant app may or may not be on the physical device.

Activating a device

Your device comes with the PXP software pre-installed, so you can get started in just a few steps.

To activate your device:

Log in to the Unity Portal and create a new POS device. You can choose your own settings or keep the default ones to start with and update these later. At this point, the device's state is set to Pending.
Turn on the device and connect it to the Internet. It sends its serial number to the POS Service, which returns an HMAC used to authenticate it. The device's state changes to Active.
The device automatically downloads the settings that were configured in the Portal.

The device is now activated and ready to use.

ℹ️
If a member of the PXP Operations team sets up the device for you, the initial state is New. You'll have to manually change it to Pending in the Unity Portal.

Sending a request

To initiate a transaction, you have to provide key information about the transaction method, as well as the amount and currency.

The transaction method is made up of three elements:

The entry type, which describes the origin of the transaction and determines the supported payment methods and available features. For POS+, this is always in-store.
The funding type, which describes the method used to fund the transaction.
The intent, which describes the purpose of a transaction, indicating the intended money flow direction. Each intent dictates a specific transaction flow and affects how the transaction is handled by the system.

Intents

The following table describes the possible intents that you can set when you initiate a transaction.

Intent	Description
`Authorisation`	Reserve funds on the customer's payment method.
`EstimatedAuthorisation`	Reserve funds on the customer's payment method, based on an estimated amount. This method is particularly useful in environments such as hotels, car rental agencies, and fuel stations, where the final charge may vary based on additional services or usage.
`Purchase`	Authorise and capture funds in one step, for direct purchases where the amount is known.
`Payout`	Send funds to a recipient.
`Refund`	Return funds to a customer.
`Verification`	Verify that a card is legitimate and active, without reserving any funds or completing a purchase. This method is particularly useful in environments such as hotels, car rental agencies, and other scenarios where it's important to validate the card upfront, but the final transaction amount may not be known or processed immediately.

Receiving a response

Once you've successfully submitted your request, you'll receive a 200 response. The content of this response will vary depending on your specific request, but there are several key elements to pay particular attention to.

These are:

The transaction state. This state describes which step of the payment flow a transaction has reached at a given point in time.
The gateway token ID. This token is generated and maintained by PXP and allows you to process recurring transactions or transactions using stored card details, without needing to provide full card details.
The provider response. This object contains raw data received directly from the provider, such as the Payment Account Reference (PAR).

States

The following table describes the possible states that a transaction can go through.

State	Description
`Authorised`	The card issuer has approved your request and the funds are reserved.
`Captured`	Funds have been transferred to your account.
`Cancelled`	The transaction has been successfully voided by you.
`Error`	An error has occurred.
`Refused`	The transaction has been declined. This could be due to incorrect payment details or insufficient funds.

Provider response

The following table describes the different parameters included in a provider response.

Parameter	Description
`provider` string	The name of the provider that processed the transaction.
`code` string	The raw result code returned by the provider that processed the transaction.
`message` string	The raw message associated with the result code from the provider that processed the transaction.
`merchantId` string	The unique identifier assigned by the provider to represent the merchant involved in the transaction processing.
`emvDataResponse` object	Response data from an EMV (Europay, Mastercard, and Visa) transaction.
`paymentAccountReference` string	The Payment Account Reference (PAR) is a unique identifier assigned to a payment account, independent of the card number. It remains constant over the account's lifetime, even if the card number (PAN) changes. PAR enhances transaction security and privacy, serving as a secure reference point for cardholders, merchants, and issuers. It is used in digital transaction processing to reliably link transactions and accounts without exposing the actual card number.
`schemeTransactionId` string	A unique identifier assigned by the card scheme (e.g., Visa, Mastercard) to each transaction. This identifier is crucial for tracking, reconciliation, and managing the lifecycle of the transaction, especially in contexts like chargebacks and fraud analysis. For card transactions, this could be the Visa Transaction Identifier or MasterCard Banknet Reference Number.
`merchantAdvice` object	Provides additional guidance or recommendations from the card network regarding the transaction. This information is particularly useful for understanding the reasons behind a transaction's refusal and can offer suggestions for next steps. For instance, it might indicate that updated account information is available or suggest specific actions to resolve the refusal. The `merchantAdvice` object includes a `code` and `message` to detail this advisory information, making it easier for you to take corrective action or understand the refusal context.