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
Enable “Tap to Phone” within the Device Configuration settings within the Cardknox Mobile App
How to use Tap to Phone with the Cardknox Android App
Enable the Tap to Phone Feature:
Open the Cardknox Android App.
Navigate to Settings -> Device Configuration
Select Tap to Phone.
Install the Tap to Phone Helper App:
When prompted, 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
Download the Tap to Phone Helper application from 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.
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)
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.
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.
Transaction Parameters
Two types of parameters are supported by the Tap to Phone helper application.
Transaction API Specific – Use any Cardknox API parameters in the deep-link request. See Transaction API documentation. However, the below API parameters must be carefully designed to achieve the desired transaction result using the Tap to Phone helper.
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.
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&x
AllowPartialAuth
=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.
You can refer to the API documentation for other response parameter definitions.
How to create a server-side call:
When running the server-side call to Cardknox, you must use the standard required API parameters. Reference the Transaction API for a list of parameters.
Additionally, the following parameters are required:
Server-side Request Example:
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:
Last updated