# Tap to Pay - Android

## **Introduction** <a href="#introduction" id="introduction"></a>

### **Purpose** <a href="#purpose" id="purpose"></a>

This document references all the features and an Android integration guide for Sola Tap to Pay.

&#x20;

**We’ll cover:**

* Tap to Pay Application Overview
* How do you install the Tap to Pay application on your Android device?
* How to integrate a third-party merchant application with the Sola Tap to Pay application

### **Scope** <a href="#scope" id="scope"></a>

This document is for Android developers looking to integrate the Sola Tap to Pay Helper application into their existing Android mobile app or web application.

***

&#x20;

## **Overview of Tap to Pay Helper Mobile App** <a href="#overview-of-tap-to-phone-helper-mobile-app" id="overview-of-tap-to-phone-helper-mobile-app"></a>

### **About** <a href="#about" id="about"></a>

Tap to Pay allows merchants to accept payments using their mobile devices without an external terminal. Tap to Pay is a service application that will work only if the transaction is requested from other third-party merchant applications.

It offers deep link identities to third-party merchant applications to seamlessly integrate to fulfill their payment needs.

**Requirements**:

* Operating system of Android OS 10(Q) or later
* An Android device with NFC capabilities
* An Android device that is not rooted
* Android Device Settings:
  * Enable NFC and Contactless Payments settings
  * Disable Developer Options and USB Debugging settings
