DvPayLite Deep Linking Integration
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
Before you get started with your implementation, read the integration overview to learn about integration and required configuration.
Request TPN
To onboard as a merchant and integrate with the sandbox environment, contact your Dejavoo representative to obtain your TPN (Terminal Profile Number).
What is TPN?
TPN is a 12-digit numeric code assigned to merchants for integration purposes.
- Android Studio IDE
ADownload 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. Then, configure the following build.gradle and settings.gradle snippets in your project.
- Configure Gradle
Include the following dependency in your project’s build.gradle file:
com.denovo:invoke-dvpay-lite:1.1.9.7
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.
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 below lines in build.gradle of your project for running the application with signature(for P3 and P5 test devices).
To download the kozen.jks file, simply click on the highlighted text “kozen.jks“
signingConfigs {
debug {
storeFile file(“kozen.jks”)
storePassword “kozen”
keyAlias “xc-buildsrv”
keyPassword “kozen”
v1SigningEnabled true
v2SigningEnabled true
}
}
buildTypes {
debug {
signingConfig signingConfigs.debug
…….
}
}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:
- We will continue to enhance the API by adding new functionality and fixing bugs over time.
- These updates may include:
- New endpoints
- Additional attributes for existing objects
- 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, the developer needs to initialize the application in an Invoking app with the set of lines below.
activityResultLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult())
{ result: ActivityResult ->
intentApplication.handleResultCallBack(result)
}
intentApplication = IntentApplication(requireContext())APIs
Device Register API
Device register API is used to download 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
This API is used to invoke the DvPayLite application to perform the transaction. It supports SALE, REFUND, VOID, PRE AUTH, and TICKET transaction types.
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
A batch is a group of transactions that have been processed but have yet to be settled. When a transaction is approved, it is added to the batch. When a batch hasn’t been settled yet, it is called an open batch, and transactions in the batch can still be voided and reversed if needed.
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 Processing 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
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 get a device 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 Processing 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 Processing 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 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
This API is used to get card number.
Note: 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.