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
`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.
`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
`Incremental`	Increase the authorised amount on an initial authorisation. Used when the final amount exceeds the initial authorisation.
`Capture`	Capture partial funds from an initial authorisation. Used when capturing the authorised amount in multiple parts.
`FinalCapture`	Capture the final part of funds from an initial authorisation. Marks the authorisation as completely captured.
`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.

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.
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.

Property	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.
`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. This object includes a code and message to detail this advisory information, making it easier for merchants to take corrective action or understand the refusal context.
`merchantAdvice.code` string	An advisory code provided by the card network that categorises the type of advice or recommendation.
`merchantAdvice.message` string	A human-readable message that provides further details or clarification about the advice code, potentially suggesting next steps or reasons for the transaction refusal.
`settlementDate` string	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`.