DvPayLite Deep Linking Integration - Intent Mode

Version History

Date	Version	Details
01/06/23	1.0.0	Initial release
19/06/23	1.0.1	Architecture diagram revised, and AndroidManifest.xml added.
28/06/23	1.0.2	Tip Adjust API added
14/07/23	1.0.3	Added Preauth and Ticket in transaction API
07/11/23	1.0.4	Updates: Device detail API, Get TPN API, Status check API, and enhancements to existing APIs.
21/11/23	1.0.5	Updates: Debugging signing configurations updated for terminal use, and Administrative Txn API added.
26/04/24	1.0.6	Updates: Added information on 3rd party app installation in P terminals.
13/09/24	1.0.7	Updates: Request tags for payment type and receipt type updated in the performTransaction API.

Prerequisites

iPOSpays-powered Dejavoo terminal
Login credential to iPOSpays (opens in a new tab)
The host application must be listed on DvStore. If you haven't done so already, please fill out the necessary form to list your application. List now (opens in a new tab)

For Sandbox (UAT)

Users should be onboarded on iPOSpays sandbox(UAT) environment as a merchant and have a valid CloudPOS TPN.

For Production (Live)

Users should be onboarded on iPOSpays production environment as a merchant and have a valid CloudPOS TPN.

If you do not have a TPN, contact your ISO or support@dejavoo.io

Set Up the Developer Environment

Android Studio IDE
- A Download and set up Android Studio from developer.android.com (opens in a new tab)

Develop Android Application

Create a new Android project or use an existing one.
Configure the following snippets in your build.gradle and settings.gradle files.

Configure Gradle

Add Dependency

Include the following dependency in your project’s build.gradle file:

com.denovo:invoke-dvpay-lite:1.1.9.7

Add Permission

Include the following permission in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />

To obtain the library file containing the access key and secret key required for integration, please Contact devsupport@denovosystem.com. Make sure to CC your Dejavoo representative when sending your request.

Configure settings.gradle

In your settings.gradle file, include the following configuration:

allprojects {
    repositories {
        jcenter()
        flatDir { dirs 'libs' }
        maven {
            url "s3://denovo-android.s3.amazonaws.com" 
            credentials(AwsCredentials) {
                accessKey "AKIA26XMFQBITA36GRDR"
                secretKey "JZdZ3BoK7V2ZpFr8iZtZ3g2oGKX/oVgDVqpJRNvy"
            }
        }
    }
}

Add Signing Configuration

Configure Signing for Debug Build

Add the following lines to your project’s build.gradle file for running the application with a signature:

signingConfigs {
      debug {
            storeFile file(“kozen.jks”)
            storePassword “kozen”
            keyAlias “xc-buildsrv”
keyPassword “kozen”
v1SigningEnabled true
v2SigningEnabled true
}
     }
buildTypes {
    debug {
        signingConfig signingConfigs.debug
        …….
        }
    }

Download the kozen.jks File

To download the kozen.jks file, click on the highlighted text that reads “kozen.jks“

Install DvPayLite Application

Ensure the DvPayLite application is installed on the payment terminal. If it is not installed, complete the installation before proceeding with the integration.

Version Control and Updates

Non-breaking changes:
1. We will continue to enhance the API by adding new functionality and fixing bugs over time.
2. These updates may include:
  - New endpoints
  - Additional attributes for existing objects
3. Such changes will not require a new API version. Ensure your code can handle new attributes gracefully and does not rely on the order of returned records unless explicitly specified in the documentation.
Breaking changes:
- We aim to maintain the current API version for the foreseeable future.
- In the event of changes that break the current API's functionality, a new version number will be released to ensure backward compatibility with existing integrations
- Refer to the Version History to review the version history of this document.

High-Level Flow

The following is a high-level flow to communicate with the DvPayLite Application.

Initialize the Application

To invoke the DvPayLite application, developers must initialize it within the invoking app using the following set of lines.

activityResultLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) 
{ result: ActivityResult ->
 
intentApplication.handleResultCallBack(result)
 
}
 
intentApplication = IntentApplication(requireContext())

APIs

Device Register API

The Device Register API is used to download both the terminal configuration and merchant configuration data from the backend application into the DvPayLite application.

Request Parameters:

Field	Description	Sample
tpn	It’s a Unique 12-digit code. This value is unique for each merchant.	123456789012
applicationType	The application type is used to identify the application	DVPAYLITE

Response Details:

onTerminalAdded

Field	Description	Example
message	It’s a Unique 12 digit code. This value is unique for each merchant.	Terminal Added Successfully
isValidTPN	Indicates whether the TPN is valid	true
assignedBuildNumber	Build number assigned to this transaction or request	(Empty in this case)

onTerminalAddFailed

Field	Description	Example
error_code	Error code indicating the type of error	15
error_message	Message describing the error	TPN is not Configured

Snippet code

jsonRequest = {“tpn”:”123456789012”, “applicationType”:”DVPAYLITE”}
InvokeApp.intentApplication.setTerminalAddListener(object : TerminalAddListener {
 
override fun onApplicationLaunched(addTerminal: JSONObject?) {
 
//application launched success json data
 
}
 
override fun onApplicationLaunchFailed(errorResult: JSONObject) {
 
//application launched failed json data
 
}
 
override fun onTerminalAdded(terminalResult: JSONObject?) {
 
//Terminal added json data
 
}
 
override fun onTerminalAddFailed(errorResult: JSONObject) {
 
//Terminal add failed json data
 
}
 
})
 
InvokeApp.intentApplication.addTerminal(jsonRequest, InvokeApp.activityResultLauncher)

Perform Transaction API

The Perform Transaction API is used to invoke the DvPayLite application to process transactions. It supports the following transaction types: SALE, REFUND, VOID, PRE_AUTH, and TICKET.

For pin-based transactions, keys must be injected into the terminal. To inject the keys, please contact the developer support team at devsupport@denovosystem.com.

Request Parameters:

Field	Description	Sample
type	Transaction type should be any one of the following [SALE, REFUND, VOID, PRE_AUTH, TICKET]	SALE
paymentType	Payment Type [CREDIT,DEBIT,EBT_Food,EBT_Cash]	CREDIT
amount	Transaction Amount	10.00
tip	Transaction Tip Amount (Applicable only for sale and ticket)	1.00
applicationType	The application type is used to identify the application	DVPAYLITE
refId	Transaction reference id (Should be unique for sale, refund, and Pre_Auth and should be original sale ref id for void and pre_auth refund for ticket)	1234567890
receiptType	Type of receipt Possible Options - [Merchant, Customer, Both, No]	Merchant

Response Details

