DvPayLite Deep Linking
Through URI Mode

DvPayLite Deep Linking Integration - URI Mode

Version History

DateVersionDetails
17/12/24 1.0.0

Initial Version

Request TPN

To onboard as a merchant and test with the sandbox environment, contact your Dejavoo representative to obtain a TPN (Terminal Profile Number).

What is TPN?

TPN is a 12-digit numeric code assigned to merchants for integration purposes.

Set Up the Developer Environment

1. Android Studio IDE

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

2. Develop an Android Application

  • Create a new Android project or use an existing one.
  • Follow the steps outlined below:
    • Set the scheme as "denovopay" when creating the URI.
    • Update the host based on the type of transaction.
    • Refer to the Perform Transaction API section in this document for transaction types and sample input requests.

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 DvPay Lite Application.

DvPayimage-1.png

APIs

Device Register API

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

Host: “register”

Intent will return transactionResult in the activity result.

Request Parameters:

FieldDescriptionSample
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 applicationDVPAYLITE

Response Parameters:

FieldDescriptionSample
transactionResult It is a string that provides responses as Success and failureSuccess/Failure
transactionResult Json It is a json string that contains response tags of the transaction

Response(transactionResultJson) Details:

  1. if success
FieldDescriptionSample
message It’s a Unique 12 digit code. This value is unique for each merchant.Terminal Added Successfully
isValidTPN Indicates whether the TPN is validtrue
assignedBuildNumber Build number assigned to this transaction or request(Empty in this case)
  1. if failure
FieldDescriptionSample
error_code Error code indicating the type of error15
error_message Message describing the errorTPN is not Configured

Snippet code:

jsonRequest = {
    “tpn”:”123456789012”, 
    “applicationType”:”DVPAYLITE”
    }

sample - scheme + "://" + host + "?data=" + Request (Passing Request as Url encoded(UTF-8))

Perform Transaction API

This API is used to invoke the DvPayLite application to perform a transaction. 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.

Host: “pay”

The Intent will return transactionResult in the activity result.

Request parameters

FieldDescriptionSample
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 Amount10.00
tip Transaction Tip Amount (Applicable only for sale and ticket) 1.00
applicationType The application type is used to identify the applicationDVPAYLITE
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 Parameters:

FieldDescriptionSample
transactionResult It is a string that provides responses as Success and failureSuccess/Failure
transactionResult Json It is a json string that contains response tags of the transaction

Response(transactionResultJson) Details

FieldDescriptionSample
authCode Authorization code received from the payment processorDSC058
LTaxAmount Local Tax Amount2.40
STaxAmount State Tax Amount1.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 cardholderSteve Rogers
batchNo Batch number associated with the transaction444
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 card12/25
emvTVR EMV Terminal Verification Results0000008000
emvTC EMV Transaction CertificateF23A1C0D45678910
emvTSI EMV Transaction Status IndicatorE800
emvAppName EMV Application Name (for chip card transactions)VISA CREDIT
emvAID EMV Application Identifier (for chip card transactions)A0000000041010
date Transaction date2024-10-01
disclaimer Statement acknowledging the cardholder’s receipt of goods and agreeing to cardholder obligationsCardholder acknowledges receipt of goods
fee Custom fee associated with the transaction0.62
iPOSToken Token generated for the transaction (used for tracking and security)FDBD45C65D2CCB28BE42BAF72D1D7F13A6894F146D70AD17
invoice_no Invoice number associated with the transaction2
last_4_digits Last 4 digits of the card number5859
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 transaction which received in the requestDL305734142454
respCode Response code from the payment processor [00 - Success, and remaining all failures]00
respMsg Response message from the payment processor for the transactionAPPROVAL 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 transactionApproved
time Time of the transaction06:28:39
tipAmount Amount of tip added to the transactions3.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 fees19.82
transId Transaction ID (unique identifier for the transaction)000004
transaction_id Same as transId, used interchangeably000004
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 Amount12.00

Snippet Code:

jsonRequest = {
    “type”:”SALE”, 
    “amount”:”10.00”, 
    “tip”:”1.00”, 
    “applicationType”:”DVPAYLITE”, 
    “refId”:”1234567890”
              }

Example : scheme + "://" + host + "?data=" + Request (Passing Request as Url encoded)

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.

Host: “settle”

The Intent will return transactionResult in the activity result.

Request parameters

FieldDescriptionSample
type Transaction type [SETTLE] SETTLE
applicationType The application type is used to identify the applicationDVPAYLITE

Response Parameters:

FieldDescriptionSample
transactionResult It is a string that provides responses as Success and failureSuccess/Failure
transactionResult Json It is a json string that contains response tags of the transaction

Response(transactionResultJson) Details

FieldDescriptionSample
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 transaction0 (Success)
message Message corresponding to the resultCodeSuccess
ExtData Extended data with details about the batch settlementApp=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 batchApp=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 settlement00
HostResponseMessage Message from the host confirming the settlement statusBATCH SETTLED
isValidTPN Indicates whether the TPN is validtrue
message Overall message or outcome of the batch processBatch settled successfully

