Acceptance Devices \| Tap to Pay on iPhone Acceptance Devices App {#ttp-iphone-ad-app-about-guide}
==================================================================================================

Use the information to navigate this guide and find further information.

Audience and Purpose
--------------------

This guide is written for partner developers, system architects, and independent software vendors (ISVs) who wish to use the Tap to Pay on iPhone Acceptance Devices App in Standalone mode.  
Implementing the Tap to Pay on iPhone Acceptance Devices App in Standalone mode does not require integration with your point-of-sale system, and transactions can be started directly on an iPhone. However, some tasks described in this guide, such as generating an activation code or customizing app settings using a REST API, require software development skills.

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:  
<http://support.visaacceptance.com>

Recent Revisions to This Document {#ttp-iphone-ad-app-doc-revisions}
====================================================================

26.08.01
--------

:
Initial release.

Introduction to Acceptance Devices \| Tap to Pay on iPhone Acceptance Devices App {#ttp-iphone-ad-app-intro}
============================================================================================================

The Tap to Pay on iPhone Acceptance Devices App operates in Standalone mode.  
These are some benefits of using Standalone mode:

* The solution provides a fast way to begin accepting contactless payments.
* There is no requirement for integration with your point-of-sale (POS) system.
* You can start transactions directly on a compatible iPhone.

{#ttp-iphone-ad-app-intro_ul_iphone_standalone_benefits} IMPORTANT When the Tap to Pay on iPhone Acceptance Devices App is operating in Standalone mode, the iPhone does not communicate with your POS system to exchange transaction details. You are responsible for reconciling transactions with your internal systems and records.

Compatibility Requirements for iPhones {#ttp-iphone-ad-app-device-reqs}
=======================================================================

To accept contactless payments in the Tap to Pay on iPhone Acceptance Devices App, your iPhone must be compatible with the app.  
These are the requirements for a compatible iPhone:

* iPhone model XS or later.
* iOS version that is less than 1 year old. The recommendation is to use the latest iOS version available.
  {#ttp-iphone-ad-app-device-reqs_ul_iphone_device_reqs}

Getting Started with the Acceptance Devices App {#ttp-iphone-ad-app-get-started-intro}
======================================================================================

Use the information to start using the Acceptance Devices app. You can process payments after setting up the device and configuring the app.

Set Up an iPhone {#ttp-iphone-ad-app-setup-device}
==================================================

Before setting up an iPhone, download and install the [Acceptance Devices app](https://apps.apple.com/us/app/acceptance-devices/id6736790881 "") from the Apple App Store. Follow these steps to set up an iPhone in the Acceptance Devices app:

1. Open the Acceptance Devices App on an iPhone.

2. On the Welcome screen, tap Start Configuration. The app is configured to use the production environment. To switch to the test environment, press and hold the Welcome screen for 5 seconds. The Select Environment screen appears. Choose an environment for configuration.  
   ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/tap-to-pay-iphone-ad-app/images/ttp-iphone-ad-app-setup-welcome-450x960.png/jcr:content/renditions/original)

3. On the Create 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's settings menu, so choose a code that you will remember.  
   ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/tap-to-pay-iphone-ad-app/images/ttp-iphone-ad-app-setup-passcode-450x960.png/jcr:content/renditions/original)

4. If the Connect to the Internet screen appears, tap Connect to the internet, then choose an internet connection option.  
   ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/tap-to-pay-iphone-ad-app/images/ttp-iphone-ad-app-setup-connect-450x960.png/jcr:content/renditions/original)

5. If the Internet Connected screen appears, tap Continue.  
   ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/tap-to-pay-iphone-ad-app/images/ttp-iphone-ad-app-setup-connect-confirm-450x960.png/jcr:content/renditions/original)

   #### ADDITIONAL INFORMATION

You are prompted to activate your iPhone in the Acceptance Devices app.

Activating an iPhone in the Acceptance Devices App {#ttp-iphone-ad-app-activate-terminal-intro}
===============================================================================================

Before you can process payments on your iPhone using the Acceptance Devices app, you must use an activation code to activate the 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 enter it in the Acceptance Devices app.

Generate an iPhone Activation Code in the `Business Center` {#ttp-iphone-ad-app-activation-code-ebc}
====================================================================================================

Before activating an iPhone in the Acceptance Devices app, you must generate a device activation code. The code is valid for 24 hours.  
Follow these steps to generate an iPhone activation code in the `Business Center`:

1. In the `Business Center`, go to the left navigation panel and choose Acceptance Devices **\&gt;** Activation Codes. The Activation Codes page appears.
2. Click the Select Transacting MID drop-down menu.
3. Choose a transacting MID from the list.
4. Click the Select number of Activation Codes drop-down menu.
5. Choose the number of activation codes that you want to generate. The maximum number of codes is 15.
6. Click Generate. The activation codes display on the page. To copy the codes to your clipboard, click the icon next to the code.
7. To download a text file containing the activation codes, click the Download codes as a .txt file button.
8. Navigate to the Download folder on your computer to access the text file.

Generating an iPhone Activation Code Using a REST API Request {#ttp-iphone-ad-app-activation-code-api-intro}
============================================================================================================

Before activating an iPhone in the Acceptance Devices app, you must generate a device activation code. The code is valid for 24 hours.  
Use this information to generate a device activation code using a REST API request.  
You must authenticate each request that you send to a `Cybersource` API. 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 [*Getting Started with REST Developer Guide*](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-intro.md "").

Endpoints
---------

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 to Generate an iPhone Activation Code {#ttp-iphone-ad-app-activation-code-api-reqfields}
========================================================================================================

The body of the API request is empty. The POST request must include the information required to return the response.

REST Example: Generate an iPhone Activation Code {#ttp-iphone-ad-app-activation-code-api-ex-rest}
=================================================================================================

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.

```
{
    "tokens": [
        {
            "token": "%N5wU2jH",
            "ttl": 86399805
        }
    ]
}
```

Enter an Activation Code in the Acceptance Devices App {#ttp-iphone-ad-app-enter-activation-code}
=================================================================================================

Before activating an iPhone, 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 in the Acceptance Devices app:

1. On the Terminal Activation screen, enter the activation code that you generated. Tap Continue. The Device Activated Successfully screen appears.  
   ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/tap-to-pay-iphone-ad-app/images/ttp-iphone-ad-app-activate-enter-code-450x960.png/jcr:content/renditions/original)  
   ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/tap-to-pay-iphone-ad-app/images/ttp-iphone-ad-app-activate-success-450x960.png)
2. When 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 about the device or solution. Tap Close.  
   ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/tap-to-pay-iphone-ad-app/images/ttp-iphone-ad-app-activate-assign-serial-num-450x960.png/jcr:content/renditions/original)

Customizing the Acceptance Devices App {#ttp-iphone-ad-app-customize-intro}
===========================================================================

Use this information to customize the Acceptance Devices app in the `Business Center` or by using a REST API request.  
The Acceptance Devices Customizations feature in the `Business Center` enables you to customize these parameters for a portfolio, merchant, or transacting merchant ID (MID):

* User interface

* Common

* Standalone mode
  {#ttp-iphone-ad-app-customize-intro_ul_iphone_customize_params}  
  You can 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, and Standalone mode parameters.
  {#ttp-iphone-ad-app-customize-intro_ul_iphone_customize_api}

Customizable User Interface Parameters {#ttp-iphone-ad-app-customize-ui}
========================================================================

You can customize these user interface parameters for the Acceptance Devices app when it is operating in Standalone mode.

Home screen logo
:
This parameter defines the logo that is shown on the home screen of the app.

Toolbar logo
:
This parameter defines the logo that is shown during transaction processing.

Primary color
:
This parameter defines the color of the primary buttons.

Color on primary
:
This parameter defines the color of the text on the primary buttons.

Background color
:
This parameter defines the color of the screen background.

Color on background
:
This parameter defines the color of the text on the screen background.

Button shape
:
This parameter defines the shape of the buttons.

Customizable Common Parameters {#ttp-iphone-ad-app-customize-common}
====================================================================

You can customize these common parameters for the Acceptance Devices app when it is operating in Standalone mode.

Operating mode
:
The Acceptance Devices app on iPhone solution operates in Standalone mode only. Other modes can be enabled for other Acceptance Devices solutions.

Tipping options
:
This parameter enables you to choose one of these tipping types:

    * `Percentage:` The customer chooses from three pre-defined tip percentages or enters a custom tip amount. Define the tip values in the Tipping percentage values parameter. This setting is the default tipping type.
    * `Tip amount:` The customer enters a custom tip amount.
    * `Total amount:` The customer enters the total amount to be charged, including the tip amount.
    {#ttp-iphone-ad-app-customize-common_ul_iphone_tipping_options}

Tipping percentage values
:
This parameter defines the three tipping percentage choices that appear on the screen for the customer to choose. This parameter applies only if the Tipping Type parameter is set to `Percentage`. The default settings are `10, 15, 20`.

Transaction history view
:
This parameter defines whether the transaction history view is shown at the merchant or device level. The default setting is `Merchant`.

Customizable Standalone Mode Parameters {#ttp-iphone-ad-app-customize-standalone}
=================================================================================

You can customize this Standalone mode parameter for the Acceptance Devices app.

Additional transaction types
:
This parameter enables you to choose additional transaction types that the app supports. Sale and refund transactions are supported by default. The default setting for additional transaction types is `None`.

Customize Parameters in the `Business Center` {#ttp-iphone-ad-app-customize-ebc}
================================================================================

Follow these steps to customize common and Standalone mode parameters for the Acceptance Devices app.

1. In the `Business Center`, go to the left navigation panel and choose Acceptance Devices **\&gt;** Customizations. The Customizations screen appears.
2. Click the Load customization parameter for drop-down menu.
3. Choose a user level from the list. Click Load.
4. Scroll down to see the various parameter sections and which elements are available to customize for the chosen user level.
5. Choose parameters to customize. To see a description of a parameter, hover your mouse over the Information icon.
6. Click Apply Changes.

Retrieve Parameters Using a REST API Request {#ttp-iphone-ad-app-customize-retrieve-param-api-intro}
====================================================================================================

You can use a REST API request to retrieve and view customizable parameters and their current values. Your account settings determine the values you can view for a portfolio, merchant, or transacting merchant ID (MID).  
You must authenticate each request that you send to a `Cybersource` API. 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 [*Getting Started with REST Developer Guide*](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-intro.md "").

Endpoints
---------

The GET request must include the organization ID for the portfolio, merchant, or transacting merchant ID that is sending the request.  
**Test:** `GET ``https://apitest.cybersource.com``/dms/v2/customization?type=organization&id={{organization id}}`  
**Production:** `GET ``https://api.cybersource.com``/dms/v2/customization?type=organization&id={{organization id}}`

Required Fields to Retrieve Parameters Using a REST API Request {#ttp-iphone-ad-app-customize-retrieve-param-reqfields}
=======================================================================================================================

The body of the API request is empty. The GET request must include the information required to return the response.

REST Example: Retrieve Parameters Using a REST API Request {#ttp-iphone-ad-app-customize-retrieve-param-api-ex}
===============================================================================================================

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

Customize Parameters Using a REST API Request {#ttp-iphone-ad-app-customize-param-api-intro}
============================================================================================

You can use a REST API request to update customizable parameters for a portfolio, merchant, or transacting merchant ID (MID).  
You must authenticate each request that you send to a `Cybersource` API. 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 [*Getting Started with REST Developer Guide*](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-intro.md "").

Endpoints
---------

The PUT request must include the organization ID for the portfolio, merchant, or transacting merchant ID that is sending the request.  
**Test:** `PUT ``https://apitest.cybersource.com``/dms/v2/customization`  
**Production:** `PUT ``https://api.cybersource.com``/dms/v2/customization`

Required Fields to Customize Parameters Using a REST API Request {#ttp-iphone-ad-app-customize-param-reqfields}
===============================================================================================================

type
:
Set the value to `organization`.

id
:
Set the value to `organization id` for the portfolio, merchant, or transacting MID.

customizations
:
Set the value to the parameters to be updated.

REST Example: Customize Parameters Using a REST API Request {#ttp-iphone-ad-app-customize-param-api-ex}
=======================================================================================================

Request

```
{
    "type": "organization",
    "id": "{{organization id}}",
    "customizations":
    {
        "OPERATING_MODE": "STANDALONE",
        "TIPPING_TYPE": "TIP_AMOUNT",
        "SIGNATURE_TYPE": "ON_RECEIPT"
    }
}
```

Response to a Successful Request  
The body of the response is empty. A successful response is indicated with a `200 OK` status.

```
{
}
```

Standalone Mode Payment Services {#ttp-iphone-ad-app-standalone-mode-intro}
===========================================================================

Use the information to process payment services in the Tap to Pay on iPhone Acceptance Devices App in Standalone mode.
IMPORTANT When the Tap to Pay on iPhone Acceptance Devices App is operating in Standalone mode, the iPhone does not communicate with your POS system to exchange transaction details. You are responsible for reconciling transactions with your internal systems and records.

Sale {#ttp-iphone-ad-app-standalone-mode-sale}
==============================================

Use the information to process a sale transaction when the app is operating in Standalone mode. This transaction combines an authorization and a capture into a single transaction.  
Follow these steps to process a sale transaction:

1. In the Acceptance Devices app, tap Sale.
2. Enter the transaction amount.
3. Tap Submit to start the transaction.

Refund {#ttp-iphone-ad-app-standalone-mode-refund}
==================================================

Use the information to process a refund when the app is operating 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 [Stand-Alone Credit](/docs/cybs/en-us/tap-to-pay-iphone-ad-app/integration/all/rest/tap-to-pay-iphone-ad-app/ttp-iphone-ad-app-standalone-mode-intro/ttp-iphone-ad-app-standalone-mode-standalone-credi.md "").  
Follow these steps to process a refund:

1. In the Acceptance Devices app, tap Settings.
2. Enter your Acceptance Devices app passcode.
3. Tap Transaction History.
4. Tap the transaction you want to refund.
5. Tap Refund.
6. Enter the transaction amount.
7. Tap Refund to start the transaction.

Stand-Alone Credit {#ttp-iphone-ad-app-standalone-mode-standalone-credit}
=========================================================================

Use the information to process a stand-alone credit when the app is operating in Standalone mode. This transaction is used to process a credit without reference to the original transaction. The customer must present their payment card.

> 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 [Refund](/docs/cybs/en-us/tap-to-pay-iphone-ad-app/integration/all/rest/tap-to-pay-iphone-ad-app/ttp-iphone-ad-app-standalone-mode-intro/ttp-iphone-ad-app-standalone-mode-refund.md "").  
> Follow these steps to process a stand-alone credit:

1. In the Acceptance Devices app, tap Other Transactions.
2. Tap Refund.
3. Enter your Acceptance Devices app passcode.
4. Enter the transaction amount.
5. Tap Submit to start the transaction.

Sale with On-Reader Tipping {#ttp-iphone-ad-app-standalone-mode-sale-tip}
=========================================================================

Use the information to process a sale with on-reader tipping when the app is in Standalone mode. At the start a 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:

1. In the Acceptance Devices app, tap Settings.
2. Enter your Acceptance Devices app passcode.
3. Tap Standalone Mode.
4. Toggle Ask for Tip to ON.
5. Tap the back navigation arrow to return to the home screen.
6. Tap Sale.
7. Enter the transaction amount.
8. Tap Submit to start the transaction.

Pre-Authorization {#ttp-iphone-ad-app-standalone-mode-pre-auth}
===============================================================

Use the information to process a pre-authorization for an initial amount when the app is in Standalone mode. A pre-authorization transaction places a temporary hold on the customer's payment card, which can be captured later.  
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 [Capture](/docs/cybs/en-us/tap-to-pay-iphone-ad-app/integration/all/rest/tap-to-pay-iphone-ad-app/ttp-iphone-ad-app-standalone-mode-intro/ttp-iphone-ad-app-standalone-mode-capture.md "").  
Follow these steps to process a pre-authorization:

1. In the Acceptance Devices app, tap Other Transactions.
2. Tap Pre-Authorization.
3. Enter the transaction amount.
4. Tap Submit to start the transaction.

Capture {#ttp-iphone-ad-app-standalone-mode-capture}
====================================================

Use the information to capture a pre-authorized transaction when the app is operating in Standalone mode. The capture request references the approved pre-authorization request.  
Follow these steps to process a capture:

1. In the Acceptance Devices app, tap Settings.
2. Enter your Acceptance Devices app passcode.
3. Tap Transaction History.
4. Tap the transaction that you want to capture.
5. Tap Capture.
6. Enter the transaction amount.
7. Tap Capture to start the transaction.

Email a Customer Receipt {#ttp-iphone-ad-app-standalone-mode-email-receipt}
===========================================================================

Use the information to email a customer receipt from a previous transaction when the app is operating in Standalone mode.  
Follow these steps to email a customer receipt:

1. In the Acceptance Devices app, tap Settings.
2. Enter your Acceptance Devices app passcode.
3. Tap Transaction History.
4. Tap the transaction for which you want to email the receipt.
5. Tap Send Receipt.