Field	Description	Example
authCode	Authorization code received from the payment processor	DSC058
LTaxAmount	Local Tax Amount	2.40
STaxAmount	State Tax Amount	1.20
extData	Extended data related to the transaction (e.g., partial approval info, void status)	{"dueAmnt":"0.00","approvedAmnt":"","isPartialApprovalTxn":false,"voided":"false"}
cardHolderName	Name of the cardholder	Steve Rogers
batchNo	Batch number associated with the transaction	444
card_type	Type of card used for the transaction (e.g., VISA, MASTER, DISCOVER)	JCB
merchant	Data to be printed on Merchant receipt along with the format and alignment in xml format. [ C - center, R- Right, L- Left, N- Normal, B- Bold]
customer	Data to be printed on Customer receipt along with the format and alignment in xml format. [ C - center, R- Right, L- Left]
expDate	Expiry date of the card	12/25
emvTVR	EMV Terminal Verification Results	0000008000
emvTC	EMV Transaction Certificate	F23A1C0D45678910
emvTSI	EMV Transaction Status Indicator	E800
emvAppName	EMV Application Name (for chip card transactions)	VISA CREDIT
emvAID	EMV Application Identifier (for chip card transactions)	A0000000041010
date	Transaction date	2024-10-01
disclaimer	Statement acknowledging the cardholder’s receipt of goods and agreeing to cardholder obligations	Cardholder acknowledges receipt of goods
fee	Custom fee associated with the transaction	0.62
iPOSToken	Token generated for the transaction (used for tracking and security)	FDBD45C65D2CCB28BE42BAF72D1D7F13A6894F146D70AD17
invoice_no	Invoice number associated with the transaction	2
last_4_digits	Last 4 digits of the card number	5859
mask_pan	Masked Primary Account Number (PAN)	3530145859
pinMode	PIN mode used in the transaction. [0 = no PIN, 1 = PIN verified]	0
refId	Reference ID for tracking the transactionwhich received in the request	DL305734142454
respCode	Response code from the payment processor [00 - Success, and remaining all failures]	00
respMsg	Response message from the payment processor for the transaction	APPROVAL DSC058
rrn	Retrieval Reference Number (used for tracking in case of disputes)	427510500684
sign	Customer signature in the string format of Base64 encoding (if captured electronically)
status	Status of the transaction	Approved
time	Time of the transaction	06:28:39
tipAmount	Amount of tip added to the transaction	3.60
tipLine	Whether the tip line was included in the receipt [0 = no, 1 = yes]	0
totalAmount	Total amount including base amount, tax, tip, and fees	19.82
transId	Transaction ID (unique identifier for the transaction)	000004
transaction_id	Same as transId, used interchangeably	000004
transaction_title	Title of the transaction (e.g., SALE, REFUND)	SALE
transaction_mode	Mode of the transaction [1 - Swipe, 2 - Chip, 3- Contactless, 4 - Manual]	1
transaction_type	Numeric type for the transaction [1 - Credit, 2 - Debit, 3 - EBT, 6 - Gift]	1
amount_paid	Total amount paid for the goods or services as Base Amount	12.00

Snippet code

jsonRequest = {“type”:”SALE”, “amount”:”10.00”, “tip”:”1.00”, “applicationType”:”DVPAYLITE”, “refId”:”1234567890”}
 
InvokeApp.intentApplication.setTransactionListener(object : TransactionListener {
 
override fun onApplicationLaunched(result: JSONObject?) {
 
//application launched success json data
 
}
 
override fun onApplicationLaunchFailed(errorResult: JSONObject) {
 
//application launched failed json data
 
}
 
override fun onTransactionSuccess(transactionResult: JSONObject?) {
 
//Transaction Success json data
 
}
 
override fun onTransactionFailed(errorResult: JSONObject) {
 
//Transaction Failed json data
 
}
 
})
 
InvokeApp.intentApplication.performTransaction(jsonRequest, InvokeApp.activityResultLauncher)

Batch Settlement API

At the end of the business day, when a merchant is ready to close, all transactions processed during their operating hours must be submitted to the processor to ensure the funds are transferred to their bank account.

A batch is a collection of transactions that have been processed but not yet settled. When a transaction is approved, it is added to the batch. If the batch has not yet been settled, it is considered an open batch. Transactions within an open batch can still be voided or reversed if necessary.

Request Parameters:

Field	Description	Sample
type	Transaction type [SETTLE]	SETTLE
applicationType	The application type is used to identify the application	DVPAYLITE

Response Details

Field	Description	Example
assignedBuildNumber	Build number assigned to this transaction or request	(Empty in this case)
TPN	Terminal Profile Number (unique identifier for the terminal)	132423805864
resultCode	Result code indicating the outcome of the transaction	0 (Success)
message	Message corresponding to the resultCode	Success
ExtData	Extended data with details about the batch settlement	App=DvPayLite, ResultCode=0, BatchNum=443, Rsp=BATCH SETTLED, Status=GB,TipAmt=39.60, TotalAmt=218.06, SHFee=6.86, NumTrans=2
Receipt	Receipt information in formatted string (customer and terminal data, transaction totals, etc.)	Date: 2024/10/02, Time: 06:28:39, Terminal: 132423805864, Merchant: 888000003338, Batch#: 443, Status: GB, etc.
TransReport	Report summarizing transactions in the batch	App=DvPayLite, TrnsCnt=2, SaleAmt=218.06, ReturnAmt=0.0, VoidAmt=0.0, AuthAmt=0.0, TicketAmt=0.0, TotalAmt=218.06
HostResponseCode	Response code from the host indicating the success of batch settlemen	00
HostResponseMessage	Message from the host confirming the settlement status	BATCH SETTLED
isValidTPN	Indicates whether the TPN is valid	true
message	Overall message or outcome of the batch process	Batch settled successfully

