Cardknox is now Sola
Learn More
LogoLogo
Contact Us
  • Introduction
  • 🔗API
    • Transaction API
      • Credit Card
      • Check (ACH)
      • EBT
      • Gift Card
      • Fraud
    • Customer and Recurring API
    • Reporting API
    • Account Boarding API
      • Account Boarding Merchant Agreement
      • Account Boarding Swagger UI
    • Code Samples
    • Error Codes
  • 📦SDK
    • .NET SDK
      • Transaction Workflow
    • iOS SDK
      • iOS SDK - Technical Guide
      • Workflow
    • Android SDK
      • Android SDK - Technical Guide
  • 🧰 Cardknox Products
    • 3D Secure 2.0
      • Client-Side Integration
        • Client-Side Integration (Non-iFields)
      • Server-Side Integration
    • Account Updater
    • Batch Processing
    • Browser-Based POS systems (BBPOS)
    • CloudIM Developer Guide
    • Deep Linking
      • Deep Linking Integration for Third-Party Websites
    • EBT Online
    • Gateway Emulators
    • iFields
      • Angular iFields
    • Merchant Portal
      • FAQ
    • Mobile App
    • Split Capture
    • Tap to Phone - Android
    • Partner Portal
    • PaymentSITE
      • QR Codes for PaymentSITE
    • Webhooks
  • 📱Mobile Wallets
    • Apple Pay Hosted Checkout
      • Apple Pay Hosted Checkout Initial Setup
      • Apple Pay Prerequisites
      • Apple Pay Hosted Checkout Objects Reference (Request)
      • Apple Pay Hosted Checkout Objects Reference (Response)
      • Apple Pay iFields Integration
      • Apple Pay Hosted Checkout Sample Code
      • Apple Pay Features
      • Set up Apple Pay Merchant ID with Cardknox
    • Click-To-Pay - Hosted Checkout
      • Click-To-Pay Initial Setup
      • Click-To-Pay Sample Code
      • Click-To-Pay iFields Integration
      • Click-To-Pay Objects Reference (Request)
      • Click-To-Pay Objects Reference (Response)
    • Google Pay Hosted Checkout
      • Google Pay Control Object
      • Google Pay Request Objects
      • Google Pay Response Objects
      • Google Pay Sample Code
      • iFields Integration
      • Google Pay FAQ
  • 🔌Plugins
    • Netsuite
      • NetSuite Features and Demo
    • WooCommerce
    • Magento Plugin
    • RMH (Retail Management Hero)
    • RMS (Retail Management Systems)
  • 📖Articles
    • Frequently Asked Questions
    • How to Build POS Integration Flows
    • Card Present Integration Guide
  • Glossary of Terms
Powered by GitBook
On this page
  • Introduction
  • Purpose
  • Scope
  • Overview of Tap to Phone Helper Mobile App
  • About
  • How to use Tap to Phone with the Cardknox Android App
  • How to install Tap to Phone using the Google Play Store
  • Deep Linking
  • Supported Transaction Workflows
  • Transaction Parameters
  • Development and Debugging
  • How to Integrate Tap to Phone with Third-Party Android Applications
  • How to Setup Deeplink URL
  • How to create a server-side call:
  • Server-side Request Example:
  • How to call a Deep Link URL to Invoke the Tap to Phone Helper Application

Was this helpful?

Export as PDF
  1. Cardknox Products

Tap to Phone - Android

Introduction

Purpose

This document references all the features and an Android integration guide for Cardknox Tap to Phone.

We’ll cover:

  • Tap to Phone Application Overview

  • How do you install the Tap to Phone application on your Android device?

  • How to integrate a third-party merchant application with the Cardknox Tap to Phone application

Scope

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


Overview of Tap to Phone Helper Mobile App

About

Tap to Phone allows merchants to accept payments using their mobile devices without an external terminal. Tap to Phone 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

