Acceptance Devices | Tap to Pay on Android Acceptance Devices App
This section describes how to use this guide and where to find further information.
Audience and Purpose
This guide is written for partner developers, system architects, and independent software
vendors (ISVs) who wish to integrate their point-of-sale system with compatible Android
devices in a semi-integrated manner.
Implementing the Tap to Pay on Android Acceptance Devices App solution requires software
development skills. You must write code that uses the API request and response fields to
integrate the solution into your point-of-sale system.
Conventions
These statements appear in this document:
IMPORTANT
An
Important
statement contains information essential to
successfully completing a task or learning a concept.
WARNING
A
Warning
contains information or instructions, which, if not
heeded, can result in a security risk, irreversible loss of data, or significant cost in
time or revenue or both.
Support
For support information about any service, visit the Support Center:
Renamed Getting Started with the Tap to Phone Android Semi-Integrated Solution section
to Getting Started with the Acceptance Devices App and updated introduction. See Getting Started with the Acceptance Devices App.
Updated code examples in all mid-transaction status update examples. See REST example
sections in Local Mode Payment Services.
Removed Generating a Customer or Merchant Receipt from Processing Payment Transactions
in Semi-Integrated Mode section. The feature does not apply to this product.
Removed Obtaining a Merchant ID and Secret Key instructions from Processing Payment
Transactions in Cloud Mode section. This task is now performed in combination with
generating a bearer token.
Removed Generating a Customer or Merchant Receipt from Processing Payment Transactions
in Cloud Mode section. The feature does not apply to this product.
VISA Platform Connect: Specifications and Conditions for
Resellers/Partners
The following are specifications and conditions that apply to a Reseller/Partner enabling
its merchants through
Cybersource for
Visa Platform Connect
(“VPC”)
processing
. Failure to meet any of the specifications and conditions below is
subject to the liability provisions and indemnification obligations under
Reseller/Partner’s contract with Visa/Cybersource.
Before boarding merchants for payment processing on a VPC acquirer’s connection,
Reseller/Partner and the VPC acquirer must have a contract or other legal agreement
that permits Reseller/Partner to enable its merchants to process payments with the
acquirer through the dedicated VPC connection and/or traditional connection with
such VPC acquirer.
Reseller/Partner is responsible for boarding and enabling its merchants in
accordance with the terms of the contract or other legal agreement with the relevant
VPC acquirer.
Reseller/Partner acknowledges and agrees that all considerations and fees associated
with chargebacks, interchange downgrades, settlement issues, funding delays, and
other processing related activities are strictly between Reseller and the relevant
VPC acquirer.
Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is
responsible for payment processing issues, including but not limited to, transaction
declines by network/issuer, decline rates, and interchange qualification, as may be
agreed to or outlined in the contract or other legal agreement between
Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR
OMISSIONS BY THE
Visa Platform Connect
ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA
NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR
ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE
RELEVANT
Visa Platform Connect
ACQUIRER.
Introduction to Acceptance Devices | Tap to Pay on Android Acceptance Devices App
The Tap to Pay on Android Acceptance Devices App enables partners to easily integrate
their point-of-sale (POS) systems with supported Android devices in a semi-integrated
manner using Local and Cloud modes. Leveraging the Acceptance Devices Android app and
using API requests, your POS system can accept payments by communicating with the
Android device over a local Wi-Fi network or the cloud.
The solution can also be operated in Standalone mode. This mode does not require
integration with a POS system and enables you to start transactions directly from the
Android device.
For more information about the modes available in the Acceptance Devices app, see:
Your Android device must be compatible with the Tap to Pay on Android Acceptance Devices
App solution in order to accept contactless payments.
These are the requirements for a compatible Android device:
Tap to Pay Ready app is installed. You can download the app from the Google Play Store.
Supports Google Mobile Services (GMS) and Google Play Store.
Android 12 or later operating system is installed. Android versions that do not
receive security patches are not supported.
Has hardware-backed keystore.
Contains near-field communication (NFC) enabled chip.
Automatic time and date detection are enabled.
Developer options are disabled.
Device is not rooted. This setting prevents you from changing system-level files
or settings.
Transaction Workflow for the Tap to Pay on Android Acceptance Devices App
This is the transaction workflow for the Tap to Pay on Android Acceptance Devices
App.
Figure:
Tap to Pay on Android Acceptance Devices App Transaction Workflow
The Tap to Pay on Android Acceptance Devices App workflow typically includes this
sequence of events:
The point-of-sale (POS) system, running on Windows, Android, or iOS, integrates to
the Tap to Pay on Android Acceptance Devices App APIs.
The merchant's POS system sends an API request, using the local Wi-Fi network or
the cloud, to the Acceptance Devices app that is running on the Android device.
The Acceptance Devices app user interface opens on the Android device and
displays prompts that guide the customer through the payment flow.
The Acceptance Devices app sends an API response to the POS system with the
transaction result and details, which completes the transaction.
Getting Started with the Acceptance Devices App
This section describes how to get started with using the Acceptance Devices app. After
you finish setting up the device and configuring the app, you can process payments. For
information about the types of payments services available in this solution, see these
topics:
Follow these steps to set up the Android device in the Acceptance Devices
app:
Open the Acceptance Devices App on the Android device.
On the Welcome screen, tap
Start Configuration
. The app
is configured to use the production environment. To switch to the test
environment or demo mode, press and hold the Welcome screen for 5 seconds. The
Select Environment screen appears. Choose an environment for configuration.
On the Create a Passcode screen, enter a unique passcode. The passcode must
consist of six digits. Confirm the passcode by entering it a second time, then
tap
Save Passcode
. You will use this passcode to access
the app, so choose a code that you will remember.
The app does not include an
option to reset the passcode. If you forget the code, you must reinstall the
Acceptance Devices app and complete the set-up process again.
Check the internet connection status of your Android device:
When your device is not connected to the internet, the Connect to
Internet screen appears. Tap
Connect to Internet
, and
choose an internet connection option.
When your device is connected to the internet, the Internet Connected
screen appears. Tap
Activating an Android Device in the Acceptance Devices App
In order to process payments on your Android device using the Acceptance Devices app and
your point-of-sale (POS) system, you must use an activation code to activate the Android
device in the Acceptance Devices app. You can generate the code in the
Business Center
or by using an API request. After generating the activation code, you
must enter it in the Acceptance Devices app.
Generating an Android Device Activation Code in the
Business Center
Before activating the Android device in the Acceptance Devices app, you must generate a device
activation code.
You can generate an activation code in the
Business Center
. The code is valid
for 24 hours.
Follow these steps to generate an Android device activation code:
In the
Business Center
, go to the left navigation panel and choose
Acceptance Devices
>
Activation Codes
. The Activation Codes page
appears.
Click the
Select Transacting MID
drop-down menu.
Choose a transacting MID from the list.
Click the
Select number of Activation Codes
drop-down
menu.
Choose the number of activation codes that you want to generate. The maximum
number of codes is 15.
Click
Generate
. The activation codes display on the
page. To copy the codes to your clipboard, click the icon next to the
code.
To download a text file containing the activation codes, click the
Download codes as a .txt file
button.
Navigate to the Download folder on your computer to access the text file.
Generating an Android Device Activation Code Using a REST API Request
Before activating an Android device in the Acceptance Devices app, you must generate a
device activation code.
You can use a REST API request to generate a device activation code, which is valid for
24 hours.
You must authenticate each request that you send to a
Cybersource
API. In
order to authenticate an API request, you can use a REST shared secret key or a
REST certificate. For more information about authentication requirements, see
The POST request must include the transacting merchant ID (MID) that is sending the
request and the quantity of activation codes to be generated. You can request up to
15 activation codes in a single request.
Test:
POST
https://apitest.cybersource.com
/dms/v2/merchants/{transacting
mid}/activation-codes?size={number of activation codes}
Production:
POST
https://api.cybersource.com
/dms/v2/merchants/{transacting
mid}/activation-codes?size={number of activation codes}
Required Fields for Generating an Android Device Activation Code
The body of the API request is empty. The POST request must include the information
required to return the response.
REST Example: Generating an Android Device Activation Code
Request
The body of the request is empty. The POST request includes the information
required to return the response.
{
}
Response to a Successful Request
The response includes the activation code (
token
field)
and the amount of time (
ttl
field) that the activation
code is valid. The
ttl
field value is shown in
milliseconds. The activation code is valid for 24 hours.
Entering an Activation Code in the Acceptance Devices App
Before activating an Android device, you must generate an activation code for the
device in the
Business Center
or by using a REST API request. The activation
code is valid for 24 hours.
Follow these steps to enter an activation code for an Android device in the Acceptance Devices
app:
On the Device Activation screen, enter the activation code that you generated.
Tap
Continue
.
When the Tap to Pay Ready app is not installed on your Android device, you are
prompted to install the app. Tap the Google Play icon to install the app. When
installation is complete, return to the Acceptance Devices app and tap
Continue
.
When the Tap to Pay Ready app is installed and the activation code is accepted,
the Activation Successful screen appears. Tap
Confirm
.
The Assigned Serial Number screen appears. Record the serial number assigned to
your device for future reference. You must provide the serial number when
re-enrolling a device or when communicating with customer support. Tap
Continue
.
AFTER COMPLETING THE TASK
If you are using the app in Local mode with Mutual Transport Layer Security (mTLS) enabled, you
must activate a secure mTLS connection between your point-of-sale (POS) system and
the Android device in the Acceptance Devices app. For more information, see Activating a Secure mTLS Connection.
If you are using the app in Local mode with Transport Layer Security (TLS) enabled or
in Cloud mode, you must start the Acceptance Devices app server. For more
information, see Getting Started with the Acceptance Devices App Server.
Getting Started with the Acceptance Devices App Server
In order to process payments on your Android device using the Acceptance Devices app and your
point-of-sale (POS) system, you must start the Acceptance Devices app server on the Android
device.
Follow these steps to start the Acceptance Devices app server:
Before you start the server, the Device Status screen shows the
Device is
not connected
message. Tap
Connect Device
.
After you start the server, the Device Status screen shows the
Device
connected
message. The Android device is activated and ready to accept
transactions.
Tap the back navigation arrow to finish setting up.
Customizing the Acceptance Devices App
This section describes how to customize the Acceptance Devices app in the
Business Center
or by using a REST API request.
Use the Acceptance Devices Customizations feature in the
Business Center
to
customize these parameters for a portfolio, merchant, or transacting merchant ID (MID):
User interface
Common
Local mode
Standalone mode
Use a REST API request to perform these customization tasks:
Retrieve and review your current parameter customization settings.
Update customization settings for user interface, common, Local mode, and
Standalone mode parameters.
Customizable User Interface Parameters
You can customize these user interface parameters in the Acceptance Devices app when it
is in Local, Standalone, or Cloud mode:
Home screen logo
Defines the logo that is shown on the home screen of the app.
Toolbar logo
Defines the logo that is shown during transaction processing.
Primary color
Defines the color of the primary buttons.
Color on primary
Defines the color of the text on the primary buttons.
Background color
Defines the color of the screen background.
Color on background
Defines the color of the text on the screen background.
Button shape
Defines the shape of the buttons.
Customizable Common Parameters
You can customize these common parameters in the Acceptance Devices app when it is in
Local, Cloud, or Standalone mode:
Operating mode – Choose one of these operating modes:
Semi-Integrated with Standalone:
Acceptance Devices app
operates in Local and Standalone modes. This is the default setting.
Semi-Integrated:
Acceptance Devices app operates only in
Local mode.
Standalone:
Acceptance Devices app operates only in
Standalone mode.
Cloud with Standalone:
Acceptance Devices app operates in
Cloud and Standalone modes.
Cloud:
Acceptance Devices app operates only in Cloud
mode.
Automatic receipt printing
Enables the automatic printing of the merchant or customer receipt after each
transaction. The default setting is
Disabled
. This feature is
available only on terminals with integrated printers.
Enable accessibility options
Enables the use of accessibility features during transaction processing. This
feature supports visually impaired customers by using voice-over capabilities.
The default setting is
True
.
Tipping type – Choose one of these tipping types:
Percentage choice:
Customer selects between three pre-defined
tip percentages or enters a custom tip amount. The tipping values are set in the
Tipping values parameter. This is the default setting.
Tip amount:
Customer enters a custom tip amount.
Total amount:
Customer enters the full amount, including the tip
amount.
Tipping values
Defines the three tipping percentage choices that appear on the screen for the
customer to choose. This parameter only applies if the Tipping Type parameter is
set to Percentage choice. The default setting is
10, 15,
20
.
Tipping confirmation screen
Enables the display of an additional screen during a Sale with On-Reader Tipping
transaction. The customer reviews and confirms that the tip amount before the
payment is processed. The default setting is
False
.
MOTO CVV required
Enables Card Verification Value (CVV) as a required data input for mail order or
telephone order (MOTO) transactions. The default setting is
True
.
MOTO address required
Enables the customer's address as a required data input for MOTO transactions.
The default setting is
True
.
MOTO confirmation screen
Enables the display of an additional screen during MOTO transactions. The
merchant reviews and confirms the MOTO address data shown on the screen before
the payment is processed. The default setting is
False
.
Enable offline mode
Enables the option to toggle Offline mode ON/OFF to process transactions without
internet connectivity. The default setting is
False
.
Transaction history view
Defines whether the transaction history view is shown at the merchant or
device level. The default setting is
Merchant
.
Customizable Local Mode Parameters
You can customize these Local mode parameters in the Acceptance Devices app:
Port
Defines the port number used by the server on the terminal or device. The
default setting is
8443
.
Security
Defines whether the server on the terminal or device uses two-way verification
(mTLS) or one-way verification (TLS). The default setting is
mTLS
.
Protocol
Defines the protocol that is used to process transactions. The default setting
is
ADP
.
Signature capture type
Defines whether the signature is captured on the terminal or device screen or
paper receipt, or is skipped. The default setting is
On
screen
.
Skip summary screen
Disables the Summary screen from displaying after each transaction. The default
setting is
True
.
Customizable Standalone Mode Parameters
You can customize these Standalone mode parameters in the Acceptance Devices app:
Additional transaction types
Defines the list of transaction types, in addition to sale and refund
transactions that are supported when the app is in Standalone mode. The default
setting is
None
.
Enable LAC installments
Enables the option to toggle Latin America and Caribbean (LAC) installments
ON/OFF in order to process transactions with installment details. The default
setting is
False
.
Enable tax details
Enables the option to toggle Tax details ON/OFF in order to process transactions
with tax details. The default setting is
False
.
Customizing Parameters in the
Business Center
You can customize common, Local mode, and Standalone mode parameters for the
Acceptance Devices app in the
Business Center
.
In the
Business Center
, go to the left navigation panel and choose
Acceptance Devices
>
Customizations
. The Customizations screen
appears.
Click the
Load customization parameter for
drop-down
menu.
Choose a user level from the list. Click
Load
.
Scroll down to see the various parameter sections and which elements are
available to customize for the chosen user level.
Choose parameters to customize. To see a description of a parameter, hover your
mouse over the Information icon.
Click
Apply Changes
.
Retrieving Parameters Using a REST API Request
Using a REST API request, you can retrieve and view customizable parameters and their
current values. Depending on your account settings, you can view values for a portfolio,
merchant, or transacting merchant ID (MID).
You must authenticate each request that you send to a
Cybersource
API. In
order to authenticate an API request, you can use a REST shared secret key or a
REST certificate. For more information about authentication requirements, see
Required Fields for Retrieving Parameters Using a REST API Request
The body of the API request is empty. The GET request must include the information
required to return the response.
REST Example: Retrieving Parameters Using a REST API Request
Request
The body of the request is empty. The GET request includes the information required
to return the response.
{
}
Response to a Successful Request
{
"id": "{{organization id}}",
"customizations": {
Your configured parameters response data appears here.
},
"customizationMetadata": {
Your possible values for parameters response data appears here.
}
}
Customizing Parameters Using a REST API Request
You can update customizable parameters for a portfolio, merchant, or transacting merchant
ID (MID) by using a REST API request.
You must authenticate each request that you send to a
Cybersource
API. In
order to authenticate an API request, you can use a REST shared secret key or a
REST certificate. For more information about authentication requirements, see
The body of the response is empty. A successful response is indicated with a
200 OK
status.
{
}
Complying with the PCI MPoC Standard
The Tap to Pay on Android Acceptance Devices app complies with the PCI Security Standards
Council (PCI SSC) Mobile Payments on COTS (MPoC) Standard, ensuring secure and reliable
payment processing. The standard is typically referred to as
PCI MPoC
.
The solution uses the PCI MPoC-certified Tap to Pay Ready app by Visa to fulfill
software, attestation, and monitoring requirements. The app uses a transparent overlay
during payment processing to maintain a seamless UI experience.
Using an app-to-app approach, payment processing is handled separately from the
Acceptance Devices app. Transactions are started in the Acceptance Devices app and
securely passed to the Tap to Pay Ready app for processing before returning to the
original app. This approach helps reduce PCI compliance complexity, lowers costs, speeds
up time-to-market, and enables seamless MPoC-related updates without affecting the
Acceptance Devices app.
For more information about the solution's PCI compliance status, click this link.
Transaction Workflow for the PCI-Certified MPoC Solution
This is the transaction workflow for the PCI-Certified MPoC Solution in the Tap to Pay on
Android Acceptance Devices app.
Figure:
PCI-Certified MPoC Solution Workflow
The PCI-Certified MPoC Solution workflow typically includes this sequence of events:
The Acceptance Devices app sends a request to the Tap to Pay Ready app to initiate a
secure switch to the other app. This activity is invisible to the customer, which
ensures that the UI experience is seamless.
The PCI-Certified MPoC Solution uses the Tap to Pay Ready app to provide a
transparent overlay to securely capture payment details.
The Tap to Pay Ready backend receives payment details from the Tap to Pay Ready app
to complete transaction processing.
Installing the Tap to Pay Ready App
The PCI MPoC-Certified Solution uses the Tap to Pay Ready app to process
PCI-compliant payment transactions. The app must be installed on your Android
device.
Use one of these options to install the Tap to Pay Ready App:
Download the app from the Google Play store directly onto
your Android device. No additional set up is required.
When using the solution in Local mode, the communication protocol used between the
Acceptance Devices app and the point-of-sale (POS) system is a single WebSocket channel.
Through this channel, simultaneous, two-way communication occurs between the Acceptance
Devices app and the POS system.
Retrieving the Root CA Certificate
When the app is operating in Local mode, you can validate the Acceptance Devices app
server’s certificate by adding the Root CA certificate to your trust store. This action
is required if you want to use an mTLS connection. For more information, see Activating a Secure mTLS Connection.
You can retrieve the Root CA certificate in the
Business Center
or by using an
API request.
Retrieving the Root CA Certificate in the
Business Center
Follow these steps to retrieve the Root CA certificate in the Business Center:
In the
Business Center
, go to the left navigation panel and choose
Acceptance Devices > Activation Codes
. The Activation
Codes page appears.
Click
Download Root CA Certificate
. When the download is
complete, the browser window shows a download completion message.
In the local folder directory of your computer, navigate to the Download folder
to access the Root CA certificate file.
Retrieving the Root CA Certificate Using a REST API Request
You can use a REST API request to retrieve the Acceptance Devices app server’s Root CA
certificate when the app is operating in Local mode. You would then add the certificate
to your trust store.
You must authenticate each API request you send to a
Cybersource
API by using a REST shared secret key or a REST certificate. For more information about authentication
requirements, see
When the app is operating in Local mode, using a Mutual Transport Layer Security (mTLS)
connection creates an additional layer of security for communication between the
Acceptance Devices app running on your Android device and point-of-sale (POS) system.
Using the mTLS protocol is recommended because it employs two-way verification. The
minimum requirement for providing end-to-end data security is using the Transport Layer
Security (TLS) protocol.
Before activating an mTLS connection, you must retrieve the Root CA certificate. For more
information, see Retrieving the Root CA Certificate.
Endpoints
The endpoint is the same for the test and production environments.
Test:
POST https://{device IP address:port number}/ or wss://{device IP
address:port number}/
Production:
POST https://{device IP address:port number}/ or wss://{device IP
address:port number}/
Generating a POS Connection Code for the Point-of-Sale System
To ensure the security of the data sent over the internet between your POS system and
Android device, you must establish a secure connection (sync) between your system
and the device. You must complete this task one time for each POS system you are
using.
If Mutual Transport Layer Security (mTLS) is enabled and the device activation is
complete, the Generate Code screen appears in the Acceptance Devices app.
Follow these steps to generate a POS connection code for a POS system in the
Acceptance Devices app:
On the Generate Code screen, tap
Generate Code
.
Record the eight-character code that appears on the screen. You will use this
code to request a certificate from the POS system. The screen shows an
expiration timer for the code, which refreshes every 300 seconds.
Requesting Certificates for the Point-of-Sale System
Before you can request certificates, you must generate a set-up code for the
point-of-sale (POS) system.
To finish activating the secure mTLS connection, request certificates for the POS
system by sending a request to the Android device through the POS system.
On the Generate Code screen, tap the
Details
arrow. The
Details section expands to show the HTTP and WSS (WebSocket) addresses and the
port number.
Record the HTTP and WSS addresses and port number shown in the Details section.
You will use this information to request a certificate through the POS system,
using the HTTPS or WSS address.
To request the certificates, send an API request through the POS system to the
HTTP or WSS address and port number, along with the POS connection code shown on
the Android device and a unique POS ID.
After the certificates are retrieved by the POS system and the sync between
your POS system and Android device is complete, the
POS Activation
Successful
message appears. Tap
Close
. The next
set-up screen appears.
Required Fields for Requesting Certificates for the Point-of-Sale System
posId
Set this field to a unique, user-defined ID for the POS system.
setupCode
Set this field to the POS connection code shown on the Generate POS
Connection Code screen in the Acceptance Devices app.
REST Example: Requesting Certificates for the Point-of-Sale System
Request
{
"posId" : "123",
"setupCode" : "8QW1YS1D"
}
Response to a Successful Request
The response includes the private key and certificates required in order to establish
the secure Mutual Transport Layer Security (mTLS) connection between the Android
device and POS system. For security reasons, this example does not show actual
private key and certificate response data.
-----BEGIN RSA PRIVATE KEY-----
Your RSA private key response data appears here.
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
Your certificate response data appears here.
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Your certificate response data appears here.
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Your certificate response data appears here.
-----END CERTIFICATE-----
Implementing Hostname Validation
When operating in Local mode, you have the option to include hostname validation in your
client. When the Android device is activated, a certificate is generated on the device
and a Subject Alternative Name (SAN) is added. On the Android device, the SAN can be
viewed as the Domain Name System (DNS) name for the Acceptance Devices app server.
The SAN is generated in this format: {IMEI}.cybs.seclib.io.
To perform hostname validation or to connect to the Android device by using a SAN instead
of an IP address, you can add the device IP address and SAN to your hosts file.
Processing a Sale
This section describes how to process a sale transaction when the app is in Local mode.
This type of transaction combines an authorization and a capture into a single
transaction.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Sale
type
Set this field to
PaymentRequest
.
merchantReferenceCode
Set this field to a unique, user-defined reference code. The code can
consist of up to 50 alphanumeric characters, underscores (_), and dashes
(-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX)
or a Social Security number (XXX-XX-XXXX).
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Refund
This section describes how to process a refund when the app is in Local mode. This type
of refund includes a reference to the original transaction for a full or partial
transaction amount. Stand-alone credits are also supported in this Acceptance Devices
solution. For more information, see Processing a Stand-Alone Credit.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Refund
type
Set this field to
LinkedRefundRequest
.
transactionId
Set this field to the
id
field value from the original
transaction.
Optional Fields for Processing a Refund
Use the optional amount and currency fields to process a partial refund. Otherwise,
the full amount will be refunded.
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Stand-Alone Credit
This section describes how to process a stand-alone credit when the app is in Local mode.
This type of transaction is used to process a credit without reference to the original
transaction. The customer is required to present their card for this type of
transaction.
WARNING
When processing a stand-alone credit, there is no limit on the credit amount because
there is no reference to the original transaction amount. The recommendation is to use a
refund transaction whenever possible. For more information, see Processing a Refund.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Stand-Alone Credit
type
Set this field to
StandaloneRefundRequest
.
merchantReferenceCode
Set this field to a unique, user-defined reference code. The code can
consist of up to 50 alphanumeric characters, underscores (_), and dashes
(-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX)
or a Social Security number (XXX-XX-XXXX).
During the transaction, you might receive one or more update responses indicating the current status of the transaction. You can choose to display these updates on your point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Requesting a Check Transaction Status
This section describes how to request a check transaction status when the app is in Local
mode. This transaction is used to obtain response data for a transaction that was lost
or timed out.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Requesting a Check Transaction Status
type
Set this field to
TransactionLookupRequest
.
idType
Set this field to
TRANSACTION_ID
or
MERCHANT_REFERENCE_CODE
.
id
Set this field to the
id
or
merchantReferenceCode
field value from the original
transaction.
REST Example: Requesting a Check Transaction Status
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Cancel Transaction
This section describes how to process a cancel transaction request in Local
mode. This request is sent to interrupt an in-process transaction.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Cancel Transaction
type
Set this field to
CancelRequest
.
REST Example: Processing a Cancel Transaction
Request
{
"type": "CancelRequest"
}
Mid-Transaction Status Updates
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Sale with On-Reader Tipping
This section describes how to process a sale with on-reader tipping in Local
mode. At the start of each transaction, the Android device prompts the customer to add a
tip by showing suggested tip amounts. The customer selects or enters a tip amount on the
device before presenting their payment card.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Sale with On-Reader Tipping
type
Set this field to
PaymentRequest
.
merchantReferenceCode
Set this field to a unique, user-defined reference code. The code can
consist of up to 50 alphanumeric characters, underscores (_), and dashes
(-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX)
or a Social Security number (XXX-XX-XXXX).
amountDetails.amount
Set this field to the transaction amount.
amountDetails.currency
Set this field to the currency code.
askForTip
Set this field to
ON_DEVICE
.
REST Example: Processing a Sale with On-Reader Tipping
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Pre-Authorization
This section describes how to process a pre-authorization for an initial amount in Local
mode. A pre-authorization transaction places a temporary hold on the customer's payment
card, which can be captured at a later time.
Most authorizations expire in 5 to 7 days. The issuing bank sets the length of time
before expiration. When an authorization expires with the issuing bank, your bank or
processor might require you to re-submit an authorization request and include a request
for capture in the same message. For more information, see Processing a Capture.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Pre-Authorization
type
Set this field to
PaymentRequest
.
merchantReferenceCode
Set this field to a unique, user-defined reference code. The code can
consist of up to 50 alphanumeric characters, underscores (_), and dashes
(-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX)
or a Social Security number (XXX-XX-XXXX).
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing an Incremental Authorization
This section describes how to process an incremental authorization in Local
mode. This type of request can be made on a pre-authorization transaction to increase
the authorized amount before it is captured.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing an Incremental Authorization
type
Set this field to
IncrementalAuthorizationRequest
.
transactionId
Set this field to the
id
field value from the original
transaction.
amountDetails.amount
Set this field to the transaction amount.
amountDetails.currency
Set this field to the currency code.
REST Example: Processing an Incremental Authorization
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Capture
This section describes how to capture a pre-authorized transaction in Local
mode. The capture request references the approved pre-authorization request.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Capture
type
Set this field to
CaptureRequest
.
transactionId
Set this field to the
id
field value from the original
transaction.
Optional Fields for Processing a Capture
Use the optional amount and currency fields to process a partial capture. Otherwise,
the full amount will be captured.
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Sale with Installment Details
This section describes how to process a sale transaction with installment details when
the app is in Local mode. This type of transaction can be used to include the required
installment details as part of the sale transaction.
This transaction is available only in the Latin American & Caribbean (LAC)
region.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Sale with Installment Details
type
Set this field to
PaymentRequest
.
merchantReferenceCode
Set this field to a unique, user-defined reference code. The code can
consist of up to 50 alphanumeric characters, underscores (_), and dashes
(-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX)
or a Social Security number (XXX-XX-XXXX).
amountDetails.amount
Set this field to the transaction amount.
amountDetails.currency
Set this field to the currency code.
Optional Fields for Processing a Sale with Installment Details
Use one or more of the optional
installmentDetails
fields to
provide additional installment details.
installmentDetails.numberOfInstallments
Set this field to the number of installments.
installmentDetails.planType
Set this field to
MERCHANT_FUNDED
or
ISSUER_FUNDED
.
installmentDetails.interestPlan
Set this field to
true
or
false
.
installmentDetails.governmentPlan
Set this field to
true
or
false
.
REST Example: Processing a Sale with Installment Details
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Sale with Payment Facilitator Details
This section describes how to process a sale transaction with payment facilitator details
when the app is in Local mode. This type of transaction can be used to include the
required payment facilitator details as part of the sale transaction.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Sale with Payment Facilitator Details
type
Set this field to
PaymentRequest
.
merchantReferenceCode
Set this field to a unique, user-defined reference code. The code can
consist of up to 50 alphanumeric characters, underscores (_), and dashes
(-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX)
or a Social Security number (XXX-XX-XXXX).
amountDetails.amount
Set this field to the transaction amount.
amountDetails.currency
Set this field to the currency code.
Optional Fields for Processing a Sale with Payment Facilitator Details
Use one or more of the optional
merchantDetails
fields to provide
the required payment facilitator details.
merchantDetails.salesOrganizationId
Set this field to the sales organization identifier.
merchantDetails.subMerchantId
Set this field to the sub-merchant identifier.
merchantDetails.descriptorName
Set this field to the descriptor name.
REST Example: Processing a Sale with Payment Facilitator Details
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Sale with Tax Details
This section describes how to process a sale transaction with tax details when the app is
in Local mode. This type of transaction can be used to include the required tax details
as part of the sale transaction.
Endpoints
The endpoint is the same for the test and production environments.
Test:
wss://{device IP address:port number}/
Production:
wss://{device IP address:port number}/
Required Fields for Processing a Sale with Tax Details
type
Set this field to
PaymentRequest
.
merchantReferenceCode
Set this field to a unique, user-defined reference code. The code can
consist of up to 50 alphanumeric characters, underscores (_), and dashes
(-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX)
or a Social Security number (XXX-XX-XXXX).
amountDetails.amount
Set this field to the transaction amount.
amountDetails.currency
Set this field to the currency code.
Optional Fields for Processing a Sale with Tax Details
During the transaction, you might receive one or more update responses indicating the
current status of the transaction. You can choose to display these updates on your
point-of-sale (POS) system.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Cloud Mode Payment Services
This section describes how to process payment services featured in the Acceptance Devices
app when operated in Cloud mode. In this mode, the point-of-sale (POS) system
communicates over the cloud with the Acceptance Devices app on the Android device.
For information about other modes available in the Acceptance Devices app, see:
When operating the solution in Cloud mode, the communication protocol used between the
Acceptance Devices app and the point-of-sale (POS) system is a single HTTPS request to
the backend.
The transaction response can be sent either synchronously or asynchronously:
Synchronously
The POS system keeps the connection open until the transaction is completed
and the response is provided with the full transaction details. The backend
timeout setting is 180 seconds.
Asynchronously
The POS system receives a response with an interaction identifier after the
transaction is started. The interaction identifier can then be used to check
the transaction events. After the transaction is completed, the interaction
identifier can be used to get the transaction identifier. The transaction
identifier can then be used to get the full transaction and receipt details.
For more information, see Receiving Transaction Responses Asynchronously.
Generating a Bearer Token for Authentication
This section describes how to generate a bearer token for authentication. A unique bearer
token is required to authenticate each payment transaction request when the app is in
Cloud mode.
Generating a Bearer Token for Authentication
You must generate a new bearer token before sending each transaction request.
Follow these steps to generate a bearer token:
Create a P12 certificate for the transacting merchant ID (MID).
Construct a message using a JSON web Token (JWT) by following the steps shown
in
Use the JWT as the bearer token to authenticate the payment transaction request.
Processing a Sale
This section describes how to process a sale transaction when the app is in Cloud mode.
This transaction combines an authorization and a capture into a single transaction.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Refund
This section describes how to process a refund when the app is in Cloud mode. This type of
refund includes a reference to the original transaction for a full or partial
transaction amount. Stand-alone credits are also supported in this Acceptance Devices
solution. For more information, see Processing a Stand-Alone Credit.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Stand-Alone Credit
This section describes how to process a stand-alone credit in Cloud mode. This type of
transaction is used to process a credit without reference to the original transaction.
The customer is required to present their card for this type of transaction.
WARNING
When processing a stand-alone credit, there is no limit on the credit
amount because there is no reference to the original transaction amount. The
recommendation is to use a refund whenever possible. For more information, see Processing a Refund.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Requesting a Check Transaction Status
This section describes how to request a check transaction status in Cloud mode. This
transaction is used to obtain response data for a transaction that was lost or timed
out.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Sale with On-Reader Tipping
This section describes how to process a sale with on-reader tipping in Cloud mode. At the
start of each transaction, the Android device prompts the customer to add a tip by
showing suggested tip amounts. The customer selects or enters a tip amount on the
Android device before presenting their payment card.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Pre-Authorization
This section describes how to process a pre-authorization for an initial amount in Cloud
mode. A pre-authorization transaction places a temporary hold on the customer's payment
card, which can be captured at a later time.
Most authorizations expire in 5 to 7 days. The issuing bank sets the length of time
before expiration. When an authorization expires with the issuing bank, your bank or
processor might require you to re-submit an authorization request and include a request
for capture in the same message.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing an Incremental Authorization
This section describes how to process an incremental authorization in Cloud mode. This
type of request can be made on a pre-authorization transaction to increase the
authorized amount before it is captured.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Capture
This section describes how to capture a pre-authorized transaction in Cloud mode. The
capture request references the approved pre-authorization request.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Sale with Installment Details
This section describes how to process a sale transaction with installment details when
the app is in Cloud mode. This type of transaction can be used to include the required
installment details as part of the sale transaction.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Sale with Payment Facilitator Details
This section describes how to process a sale transaction with payment facilitator details
when the app is in Cloud mode. This type of transaction can be used to include the
required payment facilitator details as part of the sale transaction.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Sale with Tax Details
This section describes how to process a sale transaction with tax details when the app is
in Cloud mode. This type of transaction can be used to include the required tax details
as part of the sale transaction.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Receiving Transaction Responses Asynchronously
This section describes how to receive transaction responses asynchronously when the app
is in Cloud mode. For information about a follow-on service for this type of request,
see Processing a Check Transaction Events.
POST
https://terminalstest.cybersource.com/v1/cloud/transactions/async
Production:
POST
https://terminals.cybersource.com/v1/cloud/transactions/async
Receiving Transaction Responses Asynchronously
Asynchronous endpoints can be used to receive transaction responses for most types of
transaction requests when the app is in Cloud mode.
Follow these steps to receive transaction responses asynchronously:
Use the asynchronous endpoints shown in the example to process a transaction
and receive an interaction identifier. The example shows how to process a sale
asynchronously.
After the transaction is completed, use the interaction identifier returned in
the response to check the transaction events and to get a transaction
identifier.
Use the transaction identifier to process a Check Transaction Status request.
The response will contain full transaction and receipt details. For more
information, see Requesting a Check Transaction Status.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Processing a Check Transaction Events
This section describes how to process a Check Transaction Events request when the app is
in Cloud mode. This type of request is a follow-on service for receiving transaction
responses asynchronously. For more information, see Receiving Transaction Responses Asynchronously.
The GET request must include the interaction identifier
(
interactionId
).
Test:
GET
https://terminalstest.cybersource.com/v1/cloud/interactions/{interactionId}/events
Production:
GET
https://terminals.cybersource.com/v1/cloud/interactions/{interactionId}/events
Required Fields for Processing a Check Transaction Events
The body of the API request is empty. The GET request must include the information
required to return the response. If you want to receive only the latest transaction
event, set a query parameter of
limit=1
.
REST Example: Processing a Check Transaction Events
Request
The body of the request is empty. The GET request includes the information required
to return the response.
If the request is unsuccessful, you will receive an error response with details.
{
"type": "ErrorResponse",
"message": "Error message to display.",
"developerDescription": "Detailed description of error."
}
Standalone Mode Payment Services
This section describes how to process payment services featured in the Acceptance Devices
app when operated in Standalone mode.
These are some benefits of using Standalone mode:
Start transactions directly from the Android device.
Quickest way to start accepting transactions.
Does not require integration with a point-of-sale (POS) system.
Can be used as a back-up option for accepting payments when your POS system is
unavailable to operate in Local or Cloud semi-integrated modes.
IMPORTANT
When the Acceptance Devices app is operating in Standalone mode, the
Android device does not communicate with your POS system to share transaction details.
You are responsible for managing transaction reconciliation with your systems and
records.
For information about other modes available in the Acceptance Devices app, see:
Enabling Standalone Mode in the Acceptance Devices App
Follow these steps to enable Standalone mode in the Acceptance Devices
app:
In the Acceptance Devices app, tap
Settings
.
Enter your Acceptance Devices app passcode.
Tap
Standalone Mode
.
Toggle Enable Standalone Mode to
ON
.
Choose the currency in which you want to process transactions. Tap
Save
.
If you want to enable custom merchant reference codes, toggle Custom
Transaction Reference to
ON
.
Tap the back navigation arrow to return to the home screen. You can now process
transactions in Standalone mode.
Processing a Sale
This section describes how to process a sale transaction when the app is in
Standalone mode. This type of transaction combines an authorization and a capture
into a single transaction.
Follow these steps to process a sale transaction:
In the Acceptance Devices app, tap
Sale
.
Enter the transaction amount.
Tap
Submit
to start the transaction.
Processing a Refund
This section describes how to process a refund when the app is in Standalone mode.
This type of refund includes a reference to the original transaction for a full or
partial transaction amount.
Stand-alone credits are also supported in this Acceptance Devices solution. For more
information, see Processing a Stand-Alone Credit.
Follow these steps to process a refund:
In the Acceptance Devices app, tap
Settings
.
Enter your Acceptance Devices app passcode.
Tap
Transaction History
.
Tap the transaction you want to refund.
Tap
Refund
.
Enter the transaction amount.
Tap
Refund
to start the transaction.
Processing a Stand-Alone Credit
This section describes how to process a stand-alone credit when the app is in
Standalone mode. This type of transaction is used to process a credit without
reference to the original transaction. The customer must present their payment card
for this type of transaction.
WARNING
When processing a stand-alone credit, there is no limit on the credit amount
because there is no reference to the original transaction amount. The
recommendation is to use a refund transaction whenever possible. For more
information, see Processing a Refund.
Follow these steps to process a stand-alone credit:
In the Acceptance Devices app, tap
Other
Transactions
.
Tap
Refund
.
Enter your Acceptance Devices app passcode.
Enter the transaction amount.
Tap
Submit
to start the transaction.
Processing a Sale with On-Reader Tipping
This section describes how to process a sale with on-reader tipping in Standalone
mode. At the start of each transaction, the terminal prompts the customer to add a
tip by showing suggested tip amounts. The customer selects or enters a tip amount on
the terminal before presenting their payment card.
Follow these steps to process a sale with on-reader tipping:
In the Acceptance Devices app, tap
Settings
.
Enter your Acceptance Devices app passcode.
Tap
Standalone Mode
.
Toggle Ask for Tip to
ON
.
Tap the back navigation arrow to return to the home screen.
Tap
Sale
.
Enter the transaction amount.
Tap
Submit
to start the transaction.
Processing a Pre-Authorization
This section describes how to process a pre-authorization for an initial amount in
Standalone mode. A pre-authorization transaction places a temporary hold on the
customer's payment card, which can be captured at a later time.
Most authorizations expire in 5 to 7 days. The issuing bank sets the length of time
before expiration. When an authorization expires with the issuing bank, your bank or
processor might require that you re-submit an authorization request and include a
request for capture in the same message. For more information, see Processing a Capture.
Follow these steps to process a pre-authorization:
In the Acceptance Devices app, tap
Other
Transactions
.
Tap
Pre-Authorization
.
Enter the transaction amount.
Tap
Submit
to start the transaction.
Processing a Capture
This section describes how to capture a pre-authorized transaction in Standalone
mode. The capture request references the approved pre-authorization request.
Follow these steps to process a capture:
In the Acceptance Devices app, tap
Settings
.
Enter your Acceptance Devices app passcode.
Tap
Transaction History
.
Tap the transaction that you want to capture.
Tap
Capture
.
Enter the transaction amount.
Tap
Capture
to start the transaction.
Processing a Sale with Installment Details
This section describes how to process a sale transaction with installment details
when the app is in Standalone mode. This type of transaction can be used to include
the required installment details as part of the sale transaction.
This transaction is available only in the Latin American and Caribbean (LAC)
region.
Follow these steps to process a sale transaction with installment details:
In the Acceptance Devices app, tap
Settings
.
Enter your Acceptance Devices app passcode.
Tap
Standalone Mode
.
Tap
Installment Details
.
Toggle Enable Installment Details to
ON
.
Configure the installment details.
Tap the back navigation arrow to return to the home screen.
Tap
Sale
.
Enter the transaction amount.
Tap
Submit
to start the transaction.
Processing a Sale with Tax Details
This section describes how to process a sale transaction with tax details when the
app is in Standalone mode. This type of transaction can be used to include the
required tax details as part of the sale transaction.
Follow these steps to process a sale transaction with tax details:
In the Acceptance Devices app, tap
Settings
.
Enter your Acceptance Devices app passcode.
Tap
Standalone Mode
.
Tap
Tax Details
.
Toggle Enable Tax Details to
ON
.
Configure the tax details.
Tap the back navigation arrow to return to the home screen.
Tap
Sale
Enter the transaction amount.
Tap
Submit
to start the transaction.
Emailing a Customer Receipt
This section describes how to email a customer receipt from a previous transaction
when the app is in Standalone mode.
Follow these steps to email a customer receipt:
In the Acceptance Devices app, tap
Settings
.
Enter your Acceptance Devices app passcode.
Tap
Transaction History
.
Tap the transaction for which you want to email the receipt.
Tap
Send Receipt
.
Release Notes for Tap to Pay on Android Acceptance Devices App
These release notes are organized by release name and version, from newest to oldest.
Each release note includes these details:
Name of release
Type of release: app or SDK
Version number
Operating system: Android or iOS
Release date: DD-MM-YYYY format
These are the types of release notes published:
General information
Improvements
New features
Fixed issues
Updated requirements
Security updates
Hot fixes
Acceptance Devices App Version 1.15.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.15.0 for Android, which is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 08-21-2025.
New Features
Added the ability to configure the transaction history to show all transactions
from the merchant or show only transactions from the device.
Added the ability to customize user interface parameters.
Improvements
Updated the SDK version to 2.103.1.
Fixed Issues
Tap to Pay: Fixed the issue that caused the app to occasionally crash after installing
the Tap to Pay Ready app during the activation process.
Acceptance Devices App Version 1.14.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.14.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices
App. The release date is 07-07-2025.
New Features
Tap to Pay: The solution is now PCI-MPoC compliant, which requires the Tap to Pay Ready
app to be installed on the Android devices used to process transactions. After upgrading
to this version of the Acceptance Devices app, re-enroll your devices.
Improvements
Tap to Pay: The process used to select the currency in Standalone mode is now
automated and based on the merchant configuration.
Updated the SDK version to 2.102.0.
Acceptance Devices App Version 1.13.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.13.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices
App. The release date is 06-18-2025.
Improvements
Improved the reconnect mechanism when using the app in Cloud mode.
Updated the SDK version to 2.101.1.
Acceptance Devices App Version 1.12.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.12.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 05-13-2025.
Improvements
Updated the UI to use Google Material Design 3.
Updated the SDK version to 2.100.0.
Archive of Release Notes
This archive of release notes for the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App is organized by release name and version, from newest to
oldest. For more information, see the current release notes.
Each release note includes these details:
Name of release
Type of release: app or SDK
Version number
Operating system: Android or iOS
Release date: MM-DD-YYYY format
These are the types of release notes published:
General information
Improvements
New features
Fixed issues
Updated requirements
Security updates
Hot fixes
Acceptance Devices App Version 1.11.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.11.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 04-14-2025.
Improvements
Improved the experience when using the app with the Arabic language.
Tap to Pay: Improved the error messages that can appear during enrollment.
Updated the SDK version to 2.99.0.
Fixed Issues
Fixed the issue that caused the language not to change correctly when switching to Arabic.
Acceptance Devices App Version 1.10.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.10.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 03-05-2025.
New Features
Added Arabic as a supported language.
Improvements
Tap to Pay: Improved the device enrollment experience by removing the need to
provide an International Mobile Equipment Identity (IMEI) number. After upgrading to
Acceptance Devices app version 1.10.0, devices must be re-enrolled.
Updated the SDK version to 2.98.0.
Acceptance Devices App Version 1.9.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.9.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 02-03-2025.
New Features
Added the ability to print a customer or merchant receipt when using a terminal with an
integrated printer.
Improvements
Tap to Pay: Added a device requirements screen during the set-up process.
Improved the validation process when entering an activation code so that it accepts only 8 characters.
Improved the app behavior when attempting to access transaction history when the internet connection is not available.
Improved the reconnect mechanism when using the app in Cloud mode.
The mid-transaction status updates now indicate if the current transaction can be
cancelled.
Updated the SDK version to 2.97.0.
Acceptance Devices App Version 1.8.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.8.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 10-31-2024.
Improvements
Updated the SDK version to 2.95.0.
Fixed Issues
Fixed the issue that caused today's transactions to not appear in the transaction history if the end date was manually set to
Today
.
Acceptance Devices App Version 1.7.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.7.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 09-30-2024.
New Features
Added the ability to provide these details when performing a transaction:
Payment facilitator details.
Tax details.
Installment details for the Latin America and Caribbean (LAC) region.
Added support for additional languages in the Acceptance Devices app.
Acceptance Devices app can now be used with Tap to Pay.
Improvements
Updated the SDK version to 2.94.0.
Fixed Issues
Fixed the issue that caused the Acceptance Devices app to crash when an unsupported
character was entered during activation code entry.
Fixed the issue that caused the Print Receipt button to appear on the Summary screen
of devices without a printer.
Acceptance Devices App Version 1.6.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.6.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is
07-22-2024.
Improvements
Acceptance Devices app server now provides the full certificate chain for TLS.
Transaction summary reports can now show multiple currencies.
Improved the UI on several screens.
Improved the WebSocket connection handling.
Updated the SDK version to 2.92.0.
Acceptance Devices App Version 1.5.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.5.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 06-25-2024.
New Features
Added the option to set a custom merchant reference code for transactions when the
Acceptance Devices app is in Standalone mode.
Signature capture type can now be set to
NONE
to skip signature
capture.
Added support for the Oracle Payment Interface.
Improvements
PAX IM30: Settings button is now hidden.
Settings menu now has an idle timeout of 2 minutes for the PAX IM30 and 5 minutes
for all other supported PAX devices.
Status notification now indicates when a device is operating in Standalone
mode.
Updated the SDK version to 2.91.0.
Fixed Issues
Fixed the issue that caused POS Setup to fail when you attempt set up again after
canceling.
Fixed the issue that caused Offline mode not to be shown when the Acceptance Devices
app is in Cloud with Standalone mode.
PAX A35: Fixed the issue that caused some text in the transaction summary report to
not display correctly.
Acceptance Devices App Version 1.4.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.4.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 05-29-2024.
New Features
Added support for PAX IM30 and PAX A920 MAX devices.
Added support for asynchronous responses for transactions when the Acceptance
Devices app is in Cloud mode.
Improvements
Updated the SDK version to 2.90.0.
Fixed Issues
Fixed the issue that rarely caused the app to crash when an invalid request was
attempted.
Fixed the issue that caused null receipt fields to be shown in the response when
processing an offline transaction.
Acceptance Devices App Version 1.3.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.3.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 04-23-2024.
New Features
Acceptance Devices App now supports:
Offline transactions (also known as
deferred authorization
or
store
and forward
) in Local and Standalone modes
On-receipt tipping in Local mode
Cloud mode
Transaction summary reports
Improvements
Added support for TLS v1.3.
Removed support for TLS v1.0 and TLS v1.1.
Updated the SDK version to 2.88.0.
Fixed Issues
Fixed the issue that caused the transaction history not to display transactions when
the PAX terminal was set to certain time zones.
PAX A35 terminal: Fixed the issue that caused the Acceptance Devices app not to
auto-start.
Acceptance Devices App Version 1.2.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.2.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 01-31-2024.
Improvements
Capture API requests now return
CaptureResponse
in the
Type
field.
If there is no internet access, the Start Server button is not
available in the Acceptance Devices app.
Improved the responsiveness of the Settings menu.
Updated the SDK version to 2.86.
Fixed Issues
Fixed the issue that caused the Acceptance Devices app to crash occasionally
when starting a transaction from the background.
On the Enter Amount screen, fixed the issue that caused the Backspace key to not
work properly for some keyboard settings.
On the PAX A35 terminal, fixed the issue that caused the green and red physical
buttons to be ignored on the Passcode screen.
Fixed the issue that caused authentication to fail after
reactivation when operating in Standalone mode.
Acceptance Devices App Version 1.1.0 Release Notes
These release notes are for the Acceptance Devices app, version 1.1.0 for Android, which
is used in the PAX Acceptance Devices App and Tap to Pay on Android Acceptance Devices App. The release date is 12-22-2023.
New Features
Acceptance Devices protocol:
The Acceptance Devices app features the new,
streamlined Acceptance Devices protocol. This protocol replaces the ATICA
(ISO20022) protocol and is the default integration method for the PAX Acceptance Devices App.
WebSockets support:
The Acceptance Devices app now supports WebSockets,
enabling a two-way connection between the point-of-sale (POS) system and the
terminal.
Standalone mode:
A new standalone operating mode was added to the
Acceptance Devices app. This mode enables merchants to enter transaction amounts
directly on the terminal.
Transaction history:
Merchant transaction history is now accessible from
the Settings menu in the Acceptance Devices app. This feature includes quick
filtering options and linked operations.