Snippet Code

settleReq = {
    “type”:”SETTLE”, 
    “applicationType”:”DVPAYLITE”
    }

Example : scheme + "://" + host + "?data=" + Request (Passing Request as Url encoded)

Tip Adjust API

This API is used to perform a tip adjustment on a sale transaction.

Tip adjustments are allowed only for credit transactions by processors and are not permitted for other transaction types.

Host: “pay” The intent will return transactionResult in the activity result.

Request parameters

FieldDescriptionSample
type Transaction type [TIP ADJUST]TIP ADJUST
amount Transaction Amount of original sale base transaction10.00
tip Transaction Tip Amount1.00
applicationType The application type is used to identify the applicationDVPAYLITE
refId Transaction reference id of original sale transaction1234567890

Response Parameters

Same as Perform Transaction API

Snippet Code

jsonRequest = 
    {“type”:”TIP ADJUST”, 
    “amount”:”10.00”, 
    “tip”:”1.00”, 
    “applicationType”:”DVPAYLITE”, 
    “refId”:”1234567890”}

Example : scheme + "://" + host + "?data=" + Request (Passing Request as Url encoded)

Get TPN API

This API is used to retrieve the TPN (Terminal Processing Number) of a device.

Host: “get”

The intent will return transactionResult in the activity result.

Request parameters

FieldDescriptionSample
type String that specifies get TPNgetTPN
applicationType The application type is used to identify the applicationDVPAYLITE

Response Parameters

FieldDescriptionSample
transactionResult It is a string that provides responses as Success and failureSuccess/Failure
transactionResult Json It is a json string that contains response tags of the transaction

Response Details

FieldDescriptionSample
message Application type is used to identify the application.DvPayLiteTPN
tpn Terminal Processing Number (unique identifier)132423805864

Snippet Code

jsonRequest = 
            {"applicationType":"DVPAYLITE", 
            "type":"getTPN"}

Example: scheme + "://" + host + "?data=" + Request (Passing Request as Url encoded)

Device detail API

This API is used to obtain the details of the device.

Host: “get”

The intent will return transactionResult in the activity result.

Request parameters

FieldDescriptionSample
applicationType The application type is used to identify the applicationDVPAYLITE

Response Parameters

FieldDescriptionSample
transactionResult It is a string that provides responses as Success and failureSuccess/Failure
transactionResult Json It is a json string that contains response tags of the transaction

Response parameters

FieldDescriptionSample
model Model of the deviceP3
manufacture Manufacturer of the deviceKozen
sNo Serial number of the deviceB1791E1XL8080062
tpn Terminal Processing Number (unique identifier)132423805864
respCode Response code indicating the outcome of the request00
respMessage Message corresponding to the response codeSuccess

Snippet Code

jsonRequest = 
{"applicationType":"DVPAYLITE", 
"type":"getDevice"}

Example : scheme + "://" + host + "?data=" + Request (Passing Request as Url encoded)

Status Check API

This API is used to retrieve the current transaction status.

Host: “pay”

The intent will return transactionResult in the activity result.

Request parameters

FieldDescriptionSample
refId Transaction reference id of original sale transaction1234567890
type Type of the transaction [STATUS]STATUS
applicationType The application type is used to identify the applicationDVPAYLITE

Response Details

Same as Perform Transaction API

Snippet Code

jsonRequest = 
{“type”:” STATUS”,
“applicationType”:”DVPAYLITE”, 
“refId”:”1234567890”}

Example : scheme + "://" + host + "?data=" + Request (Passing Request as Url encoded)

Administrative Txn API

This API is used to retrieve card numbers.

For this to function, the administrative transaction type must be enabled in STEAM:

  • Navigate to Edit Parameters.
  • Go to the Transaction tab.

Host: “pay” The intent will return transactionResult in the activity result.

Request parameters

FieldDescriptionSample
type Type of the transaction [ADMINISTRATIVE_TXN]ADMINISTRATIVE_TXN
applicationType The application type is used to identify the applicationDVPAYLITE

Response Parameters:

FieldDescriptionSample
transactionResult It is a string that provides responses as Success and failureSuccess/Failure
transactionResult Json It is a json string that contains response tags of the transaction

Snippet Code

jsonRequest = 
{“type”:” ADMINISTRATIVE_TXN”,
“applicationType”:”DVPAYLITE”}

Example : scheme + "://" + host + "?data=" + Request (Passing Request as Url encoded)

Go Live Requirements

The following are the Go Live activities:

  • All third-party app integrations with DvPay Lite via deep-linking will be hosted in our DvStore application, which is provided as a default app in the firmware of production terminals.
  • To host an application in the app market, please contact the Dev Support team using the email provided below.
  • Once the application is hosted in the DvStore app, it can be downloaded to terminals and updated by hosting newer versions of the app.
  • Applications can be tested in test environments before being uploaded to production environments.

Help

For any questions or suggestions, email us directly at devsupport@denovosystem.com.