How to use Tap to Phone with the Cardknox Android App

  • Enable the Tap to Phone Feature:

    • Navigate to Settings -> Device Configuration

    • Select Tap to Phone.

  • Install the Tap to Phone Helper App:

  • Activate Tap to Phone:

    • Once the Tap to Phone helper app is installed, return to the Cardknox App and enable Tap to Phone.

How to install Tap to Phone using the Google Play Store


Deep Linking

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

The Tap to Phone 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 Phone Helper application's predefined URL is:

cardknox://tap.cardknox.com/transaction


Supported Transaction Workflows

Tap to Phone 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 Phone helper application. To complete the transaction, send the server-side payload and other returned data to the Cardknox 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 Phone helper will use the ‘Encrypted Payload’ workflow and return the encrypted payload in the transaction response.

xRedirectURL

Yes

A valid URL scheme defined inside the third-party application to receive transaction responses from the ‘Tap to Phone’ helper application

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

Parameters

Required

Possible Values

Description

xCommand

Yes

cc:singleusetoken

If you send the xCommand value as cc:singleusetoken, the Tap to Phone helper will use the “Single Use Token (SUT)” workflow and return the SUT in the transaction response.

xRedirectURL

Yes

A valid URL scheme defined inside the third-party application to receive transaction responses from the ‘Tap to Phone’ helper application

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

Parameters

Required

Possible Values

Description

xCommand

Yes

cc:sale, cc:save, cc:authonly, cc:credit

Cardknox transaction type

xKey

Yes

Your Cardknox API key

xRedirectURL

Yes

A valid URL scheme defined inside the third-party application to receive transaction responses from the ‘Tap to Phone’ helper application


Transaction Parameters

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

Parameter

Description

xRedirectURL

A valid URL scheme defined inside the third-party application to receive transaction responses from the ‘Tap to Phone’ helper application

xCommand

This parameter is utilized to indicate the specific type of transaction that needs to be executed (cc:sale, cc:refund, cc:void, etc.).

One caveat is that this must be defined as cc:encrypt for the ‘Encrypted Payload’ workflow or cc:singleusetoken for the ‘Single-Use-Token’ workflow.

For the ‘Complete Transaction’ workflow, you can pass the usual Cardknox-specific xCommand values.


Development and Debugging

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

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

Parameter

Description

Possible Values

Default Value

debug

Set to TRUE to display logs in the Tap to Phone helper application.

TRUE/FALSE

FALSE

useSTG

This enables a staging gateway environment. Applicable only for ‘Complete Transaction’ workflow.

TRUE/FALSE

FALSE

doNotRedirect

Disables the redirect URL and displays the results/logs within the Tap to Phone helper app.

TRUE/FALSE

FALSE

All ‘debugging’ parameters are optional.


How to Integrate Tap to Phone with Third-Party Android Applications

How to Setup Deeplink URL

Third-party merchant app developers can form URLs based on different transaction needs. Tap to Phone 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.

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&xAllowPartialAuth=true

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

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

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

Parameter

Description

xEncryptedPayload

This will contain the encrypted payload or single-use token if the transaction workflow is requested as an ‘encrypted payload’ or ‘single-use token’.

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 Cardknox gateway response values.

xCommand

How to create a server-side call:

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…

Server-side Request Example:

{
  "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"
}

How to call a Deep Link URL to Invoke the Tap to Phone Helper Application

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

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);

Last updated 9 months ago

Was this helpful?

Enable “Tap to Phone” within the Device Configuration settings within the

Open the .

When prompted, install the .

Download the Tap to Phone Helper application from the .

Transaction API Specific – Use any Cardknox API parameters in the deep-link request. . However, the below API parameters must be carefully designed to achieve the desired transaction result using the Tap to Phone helper.

You can refer to the for other response parameter definitions.

When running the server-side call to Cardknox, you must use the standard required API parameters. Reference the for a list of parameters.

🧰
Cardknox Mobile App
Cardknox Android App
Tap to Phone Helper app
Google Play Store
See Transaction API documentation
API documentation
Transaction API
*Any ‘Cardknox API’ parameter