Snippet code

settleReq = {“type”:”SETTLE”, “applicationType”:”DVPAYLITE”} InvokeApp.intentApplication.setSettlementListener(object :
 
SettlementListener {
 
override fun onSettlementFailed(p0: JSONObject) {
 
//Settlement failed json data
 
}
 
override fun onSettlementSuccess(p0: JSONObject) {
 
//Settlement success json data
 
}
 
})
 
InvokeApp.intentApplication.settleBatch(settleReq, InvokeApp.activityResultLauncher)

Tip Adjust API

Tip Adjustment allows users to modify the tip amount on a transaction before the batch is settled and sent to the processor. This API is used to perform a tip adjustment on a sale transaction.

Note: Tip adjust is allowed only for credit transactions by processors. It is not allowed for any other transactions.

Request Parameters:

Field	Description	Sample
Type	Transaction type [TIP ADJUST]	TIP ADJUST
Amount	Transaction Amount of original sale base transaction	10.00
Tip	Transaction Tip Amount	1.00
Application type	The application type is used to identify the application.	DVPAYLITE
refId	Transaction reference id of original sale transaction	1234567890

Response Details:

Same as Perform Transaction API

Snippet code

jsonRequest = {“type”:”TIP ADJUST”, “amount”:”10.00”, “tip”:”1.00”, “applicationType”:”DVPAYLITE”, “refId”:”1234567890”}
 
InvokeApp.intentApplication.setTransactionListener(object : TransactionListener {
 
override fun onApplicationLaunched(result: JSONObject?) {
 
//application launched success json data
 
}
 
override fun onApplicationLaunchFailed(errorResult: JSONObject) {
 
//application launched failed json data
 
}
 
override fun onTransactionSuccess(transactionResult: JSONObject?) {
 
//Transaction Success json data
 
}
 
override fun onTransactionFailed(errorResult: JSONObject) {
 
//Transaction Failed json data
 
}
 
})
 
InvokeApp.intentApplication.performTipAdjust(jsonRequest, InvokeApp.activityResultLauncher)

Get TPN API

This API is used to retrieve a terminal’s TPN.

Request Parameters:

Field	Description	Sample
applicationType	Application type is used to identify the application.	DVPAYLITE

Response Details

Field	Description	Example
message	Application type is used to identify the application.	DvPayLiteTPN
TPN	Terminal Profile Number (unique identifier for the terminal)	132423805864

Snippet code

jsonRequest = {“applicationType”:”DVPAYLITE”}
 
InvokeApp.intentApplication.setGetTPNListener(object : GetTPNListener {
 
override fun onApplicationLaunched(response: JSONObject?) {
 
//application launched success json data
 
}
 
override fun onApplicationLaunchFailed(response: JSONObject?) {
 
//application launched failed json data
 
}
 
override fun onGetTPN(response: JSONObject?) {
 
//Success json data
 
}
 
override fun onTPNFailed(response: JSONObject?) {
 
// Failed json data
}
})
 
InvokeApp.intentApplication.getTPN(jsonRequest, activityResultLauncher)

Device detail API

This API is used to obtain details of the device.

Request Parameters:

Field	Description	Sample
applicationType	Application type is used to identify the application.	DVPAYLITE

Response Details

