How it works

Learn about how Tap+ works.

Overview

Tap+ allows you to leverage your existing Android devices for payment processing.

Your merchant app communicates with each Android device using the Tap+ API or SDK. The Android 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.

Diagram showing how Tap+ connects to different PXP services

Integration methods

The Tap+ API is a REST API that uses HTTP methods (POST, GET, etc.), returns standard HTTP status codes, communicates using JSON, and uses resource-based URLs. For more detailed information about PXP APIs, see API overview.

Key features

With Tap+, you benefit from:

Flexible transaction management: We support a wide range of transaction types, including purchases, refunds, authorisations, and voids. Each transaction type is designed with flexibility and efficiency in mind, enabling you to adapt the integration to your specific business needs through either SDK methods or REST API endpoints.
Real-time response handling: Handle transaction responses dynamically based on standardised status codes. Each response is categorised to facilitate quick actions and error handling within your application, whether using SDK callbacks or API response objects.
Callback and webhook integration: With built-in support for merchant deeplinks and structured response formats, enable your customers to return to designated points within your application upon transaction completion. This feature creates a cohesive user experience through SDK navigation or API correlation tracking.
Configurable initialisation: The configuration process is straightforward, through SDK configuration objects or REST API parameters, where you can set up credentials, endpoints, merchant identifiers, and other essential parameters for smooth integration across both platforms.
Comprehensive error management: We provide robust error handling throughout, ensuring you can capture, log, and address issues promptly. Standardised error codes and messages provide insight into transaction problems, helping developers maintain reliable payment processing regardless of integration method.

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 Tap+, this is always in-store.
The funding type, which describes the method used to fund the transaction.
The intent or operation, which describes the purpose of a transaction and indicates the intended money flow direction. Each intent or operation dictates a specific transaction flow and affects how the transaction is handled by the system. Note that intents are used to initiate transactions, while operations are used to modify transactions.

Intents

The following table describes all available intents.

Name	Description
`Purchase`	Authorise and capture funds in one step, for direct purchases where the amount is known.
`StandaloneRefund`	Return funds to a customer without reference to a previous transaction. Used for customer returns and service cancellations.

Operations

The following table describes all available operations, which are used to modify existing transactions.

Name	Description
`Refund`	Return funds from a previously captured transaction. This requires the original transaction reference.
`Void`	Cancel a previously authorised transaction before it is settled. Only available for transactions that haven't been settled. This is only supported when Elavon is the acquirer.

Receiving a response

Once you've successfully submitted your request, you'll receive a 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. Learn more about states.
The state data. This object contains a response code and message that provide detailed information about the transaction outcome, following the ISO 8535 standard. Learn more about state data.
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). Learn more about the provider response.

Action required: Store Diners network reference ID (from 1 July 2026)

If you process Diners transactions with stored card details (recurring or merchant-initiated payments using the gateway token ID), you must store the schemeTransactionId (network reference ID) for all Diners transactions starting 1 July 2026. Both this and the Retrieval Reference Number will be required for subsequent MIT/recurring payments.

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.

State data (response codes)

Every transaction response includes a stateData object containing a response code (stateData.code) and response message (stateData.message) that provide detailed information about the transaction outcome. These codes follow the ISO 8535 standard and help you understand exactly why a transaction was approved, declined, or encountered an error.

The response code and its corresponding message allow you to implement appropriate handling logic in your integration, such as displaying user-friendly messages, triggering retry mechanisms, or logging specific decline reasons for analysis.

The following table lists all possible response codes you may receive.

ISO 8535 code	Description
`CRD000`	Approved
`CRD001`	Honour with identification
`CRD002`	Approved for partial amount
`CRD003`	Approved (VIP)
`CRD004`	Approved, update track 3
`CRD005`	Approved, account type specified by card issuer
`CRD006`	Approved for partial amount, account type specified by card issuer
`CRD007`	Approved, update ICC
`CRD100`	Do not honour
`CRD101`	Expired card
`CRD102`	Suspected fraud
`CRD103`	Card acceptor contact acquirer
`CRD104`	Restricted card
`CRD105`	Card acceptor call acquirer's security department
`CRD106`	Allowable PIN tries exceeded
`CRD107`	Refer to card issuer
`CRD108`	Refer to card issuer's special conditions
`CRD109`	Invalid merchant
`CRD110`	Invalid amount
`CRD111`	Invalid card number
`CRD112`	PIN data required
`CRD113`	Unacceptable fee
`CRD114`	No account of type requested
`CRD115`	Requested function not supported
`CRD116`	Not sufficient funds
`CRD117`	Incorrect PIN
`CRD118`	No card record
`CRD119`	Transaction not permitted to cardholder
`CRD120`	Transaction not permitted to terminal
`CRD121`	Exceeds withdrawal amount limit
`CRD122`	Security violation
`CRD123`	Exceeds withdrawal frequency limit
`CRD124`	Violation of law
`CRD125`	Card not effective
`CRD126`	Invalid PIN block
`CRD127`	PIN length error
`CRD128`	PIN key sync error
`CRD129`	Suspected counterfeit card
`CRD180`	Retry in contact mode or SCA Ecom required
`CRD181`	Pick up card
`CRD182`	Bad format
`CRD183`	Timeout / Malfunction
`CRD184`	Card restricted
`CRD185`	Refused by fraud or scoring system

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.
`terminalId` string	This is the unique identifier assigned by the provider to represent the terminal involved in the transaction processing.
`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. Important for Diners (from 1 July 2026): For Diners transactions, this field returns the network reference ID (NRID). You must store this value for all Diners transactions as it will be required (alongside the Retrieval Reference Number) when submitting subsequent merchant-initiated or recurring payments. This is mandatory for PSD2 SCA compliance and Diners card scheme rules.
`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.
`settlementDate` date	The date on which the transaction funds are settled between banks for MasterCard payments. This field is applicable and provided only for transactions processed using MasterCard. The settlement date is crucial for financial reconciliation and is formatted as `YYYY-MM-DD`.