* Enable “Tap to Pay” within the Device Configuration settings within the Sola[ Mobile App](https://play.google.com/store/apps/details?id=com.gateway.cardknox.android\&hl=en_US\&gl=US)

### **How to use Tap to Pay with the Sola Android App** <a href="#how-to-use-tap-to-phone-with-the-cardknox-android-app" id="how-to-use-tap-to-phone-with-the-cardknox-android-app"></a>

* **Enable the Tap to Pay Feature:**
  * Open the Sola [Android App](https://play.google.com/store/apps/details?id=com.gateway.cardknox.android).
  * Navigate to Settings -> Device Configuration
  * Select Tap to Pay.
* **Install the Tap to Pay Helper App:**
  * When prompted, install the [Tap to Pay Helper app](https://play.google.com/store/apps/details?id=com.cardknox.tap.prod\&pli=1).
* **Activate Tap to Pay:**
  * Once the Tap to Pay helper app is installed, return to the Sola App and enable Tap to Pay.

### **How to install Tap to Pay using the Google Play Store** <a href="#how-to-install-tap-to-phone-using-the-google-play-store" id="how-to-install-tap-to-phone-using-the-google-play-store"></a>

Download the Tap to Pay Helper application from the [Google Play Store](https://play.google.com/store/apps/details?id=com.cardknox.tap.prod\&pli=1).&#x20;

&#x20;

***

## **Deep Linking** <a href="#deep-linking" id="deep-linking"></a>

The deep linking feature allows a third-party application to use a predefined URL to open up the pre-installed Tap to Pay Helper mobile application to process a payment transaction.

The Tap to Pay Helper app will use the “`xRedirectUrl`” parameter to deliver the transaction results to the third-party application. Results are provided as query parameters, appended onto the value provided by the `xRedirectUrl` parameter.

The Tap to Pay Helper application's predefined URL is:

`cardknox://tap.cardknox.com/transaction`

&#x20;

***

&#x20;

## **Supported Transaction Workflows**  <a href="#supported-transaction-workflows" id="supported-transaction-workflows"></a>

Tap to Pay Helper mobile application supports three (3) different transaction workflows.

1. **Encrypted Payload** – The third-party application will request the encrypted payload from the Tap to Pay helper application. To complete the transaction, send the server-side payload and other returned data to the Sola API. (see server-side transaction example)

| **Parameters**                               | **Required** | **Possible Values** | **Description**                                                                                                                                                               |
| -------------------------------------------- | ------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **xCommand**                                 | Yes          | cc:encrypt          | If you send the xCommand value as `cc:encrypt`, the Tap to Pay helper will use the ‘Encrypted Payload’ workflow and return the encrypted payload in the transaction response. |
| <p><strong>xRedirectURL</strong></p><p> </p> | Yes          |                     | A valid URL scheme defined inside the third-party application to receive transaction responses from the ‘Tap to Pay’ helper application                                       |

&#x20;

&#x20;

2. **Single Use Token (SUT)** – The merchant application will request a “Single Use Token” instead of the encrypted payload from the Tap to Pay helper application. Then, send the SUT and other returned data to the Sola API to complete the transaction.

   &#x20;

| **Parameters**                               | **Required** | **Possible Values** | **Description**                                                                                                                                                             |
| -------------------------------------------- | ------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **xCommand**                                 | Yes          | cc:singleusetoken   | If you send the xCommand value as `cc:singleusetoken`, the Tap to Pay helper will use the “Single Use Token (SUT)” workflow and return the SUT in the transaction response. |
| <p><strong>xRedirectURL</strong></p><p> </p> | Yes          |                     | A valid URL scheme defined inside the third-party application to receive transaction responses from the ‘Tap to Pay’ helper application                                     |

&#x20;

&#x20;

3. **Complete Transaction** – With this workflow, the Tap to Pay helper application processes the complete transaction and returns the gateway response to the third-party application.

&#x20;

| **Parameters**                                                                  | **Required** | **Possible Values**                      | **Description**                                                                                                                         |
| ------------------------------------------------------------------------------- | ------------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **xCommand**                                                                    | Yes          | cc:sale, cc:save, cc:authonly, cc:credit | Sola transaction type                                                                                                                   |
| **xKey**                                                                        | Yes          |                                          | Your Sola API key                                                                                                                       |
| <p><strong>xRedirectURL</strong></p><p> </p>                                    | Yes          |                                          | A valid URL scheme defined inside the third-party application to receive transaction responses from the ‘Tap to Pay’ helper application |
| [**\*Any ‘Cardknox API’ parameter**](https://docs.cardknox.com/api/transaction) |              |                                          |                                                                                                                                         |

&#x20;

***

&#x20;

## **Transaction Parameters** <a href="#transaction-parameters" id="transaction-parameters"></a>

Two types of parameters are supported by the Tap to Pay helper application.

1. **Transaction API Specific** – Use any Sola API parameters in the deep-link request. [See Transaction API documentation](/api/transaction.md). However, the below API parameters must be **carefully designed** to achieve the desired transaction result using the Tap to Pay helper.

&#x20;

&#x20;

| **Parameter** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xRedirectURL  | A valid URL scheme defined inside the third-party application to receive transaction responses from the ‘Tap to Pay’ helper application                                                                                                                                                                                                                                                                                                  |
| xCommand      | <p>This parameter is utilized to indicate the specific type of transaction that needs to be executed (cc:sale, cc:refund, cc:void, etc.).</p><p>One caveat is that this must be defined as <code>cc:encrypt</code> for the  ‘Encrypted Payload’ workflow or <code>cc:singleusetoken</code> for the ‘Single-Use-Token’ workflow.</p><p>For the ‘Complete Transaction’ workflow, you can pass the usual Sola-specific xCommand values.</p> |

&#x20;

***

### **Development and Debugging** <a href="#development-and-debugging-hardbreak-hardbreak" id="development-and-debugging-hardbreak-hardbreak"></a>

**Tap to Pay Development/Debugging Parameters** – These are defined to troubleshoot issues quickly during the development phase.

The following is the list of Tap to Pay specific parameters that can be passed, along with the BBPOS Specific parameters, by the third-party merchant application in the deep link query string.

&#x20;

| **Parameter** | **Description**                                                                                                 | **Possible Values** | **Default Value** |
| ------------- | --------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------- |
| debug         | Set to TRUE to display logs in the Tap to Pay helper application.                                               | TRUE/FALSE          | FALSE             |
| useSTG        | <p>This enables a staging gateway environment. Applicable only for ‘Complete Transaction’ workflow.</p><p> </p> | TRUE/FALSE          | FALSE             |
| doNotRedirect | Disables the redirect URL and displays the results/logs within the Tap to Pay helper app.                       | TRUE/FALSE          | FALSE             |

&#x20;

*All ‘debugging’ parameters are optional.*

&#x20;

***

&#x20;

## **How to Integrate Tap to Pay with Third-Party Android Applications** <a href="#how-to-integrate-tap-to-phone-with-third-party-android-applications" id="how-to-integrate-tap-to-phone-with-third-party-android-applications"></a>

### How to Setup Deeplink URL <a href="#how-to-setup-deeplink-url" id="how-to-setup-deeplink-url"></a>

Third-party merchant app developers can form URLs based on different transaction needs. Tap to Pay helper app will not cache any third-party request in the mobile application storage, and it's entirely driven by the transaction request passed through the deep link request.

&#x20;

Example of a deep link URL:

`cardknox://tap.cardknox.com/transaction?`**`xRedirectURL`**`=mechant://pos.merchant.com/&`**`xKey`**`=XXXXXW23243HHDFJ&`**`xEmail`**`=test@merchant.com&`**`xAmount`**`=12.00&`**`xTip`**`=1.0&`**`xCommand`**`=cc:sale&`**`debug`**`=True&`**`useSTG`**`=True&x`**`AllowPartialAuth`**`=true`

&#x20;

Note that the above URL is corresponding to the “Complete Transaction” workflow since xKey is provided

&#x20;

Example of a deep link request, corresponding to the transaction response:

`mechant://pos.merchant.com?`**xResult**`=D&`**xStatus**`=Declined&`**xError**`=Invalid%20Chip&`**xRefNum**`=102304545&`**xErrorCode**`=2034`

&#x20;

The below response parameters and their explanations in the context of Tap to Pay helper.

&#x20;

| **Parameter**     | **Description**                                                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xEncryptedPayload | <p>This will contain the encrypted payload or single-use token if the transaction workflow is requested as an ‘encrypted payload’ or ‘single-use token’.</p><p> </p> |
| xSerialNumber     | This will contain the rock value, that’s needed to perform the gateway request when the workflow is requested as ‘Encrypted Payload’ or ‘Single-Use-Token’.          |
| xStatus           | This will be a success or error when the workflow is requested as ‘Encrypted payload’ or ‘Single-Use-Token’. Containing the standard Sola gateway response values.   |
| xCommand          |                                                                                                                                                                      |

&#x20;

You can refer to the [API documentation](/api/transaction.md) for other response parameter definitions.

### **How to create a server-side call:** <a href="#how-to-create-a-server-side-call" id="how-to-create-a-server-side-call"></a>

When running the server-side call to Sola, you must use the standard required API parameters. Reference the [Transaction API](/api/transaction.md) for a list of parameters.

Additionally, the following parameters are required:

| **Parameter**  | **Description**                                                       | **Example**                                                                                          |
| -------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| xSerialNumber  | The serial number value returned from the payload.                    | alP4n4-\_92UPrgVI                                                                                    |
| xMobileTapType | Must equal to ‘TapToPhoneApp’                                         | TapToPhoneApp                                                                                        |
| xEMVData       | Pass the value of the returned encrypted payload (xEncryptedPayload). | AAABBgAAABgAAAAAAAABHgAAAIYAAAEeAQAAAAH\_htzImhOJfEQlhxhrJsYZttThXPsWFZgUTYwxmxqaxdOXYnCvfoATExUgJb… |

&#x20;

### Server-side Request Example: <a href="#server-side-request-example" id="server-side-request-example"></a>

```
{
  "xKey": "dxxxcaxaxfxxfxxxxxxdxxcxcxfaax",
  "xCommand": "cc:sale",
  "xVersion": "4.5.9",
  "xSoftwareVersion": "1.0.12",
  "xAmount": "1.08",
  "xSoftwareName": "My Application ",
  "xEMVdata": "AAABBgAAABgAAAAAAAABHgAAAIYAAAEeAQAAAAH_htzImhOJfEQlhxhrJsYZttThXPsWFZgUTYwxmjxPBLLhkxwPcVZACZGDIntDDasmtAxxBWxxn_eAxlUbNxxAxxWtR",
  "xSerialNumber": "alN4n4-_92UPrgVI",
  "xMobileTapType": "TapToPhoneApp"
}
```

&#x20;

### **How to call a Deep Link URL to Invoke the Tap to Pay Helper Application** <a href="#how-to-call-a-deep-link-url-to-invoke-the-tap-to-phone-helper-application" id="how-to-call-a-deep-link-url-to-invoke-the-tap-to-phone-helper-application"></a>

Once the deep link URL is formed, you can create an intent using the formed deep link URL and start the activity using the intent.

Thus Tap to Pay Helper application will be launched and start the workflow. Once the requested operations are complete, the result will be returned using the xRedirectUrl as well.&#x20;

&#x20;

Here’s an example snippet of code to invoke the creation:

```
Uri myAction = Uri.parse(deepLinkUrl); 
// deepLinkUrl must be a string variable holding the deep link URL with all required parameters.
Intent intent = new Intent (Intent.ACTION_VIEW);
intent.setData (myAction);
startActivity(intent);
```

&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.solapayments.com/products/tap-to-pay-android.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.