Field	Description	Example
model	Model of the device	P3
manufacture	Manufacturer of the device	Kozen
sNo	Serial number of the device	B1791E1XL8080062
TPN	Terminal Profile Number (unique identifier for the terminal)	132423805864
respCode	Response code indicating the outcome of the request	00
respMessage	Message corresponding to the response code	Success

Snippet code

jsonRequest = {“applicationType”:”DVPAYLITE”}
 
InvokeApp.intentApplication.setGetDeviceListener(object : GetDeviceListener {
 
override fun onApplicationLaunched(response: JSONObject?) {
 
//application launched success json data
 
}
 
override fun onApplicationLaunchFailed(response: JSONObject?) {
 
//application launched failed json data
 
}
 
override fun onGetDevice(p0: JSONObject?) {
 
// Success json data
 
}
 
override fun onGetDeviceFailed(p0: JSONObject?) {
 
// Failure json data
 
}
 
})
 
InvokeApp.intentApplication.getDevice(jsonRequest, activityResultLauncher)

Status Check API

This API is used to get the current transaction status.

Request Parameters:

Field	Description	Sample
refId	Transaction reference id of original sale transaction	1234567890
type	Type of the transaction [STATUS]	STATUS
applicationType	Application type is used to identify the application.	DVPAYLITE

Response Details

Same as Perform Transaction API

Snippet code

jsonRequest = {“type”:” STATUS”, “applicationType”:”DVPAYLITE”,“refId”:”1234567890”}
 
InvokeApp.intentApplication.setTransactionListener(object :TransactionListener {
 
override fun onApplicationLaunched(result: JSONObject?) {
 
//application launched success json data
 
}
 
override fun onApplicationLaunchFailed(errorResult: JSONObject) {
 
//application launched failed json data
 
}
 
override fun onTransactionSuccess(transactionResult: JSONObject?) {
 
//Transaction Success json data
 
}
 
override fun onTransactionFailed(errorResult: JSONObject) {
 
//Transaction Failed json data
 
}
 
})
 
InvokeApp.intentApplication.performTransaction (jsonRequest, activityResultLauncher)

Administrative Txn API

The Administrative Txn API allows you to retrieve card numbers.

For this to work, administrative transaction type must be enabled from S.T.E.A.M →Edit Parameters-> Under Transaction tab

For this to work, administrative transaction type to be enabled in STEAM ->edit parameters -> Under transaction tab

Request Parameters:

Field	Description	Sample
type	Type of the transaction [ADMINISTRATIVE_TXN]	ADMINISTRATIVE_TXN
applicationType	The application type is used to identify the application	DVPAYLITE

Snippet code

jsonRequest = {“type”:” ADMINISTRATIVE_TXN”, “applicationType”:”DVPAYLITE”}
 
InvokeApp.intentApplication.setTransactionListener(object :TransactionListener {
 
 
            override fun onApplicationLaunched(result: JSONObject?) {
                //application launched success json data  
            }
 
            override fun onApplicationLaunchFailed(errorResult: JSONObject) {
                //application launched failed json data
            }
 
            override fun onTransactionSuccess(transactionResult: JSONObject?) {
                //Transaction Success json data           
            }
 
            override fun onTransactionFailed(errorResult: JSONObject) {
                //Transaction Failed json data             
            }
        })
 
     InvokeApp.intentApplication.performTransaction (jsonRequest, activityResultLauncher)

Go Live Requirements

Following are the Go Live Activities:

Set up production terminal with DvPayLite app
Replace Production environment SDK versions in the application build gradle.

3rd party app installation in terminals

All the 3rd party apps integrating with DvPayLite deep-linking will be hosted in our market application which will come as default app in the firmware provided in the production terminal. To host the application in the market app, we require the below details.

APK that should be hosted.
Package name of application
App name to display
App icon to display

Once the application is hosted in a market app, the app can be downloaded from there in terminals and also can be updated by hosting newer applications. This can be tested on test environments and can be uploaded for production environments.

Help

Email us directly at devsupport@denovosystem.com with any questions or suggestions.

Peripheral SDKs Through URI Mode