This is a test environment for documentation.
SPIn specification
SOAP API

SPIn specification API

Version History

DateVersionDetails
10/01/22 1.0

Initial release

10/10/22 1.1

Added support for Tags

11/01/22 1.2

Added support for iPOSToken

20/02/23 1.3

Added PerformedBy Tag

5/04/23 1.4

Added userChoice option to PaymentType

21/07/23 1.5

Added support for user input and summary reports to fetch batch details from the payment device.

30/01/24 1.6

06/02/24 1.7

Added support for level data, dual pricing requests, and the ISVID indicator.

10/09/24 1.8

Enabled cart Items display API

12/12/24 1.9

Added fee support tag in sale request

09/06/24 1.10

Added Multi MerchantId

07/07/25 2.0

Added Get Card API support

25/07/25 2.1

Added dynamic capabilities for display cart items API

Prerequisites

For Sandbox (UAT)

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

For Production (Live)

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

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

Steps to Setup

Step 1: Login to iPOSpays (opens in a new tab)

Step 2: Enable SPIn for your TPN.

  • Go to S.T.E.A.M -> Edit Parameters -> search and select your TPN
  • Click Edit Parameter
  • Click Integrations
  • Under Type of Integrations, select SPIn and choose whether you are doing a wire based integration (Local) or over the network (Cloud).
  • Copy the Register ID and Auth Key. You will need these values when calling the API from the Host System.

Watch This Video for a Visual Walkthrough of the Steps

SPIn Proxy (Troubleshooting)

SPIn proxy helps integrators ensure the connection is established between SPIn and the payment terminal.

If the arrow between the SPIn logo and the payment terminal logo is lit up in green, it indicates that the connection has been successfully established. If the arrow is lit up in red, it means the connection has not been established and there is an issue. In this case, please reach out to us at support@dejavoosystems.com.

We also offer simulated testing to verify if the generated Auth Key and TPN are working and ready to be configured with the Host System.

TPN & Auth Key Check – Short Steps:

TPN Check:

  • Click “Check Register Connection” and select “Show TPN.”
  • Confirm pop-up on the terminal.
  • Verify the connection:
    • If the arrow light is green, the TPN will appear on the portal, indicating a successful connection.
    • If the arrow light is red, the connection has failed. For failed connections, contact support at support@dejavoosystems.com.

Auth Key Check:

  • Click “Check Register Connection” and select “Show Auth Key.”
  • Confirm pop-up on the terminal.
  • Verify the connection:
    • If the arrow light is green, the Auth Key will appear on the portal, indicating a successful connection.
    • If the arrow light is red, the connection has failed. For failed connections, contact support at support@dejavoosystems.com.

Server/Register/POS to Terminal Request Format

Follow the process and references mentioned in this section to send a request from the server/register/POS to the integrated Dejavoo payment terminal.

Transaction Request

The current chapter defines the XML format of the request to run a transaction via HTTP GET method.

Sandbox URLhttps://test.spinpos.net:443/SPIn/cgi.html? (opens in a new tab)
Production URLhttps://spinpos.net:443/SPIn/cgi.html? (opens in a new tab)

After sending transaction request to payment terminal, please wait for a timeout period (default timeout is 120 seconds). Within the timeout period SPIn proxy will respond either with approval or decline or time out. If the transaction timeout, please use the Transaction Status Request to check the status.

Request Fields Definition

NameData TypeM/ODescription
AuthKey * String(25) M

Specifies the Auth-Key which authorizes Host system to use the SPIn™ Web Service

PaymentType * String(20) M

Identifies EDC (Electronic Data Capture) type: Credit, Debit, EBT (Electronic Benefits Transfer), userChoice, Gift

Note: If the userChoice value is set to PaymentType in the request, it will allow customers (end-users) to choose between Credit, Debit, or EBT during payment. In the response, the PaymentType field will reflect the option selected by the customer during the transaction.

TransType * String(20) M

Identifies the type of transaction to be run.

(Sale, Return, Void, Auth, Capture, Verification, Conversion)

Some example of supported TransType with PaymentType:

US:

1. Credit: Sale, Return, Void, Auth, Capture, CashAdvance*

2. Debit: Sale, Return

3. EBT_Food – Sale, Return

4. EBT_Cash – Sale, Return

5. Gift – Activate, Inquire, Redeem, Refund, Reload, Deactivate, Reissue, Void

Note: Cash Advance is only available for certain processors

Amount * Float(10) M/O

Dollar amount of the transaction. ($$$$$$$.CC)

Note: This is the total amount. If a tip is added, the amount will include base + tip.

Not used , if using Loyalty transactions in Points value. NOTE: Amount must always be a positive value, even for Returns.

Tip Float(10) O

Dollar amount of the transaction. ($$$$$$$.CC)

Note: Tip must be enabled on terminal

CustomFee Float(10) O

Dollar amount of the transaction. ($$$$$$$.CC)

Note: Whatever fee type enabled in the TPN configuration, the provided fee will be considered as custom fee.

RefId * VarChar(50) M

Alphanumeric reference field that must be unique within the scope of an open batch. Set by the host system and mandatory for all deployments. Used for Tip or other transaction adjustment requests related to a specific transaction (e.g., Tip Adjustment or Void Transaction).

For Table payment type, the RefId does not need to be unique within a batch.

RegisterId * VarChar(50) M

Alphanumeric reference field.

TPN VarChar(12) O

Alphanumeric. The TPN can be used instead of the RegisterId only for Dejavoo SPIn Proxy connections.

For example, the pair

<RegisterId>21123001</RegisterId> <AuthKey>12345678</AuthKey>

works the same way as:

<TPN>12345678912</TPN> <AuthKey>12345678</AuthKey>

CashbackAmount Float(10) O

Cashback amount of the transaction. ($$$$$$$.CC). Only valid on Debit or EBT payment types. Available on builds later than 5/17/19 and Aura

PrintReceipt VarChar(50) O

An optional tag. Possible values:

1. No – transaction receipt won’t be printed on terminal

2.Merchant – print Merchant copy only

3. Customer – print Customer copy only

Both – (default) print both Merchant and Customer copies

SigCapture VarChar(3) O

If SigCapture is set to “No” in the request, the terminal will suppress the signature capture event during the transaction. If this element is not included or is set to “Yes”, the terminal will capture the signature (if the terminal supports signature capture).

Tag1 * VarChar(8) M

The portal supports up to three tags. Tag labels can enabled for the TPN from the portal by going to S.T.E.A.M → Search and Select TPN → Edit Parameter → Value Add → Enable Tag the Tx on the portal. The label for each tag must be configured in Edit Parameter. Once processed, the tag value will be printed on the merchant copy of the receipt. Additionally, transactions can be filtered by this tag value on the portal, and the settlement report will include the tag value as well.

Tag2 * VarChar(8) M

Same as Tag1

Tag3 * VarChar(8) M

Same as Tag1

PerformedBy * VarChar(100) M

This tag will identify the user who performed the transaction. In the case of a Cloud POS + PIN pad transaction, this tag will identify the merchant user (i.e., the email ID of the merchant) who initiated the transaction.

The terminal will upload this information to the portal as part of the signature upload process. This information will be visible on the portal and included in the transaction report for download.

MerchantId * VarChar(12) O

Optional – For regular transactions when Multi MID (MMID) is not enabled.

Mandatory – When Multi MID (MMID) is enabled, the MerchantId must be provided. This should be the TPN (Terminal Provider Number) through which the transaction is intended to be processed.

In the iPOSpays environment, each MID is tied to a specific TPN, so it's essential to send the correct TPN to ensure the transaction routes to the appropriate MID.

Tag:

<MerchantId>TransactingTPN</MerchantId>

Example:

<AuthKey>12345678</AuthKey>

<TPN>MasterTPN</TPN>

<MerchantId>TransactingTPN</MerchantId>

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alphanumeric reference field. Echo back the original value from request.

RegisterId * VarChar(50)

Alphanumeric reference field.

TPN * VarChar(12)

TPN sent in the request is returned

TransNum * VarChar(50)

Transaction number identified on terminal

InvNum * VarChar(50)

Unique alphanumeric invoice field.

ResultCode * VarChar(50)

Transaction status: 0-Approved, 1-Declined/Failed due to reason returned by terminal 2- Failed due to reason returned by SPIn Proxy

RespMSG * VarChar(50)

Alphanumeric field from SPIn Proxy or Terminal

Message * VarChar(50)

Alphanumeric field from SPIn Proxy or Terminal.

AuthCode * VarChar(50)

Alphanumeric field from Processor.

PNRef * VarChar(50)

Alphanumeric field from SPIn Proxy or Terminal.

PaymentType * VarChar(50)

An alphabetical string indicating the payment type used for processing transactions. The payment type can be switched based on rules embedded within the payment application. For example, a Credit Visa card can be processed as Debit either through an automatic BIN table lookup or based on user selection at the Credit/Debit prompt.

Voided * VarChar(50)

True/False – A flag used to define whether a transaction has been voided. It is most commonly used with the Status transaction type.

TransType * String(20)

Identifies the type of transaction performed

SN * VarChar(50)

Serial number of the payment terminal that was used to perform the transaction.

ExtData * VarChar(512)

Additional transaction data:

1. InvNum: Invoice number

2. CardType: VISA, MASTERCARD, AMEX, DISCOVER, DINERSCLUB, JCB, ENROUTE, DEBIT, EBT

3. BatchNum: Batch number

4. Tip: Tip amount

5. CashBack: Cashback amount

6. Fee: Merchant fee

7. AcntLast: Last 4 digits of account number

8. Name: Cardholder name (if card swipe)

9. TotalAmt: Total amount

10. DISC: Discount amount

11. SHFee: Service and Handling Fee, if enabled

12.EBTFSAvailBalance: EBT Food Stamp Balance, if provided by Host

13. EBTCashAvailBalance: EBT Cash Balance, if provided by Host

14. EntryType: Entry method used to provide account data. Supported Entry Types – Swipe, Manual, CHIP, Contactless, CHIP Contactless, and CHIP/Swipe (if Fallback occurred)

15. GiftBalAmount: Balance amount available for the gift card used, if provided by the Host

Note: Check transactions do not have this field.

EMVData * VarChar(100)

Additional transaction data specific to EMV transactions required to be present on the receipt:

1. AID: Application ID from ICC

2. AppName: Application Name from ICC

3. TVR: Terminal Verification Results

4. TSI: Transaction Status Information

5. IAD: Issuer Application Data

6. ARC: Authorization Response Code

Sign * Base64

Base64 encoded signature image in b/w bitmap format

iPOSToken * VarChar(100)

The tokenized card number and expiry date represent an iPOSpays token, not a processor token. Therefore, this token can only be used for transactions processed through the portal.

For instructions on how to use this token to perform a transaction on the card on file, please refer to the [iPOS Transact API](https://docs.ipospays.com/ipos-transact) documentation.

Sample Request and Response:

Request to Terminal
 
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
	<PaymentType>Credit</PaymentType>
	<TransType>Sale</TransType>
	<Amount>1.00</Amount>
	<CustomFee>1.00</CustomFee>
	<RefId>2</RefId>
	<RegisterId>3</RegisterId>
	<AuthKey>234123-74653252-663525223</AuthKey>
	<TPN>123456789123</TPN>
	<MerchantId>123456789143</MerchantId>
	<PrintReceipt>Both</PrintReceipt>
	<PerformedBy>sample@email-account-id</PerformedBy>
</request>
Response from Terminal to Server
<xmp>
	<response>
		<RefId>2</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<ResultCode>0</ResultCode>
		<RespMSG>Approved</RespMSG>
		<Message>Approved</Message>
		<AuthCode>292249</AuthCode>
		<PNRef>1807027</PNRef>
		<PaymentType>Credit</PaymentType>
		<ExtData>InvNum=1,CardType=VISA,BatchNum=1,Tip=0.00, CashBack=0.00,Fee=0.00,AcntLast4=1234,Name=Dejavoo, TotalAmt=1.00,DISC=0.00,SHFee=0.00,EBTFSAvailBalance=,EBTCashAvailBalance=,EntryType=Swipe,TaxCity=0.00,TaxState=0.00,Cust1=,Cust1Value=,Cust2=,Cust2Value=,Cust3=,Cust3Value=,AcntFirst4=4111,TaxAmount=0.00</ExtData>
		<Sign>Qk2uCAAAAAAAAD4AAAAoAAAACwEAADwAAAABAAEAAAAAAHAIAADED</Sign>
		<iPOSToken>BoPRWAadfR3cgsjazKpj+y/9CfSK2dzHmMYEt+QJ7MEiEgUQCSIQDmzC</iPOSToken>
	</response>
</xmp>
Decline Response from Terminal to Server
<xmp>
	<response>
		<Message>Canceled</Message>
		<RefId>167</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<ResultCode>1</ResultCode>
		<RespMSG>%20%20%20%20DECLINE%20%20%20%20%20</RespMSG>
		<PaymentType>Debit</PaymentType>
		<Voided>false</Voided>
		<TransType>Sale</TransType>
		<SN>B17912107210053</SN>
	</response>
</xmp>
Timeout Response from Terminal to Server
<xmp>
	<response>
		<Message>Canceled</Message>
		<RefId>164</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<ResultCode>1</ResultCode>
		<RespMSG>Transaction%20timeout.%20Please%20try%20again%20later.</RespMSG>
		<PaymentType>Debit</PaymentType>
		<Voided>false</Voided>
		<TransType>Sale</TransType>
		<SN>B17912107210053</SN>
		<ExtData>Amount=1.00,dueAmnt=,approvedAmnt=,InvNum=,CardType=,Tip=0.00,
		Fee=0.03,Disc=0.00,DiscLabel=,BatchNum=1,CashBack=0.00,AcntLast4=,
		AcntFirst4=,BIN=,Name=DenovoPay,FeeLabel=CustomFee,BaseAmount=1.00,TxnCode=1,
		TaxCity=0.00,Tax1Label=,TaxState=0.00,Tax2Label=,TipLine=0,RespCode=,RRN=,
		TraceNum=,HostTxnId=,txnId=,PrintSaveMsg=,L2L3flag=,TxnType=2,EntryType=Chip,
		TotalAmt=1.00,TaxAmount=0.00,isGiftMode=false,GiftBalAmount=,ebtCashBalAmount
		=,isWalletMode=false,txnLabel=DEBIT SALE,declineReason=Transaction timeout. Please try again later.</ExtData>
	</response>
</xmp>
  • Sample Request to Terminal with Payment Type as user Choice:
Sample Request to Terminal with Payment Type as user Choice
 
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
	<PaymentType>userChoice</PaymentType>
	<TransType>Sale</TransType>
	<Amount>1.00</Amount>
	<RefId>2</RefId>
	<RegisterId>3</RegisterId>
	<AuthKey>234123-74653252-663525223</AuthKey>
	<TPN>123456789123</TPN>
	<PrintReceipt>Both</PrintReceipt>
	<PerformedBy>sample@email-account-id</PerformedBy>
</request>

Set Custom Timeout for Transactions

The default timeout after which SPIn Proxy will send the “operations timed out” error is 120 seconds. However, some scenarios may require a longer timeout. For instance, during curbside checkout, where the merchant takes the payment device to the customer’s car, the register, POS, or server may need more time to complete the transaction.

To set a custom timeout, use the OperationalTimeout tag to adjust the timeout period accordingly, ensuring the process is not prematurely interrupted.

<OperationalTimeout>120</OperationalTimeout>

 
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
	<PaymentType>Debit</PaymentType>
	<TransType>Sale</TransType>
	<Amount>3.65</Amount>
	<Tip>0.00</Tip>
	<CashbackAmount>0.00</CashbackAmount>
	<CustomFee>0.00</CustomFee>
	<RefId>171</RefId>
	<RegisterId>3748036</RegisterId>
	<TPN>123456789123</TPN>
	<MerchantId>123456789143</MerchantId>
	<AuthKey>UAqzib8AYx</AuthKey>
	<PrintReceipt>Merchant</PrintReceipt>
	<SigCapture>No</SigCapture>
	<OperationalTimeout>150</OperationalTimeout>
</request>

Capture/Ticket Request

Pre-Auth (Auth-Only) transactions allow users to hold a specific amount for processing at a later time without needing to re-enter account details. A Capture/Ticket Request is used to finalize an Auth-Only (Ticket) transaction, ensuring the held amount is processed without requiring the account data to be entered again.

Follow the steps and references outlined in this section to perform a Capture/Ticket transaction.

Capture request used to post capture an Auth only transaction without re-entering account data.

Request Fields Definition

NameData TypeM/ODescription
RefId * VarChar(50) M

Alphanumeric reference field. Echo back the original value from request.

RegisterId * VarChar(50) M

Alphanumeric reference field.

TPN * VarChar(12) O

Alphanumeric TPN field.

AuthKey * String(25) O

Specifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey.

TransType * String(20) M

Identifies the type of transaction to be run – Capture

Amount * Float(10) M

Dollar amount of the transaction. ($$$$$$$.CC)

Tip * Float(10) O

Dollar amount of the transaction. ($$$$$$$.CC)

Note: Tip must be enabled on terminal

RefId * VarChar(50) M

Alphanumeric reference field. Must be the same as a Reference ID from original transaction.

MerchantId * VarChar(12) O

Optional – For regular transactions when Multi MID (MMID) is not enabled.

Mandatory – When Multi MID (MMID) is enabled, the MerchantId must be provided. This should be the TPN (Terminal Provider Number) through which the transaction is intended to be processed.

In the iPOSpays environment, each MID is tied to a specific TPN, so it's essential to send the correct TPN to ensure the transaction routes to the appropriate MID.

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alphanumeric reference field. Echo back the original value from request.

RegisterId * VarChar(50)

Alphanumeric reference field. Echo from original request.

TPN * VarChar(12)

Alphanumeric TPN field.

ResultCode * VarChar(50)

Transaction status: 0-succeeded, 1-failed

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

0 – Success (tip was added)

1- Not Found (transaction not found)

2 – Canceled (user press cancel during a prompt)

– Failure (system error)

2 – No open batch (no open batch in a terminal)

PaymentType * VarChar(50)

An alphabetical string representing the payment type used for processing transactions. The payment type can be dynamically switched based on rules within the payment application. For example, a Credit Visa card can be processed as Debit, either through automatic BIN table lookup or user selection at the Credit/Debit prompt.

  • Request to Terminal:
Request to Terminal
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
	<AuthKey>234123-74653252-663525223</AuthKey >
	<RegisterId>3</RegisterId>
	<TPN>123456789123</TPN>
	<MerchantId>123456789143</MerchantId>
	<TransType>Capture</TransType>
	<Amount>100.00</Amount>
	<Tip>10.00</Tip>
	<RefId>2</RefId>
	<AcntLast4>0403</AcntLast4>
</request>
Response from Terminal:
<xmp>
	<response>
		<RefId>2</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<ResultCode>0</ResultCode>
		<Message>Success</Message>
		<AuthCode>292249</AuthCode>
		<PNRef>1807027</PNRef>
		<PaymentType>Credit</PaymentType>
		<ExtData>InvNum=1,CardType=VISA,BatchNum=1,Tip=0.00, CashBack=0.00,Fee=0.00,AcntLast4=1234,Name=Dejavoo, TotalAmt=1.00,DISC=0.00,SHFee=0.00,EBTFSAvailBalance=,EBTCashAvailBalance=,EntryType=Swipe,TaxCity=0.00,TaxState=0.00,Cust1=,Cust1Value=,Cust2=,Cust2Value=,Cust3=,Cust3Value=,AcntFirst4=4111,TaxAmount=0.00
		</ExtData>
	</response>
</xmp>

Tip Adjustment Request

Tip Adjustment enables users to modify the tip amount on a transaction before the batch is settled and sent to the processor. This feature is available only if tip is enabled for the TPN on the portal. Additionally, the host system must use data from the original transaction to allow the terminal to locate and update the tip amount.

Follow the steps and references outlined in this section to perform a tip adjustment.

Request Fields Definition

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alphanumeric reference field.

TPN * VarChar(12) O

Alphanumeric TPN field.

AuthKey * String(25) O

Specifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey.

TransType * String(20) M

Identifies the type of transaction to be run – TipAdjust

Amount * Float(10) M

Base dollar amount of the original transaction. ($$$$$$$.CC)

Tip * Float(10) O

Dollar amount of the transaction. ($$$$$$$.CC)

Note: Tip must be enabled on terminal

RefId * VarChar(50) M

Alphanumeric reference field. Must be the same as a Reference ID from the original transaction.

MerchantId * VarChar(12) O

Optional – For regular transactions when Multi MID (MMID) is not enabled.

Mandatory – When Multi MID (MMID) is enabled, the MerchantId must be provided. This should be the TPN (Terminal Provider Number) through which the transaction is intended to be processed.

In the iPOSpays environment, each MID is tied to a specific TPN, so it's essential to send the correct TPN to ensure the transaction routes to the appropriate MID.

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alphanumeric reference field. Echo back the original value from request.

RegisterId * VarChar(50)

Alphanumeric reference field.

TPN * VarChar(12)

Alphanumeric TPN field.

ResultCode * VarChar(50)

Transaction status: 0-succeeded, 1-failed

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

0 – Success (tip was added)

1 - Not Found (transaction not found)

2 – Canceled (user press cancel during a prompt)

3 – Failure (system error)

4 – No open batch (no open batch in a terminal)

PaymentType * VarChar(50)

Alphabetical string indicating a payment type used for processing transactions. The payment type can be switched based on rules embedded in the payment application. For example, a Credit Visa card can be processed as Debit, either based on an automatic BIN table lookup or user selection at the Credit/Debit prompt.

  • Request to Terminal:
Request to Terminal
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
 
<AuthKey>234123-74653252-663525223</AuthKey >
<RegisterId>3</RegisterId>
<TPN>123456789123</TPN>
<TransType>TipAdjust</TransType>
<MerchantId>123124125134</MerchantId>
<Amount>100.00</Amount>
<Tip>10.00</Tip>
<RefId>2</RefId>
<AcntLast4>0403</AcntLast4>
</request>
Response from Terminal
<xmp>
	<response>
		<RefId>2</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<ResultCode>0</ResultCode>
		<Message>Success</Message>
		<AuthCode>292249</AuthCode>
		<PNRef>1807027</PNRef>
		<PaymentType>Credit</PaymentType>
		<ExtData>InvNum=1,CardType=VISA,BatchNum=1,Tip=0.00, CashBack=0.00,Fee=0.00,AcntLast4=1234,Name=Dejavoo, SVC=0.00,TotalAmt=1.00,DISC=0.00,SHFee=0.00,EBTFSAvailBalance=,EBTCashAvailBalance=,EntryType=Swipe,TaxCity=0.00,TaxState=0.00,Cust1=,Cust1Value=,Cust2=,Cust2Value=,Cust3=,Cust3Value=,AcntFirst4=4111,TaxAmount=0.00</ExtData>
	</response>
</xmp>

Void Transaction Request

A Void Transaction request is used to cancel a previously authorized transaction before the batch is closed and sent to the processor. The host system must use data from the original transaction to allow the terminal to locate and process the Void request.

Follow the steps and references outlined in this section to void a transaction.

Request Fields Definition

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alphanumeric reference field.

TPN * VarChar(12) O

Alphanumeric TPN field.

PaymentType * String(20) M

Identifies EDC type: Credit, Debit, Check, Gift, Loyalty

AuthKey * String(25) O

Specifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service

TransType * String(20) M

Identifies the type of transaction to be run – Void

Amount * Float(10) M

Base dollar amount of the original transaction. ($$$$$$$.CC)

RefId * VarChar(50) M

Alphanumeric reference field. Must be the same as a Reference ID from original transaction.

MerchantId * VarChar(12) O

Optional – For regular transactions when Multi MID (MMID) is not enabled.

Mandatory – When Multi MID (MMID) is enabled, the MerchantId must be provided. This should be the TPN (Terminal Provider Number) through which the transaction is intended to be processed.

In the iPOSpays environment, each MID is tied to a specific TPN, so it's essential to send the correct TPN to ensure the transaction routes to the appropriate MID.

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alphanumeric reference field. Echo back the original value from request.

RegisterId * VarChar(50)

Alphanumeric reference field.

TPN * VarChar(12)

Alphanumeric TPN field.

ResultCode * VarChar(50)

Transaction status: 0-succeeded, 1-failed

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

0 – Success (tip was added)

1 - Not Found (transaction not found)

2 – Canceled (user press cancel during a prompt)

3 – Failure (system error)

2 – No open batch (no open batch in a terminal)

PaymentType * VarChar(50)

Alphabetical string indicating a payment type used for processing original transaction.

Request to Terminal
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
	<AuthKey>234123-74653252-663525223</AuthKey >
	<RegisterId>1</RegisterId>
	<TPN>123456789123</TPN>
	<MerchantId>123124125126</MerchantId>
	<PaymentType>Credit</PaymentType>
	<TransType>Void</TransType>
	<Amount>11.00</Amount>
	<RefId>3</RefId>
</request>
Response from Terminal
<xmp>
	<response>
		<RefId>2</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<ResultCode>0</ResultCode>
		<Message>Success</Message>
		<AuthCode>292249</AuthCode>
		<PNRef>1807027</PNRef>
		<PaymentType>Credit</PaymentType>
		<ExtData>InvNum=1,CardType=VISA,BatchNum=1,Tip=0.00, CashBack=0.00,Fee=0.00,AcntLast4=1234,Name=Dejavoo, TotalAmt=1.00,DISC=0.00,SHFee=0.00,EBTFSAvailBalance=,EBTCashAvailBalance=,EntryType=Swipe,TaxCity=0.00,TaxState=0.00,Cust1=,Cust1Value=,Cust2=,Cust2Value=,Cust3=,Cust3Value=,AcntFirst4=4111,TaxAmount=0.00</ExtData>
	</response>
</xmp>

Transaction Status Request

A Transaction Status Request allows the host system to check the result of a previously initiated transaction, typically when communication between the host system and the terminal was interrupted while the transaction request was pending.

Follow the steps and references outlined in this section to check the transaction status.

Request Fields Definition

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alphanumeric reference field.

TPN * VarChar(12) O

Alphanumeric TPN field.

PaymentType * String(20) M

Identifies EDC type: Credit, Debit, Check, Gift, Loyalty

AuthKey * String(25) O

Specifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service

TransType * String(20) M

Identifies the type of transaction to be run – Status

RefId * VarChar(50) M

Alphanumeric reference field. Must be the same as a Reference ID from original transaction.

PrintReceipt * VarChar(50) O

An optional tag. Possible values:

1. No – (default) transaction receipt won’t be printed on terminal

2. Merchant – print Merchant copy only

3. Customer – print Customer copy only

4. Both – print both Merchant and Customer copies

MerchantId * VarChar(12) O

Optional – For regular transactions when Multi MID (MMID) is not enabled.

Mandatory – When Multi MID (MMID) is enabled, the MerchantId must be provided. This should be the TPN (Terminal Provider Number) through which the transaction is intended to be processed.

In the iPOSpays environment, each MID is tied to a specific TPN, so it's essential to send the correct TPN to ensure the transaction routes to the appropriate MID.

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alphanumeric reference field. Echo back the original value from request.

RegisterId * VarChar(50)

Alphanumeric reference field.

TPN * VarChar(12)

Alphanumeric TPN field.

ResultCode * VarChar(50)

Transaction status: 0-succeeded, 1-failed

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

0 – Success (tip was added)

1- Not Found (transaction not found)

2 – Canceled (user press cancel during a prompt)

3– Failure (system error)

2 – No open batch (no open batch in a terminal)

PaymentType * VarChar(50)

Alphabetical string indicating a payment type used for processing original transaction. Populated if a transaction was found in the DB.

RespMSG * VarChar(50)

Alphanumeric field from gateway. Populated if transaction was found in the DB.

AuthCode * VarChar(50)

Alphanumeric field from gateway. Populated if transaction was found in the DB.

PNRef * VarChar(50)

Alphanumeric field from gateway. Populated if transaction was found in the DB.

EMVData * VarChar(100)

Additional transaction data specific to EMV transactions required to be present on receipt:

AID: Application ID from ICC

AppName: Application Name from ICC

TVR: Terminal verification results

TSI: Transaction status information

Populated if a transaction was found in the DB.

Sign * Base64

Base64 encoded signature image in b/w bitmap format

Populated if a transaction was found in the DB and signature file is present.

ExtData * VarChar(50)

Additional transaction data as defined in “Error! Reference source not found.”

Populated if a transaction was found in the DB and signature file is present.

Request to Terminal
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
	<AuthKey>234123-74653252-663525223</AuthKey >
	<PaymentType>Credit</PaymentType>
	<RegisterId>3</RegisterId>
	<TPN>123456789123</TPN>
	<MerchantId>123456789123</MerchantId>
	<TransType>Status</TransType>
	<RefId>3</RefId>
	<PrintReceipt>Merchant</PrintReceipt>
</request>
Response from Terminal
<xmp>
	<response>
		<RefId>3</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<InvNum>1</InvNum>
		<ResultCode>0</ResultCode>
		<RespMSG>Approved</RespMSG>
		<Message>Approved</Message>
		<AuthCode>292249</AuthCode>
		<PNRef>1807027</PNRef>
		<PaymentType>Credit</PaymentType>
		<ExtData>InvNum=1,CardType=VISA,BatchNum=1,Tip=0.00, CashBack=0.00,Fee=0.00,AcntLast4=1234,Name=Dejavoo, TotalAmt=1.00,DISC=0.00,EBTFSAvailBalance=0.00, EBTCashAvailBalance=0.00, EntryType=Swipe,TaxCity=0.00,TaxState=0.00,Cust1=,Cust1Value=,Cust2=,Cust2Value=,Cust3=,Cust3Value=,AcntFirst4=4111,TaxAmount=0.00/ExtData>
	</response>
</xmp>

Request for Settlement

A Request for Settlement is used to initiate the terminal’s batch settlement with the payment processor. At the end of the business hours, 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.

Follow the steps and references outlined in this section to initiate the terminal’s batch settlement.

Request Fields Definition

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alphanumeric reference field.

TPN * VarChar(12) O

Alphanumeric TPN field.

AuthKey * String(25) M

Specifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service

RefId * VarChar(50) M

Alphanumeric reference field.

TransType * String(20) M

Identifies the type of transaction to be run – Settle

Param * String(20) M

Type of Settlement request:

1. Close: normal closing

2. Force: Force batch totals

MerchantId * VarChar(12) O

which the batch settlement will be requested.

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alphanumeric reference field. Echo back the original value from request.

RegisterId * VarChar(50)

Alphanumeric reference field.

TPN * VarChar(12)

Alphanumeric TPN field.

ResultCode * VarChar(50)

Overall status of all application’s ResultCode in ExtData: 0-succeeded, 1-failed.

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

0 – Success

1 - Failure

AuthCode * VarChar(50)

Alphanumeric field from gateway.

ExtData * VarChar(512)

Additional transaction data per application.

List and explanation of possible data

App: Application (DvCredit, DvCheck, DvGift)

ResultCode:

0 – success (Host closed batch, Batch not open,Batch Already Settled)

1 – failed (Host failed batch),

2 – SNF Pending Transactions

3 – Untipped transactions

4 – Open Tab

BatchNum: batch number

Status: Host data or 0

NumTrans: number of transactions in open batch

TipAmt: total tip amount

TotalAmt: total amount

Request to Terminal
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
	<RegisterId>3</RegisterId>
	<TPN>123456789123</TPN>
	<MerchantId>123124125126</MerchantId>
	<AuthKey>234123-74653252-663525223</AuthKey >
	<RefId>2</RefId>
	<TransType>Settle</TransType>
	<Param>Close</Param>
</request>
Response from Terminal
<xmp>
	<response>
		<RefId>2</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<ResultCode>0</ResultCode>
		<Message>Success</Message>
		<ExtData>App=DvCredit, Merchant=CREDIT, ResultCode=0, BatchNum=34,Rsp=BATCH  RELEASED, Status=0, NumTrans=0, TipAmt=0.00, TotalAmt=0.00</ExtData>
		<ExtData>App=DvCheck, ResultCode=0, BatchNum=0, Rsp=Offline, NumTrans=1, Total=1.00</ExtData><ExtData>App=DvGift, ResultCode=0, BatchNum=0, Rsp=Batch Already Settled</ExtData>
	</response>
</xmp>

Printout Request

If the selected terminal model includes an integrated printer, it can be used as an external printer for the integrated POS system’s printing functionality. The terminal supports printing in the Courier New font, with a default width of 24 characters per line.

Follow the steps and references outlined in this section to print transaction receipts by sending a request from the server, register, or POS to the integrated Dejavoo payment terminal.

Request Fields Definition

NameData TypeM/ODescription
AuthKey * String(25) M

Specifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service

RegisterId * VarChar(50) M

Alphanumeric reference field.

TPN * VarChar(12) O

Alphanumeric TPN field.

RefId * VarChar(50) O

Alphanumeric reference field.

printer * N/A M

Indicates a block of text for printing

1. width can be set to 24 or 48 characters per line

removeExtraSpaces can be set to On/Off. This will remove or keep extra spaces in a text

t * VarChar(40) M

Text to print

b * N/A O

Indicates that text should be printed in bold

c * N/A O

Indicates that text should be printed centered

If * N/A O

Indicates that printer should feed a line after current string

inv * N/A O

Indicates that the following text should be printed inverted. Whole line till <lf> will be inverted.

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alphanumeric reference field. Echo back the original value from request.

RegisterId * VarChar(50)

Alphanumeric reference field.

TPN * VarChar(12)

Alphanumeric TPN field.

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

Success – Printout was successful

No Paper – Paper needs to be replaced

Error – Other Error

Request to Terminal
 
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?Printer=
 
<request>
	<AuthKey>234123-74653252-663525223</AuthKey >
	<RegisterId>3</RegisterId>
	<TPN>123456789123</TPN>
	<printer width="24">
		<t>
			<c>
				<b>Header</b>
			</c>
		</t>
		<l0f/>
		<t>02-15-2014</t>
		<t>09:45:29</t>
		<lf/>
		<t>Trans. Number:</t>
		<t>1</t>
		<img>Qk2uCAAAAAAAAD4AAAAoAAAACwEAADwAAAABAAEAAAAAAHAIAADEDgAAxA4AAAAAAAAAAAAAAAAAAP</img>
	</printer>
</request>
Response from Terminal
<xmp>
	<response>
		<RefId>2</RefId>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<Message>Success</Message>
	</response>
</xmp>

If two text strings are sent sequentially until <lf> is found, these first line will be printed left justified and second – right justified on the same line.

User Choice Request

This API is used to prompt the cardholder to select their preferred payment type, which is displayed on the payment terminal. The selected option is then passed back to the register. For example, the register can initiate a transaction and send a request to the payment terminal. If one of the options presented is a debit card and the cardholder chooses to pay using it, the chosen payment type (Debit card)will be included in the response sent back to the register.

Follow the steps and references outlined in this section to prompt a user choice request on the payment terminal.

Request Fields Definition

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alphanumeric reference field.

TPN * VarChar(12) O

Alphanumeric TPN field.

AuthKey * String(25) O

Specifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey.

UserChoice * String M

Requests user selection from the list of items; choices provided in a form of a menu.

title – specifies a title for the choice menu

count – specifies number of choices

timeout – time in seconds for the Terminal to wait for user input

Choice * String M

An item for the list of choices. Each list item must be enclosed within its own choice tag

Response Fields Definitions

NameData TypeDescription
RegisterId * VarChar(50)

Alphanumeric reference field.

TPN * VarChar(12)

Alphanumeric TPN field.

UserChoice * String

Response to Request for a user choice

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

Success

Failure

Cancel

Request to Terminal
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
 
<request>
	<RegisterId>3</RegisterId>
	<TPN>123456789123</TPN>
	<AuthKey>234123-74653252-663525223</AuthKey >
	<UserChoice title="Choose Payment Type:" count="4">
		<Choice>Cash</Choice>
		<Choice>Card</Choice>
		<Choice>Gift</Choice>
		<Choice>Coupon</Choice>
	</UserChoice>
</request>
Response from Terminal
<xmp>
	<response>
		<RegisterId>3</RegisterId>
		<TPN>123456789123</TPN>
		<UserChoice>Cash</UserChoice>
	</response>
</xmp>

User Input Request

With the User Input request API, customers will be prompted to enter the required additional data on the terminal.

Use cases

In a restaurant setting, the POS application can prompt the waiter’s payment device to request an order number. The waiter enters the order number directly on the terminal, which is sent back to the POS application. This enables the payment amount to be processed for the specified order, reducing the need for the waiter to make multiple trips between the cash counter and the table.

Follow the steps and references outlined in this section to prompt a user input request on the payment terminal.

Request Fields Definition

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alphanumeric reference field.

AuthKey * String(25) O

Specifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey.

UserInput * Input M

Custom interactions with the user via the terminal for collecting additional data or information.

The UserInput tag has the following input attributes

title = “<title of user input”>, 2. maxlen = “<max-len of user input”>, 3. type = “n / an / a / $n / i”

title -> title of the custom user input.

maxlen -> maximum length of the custom user input.

type -> input data type as follows Numeric (n), Alphanumeric (an), Alphabets (a), Money ($n), Info (i) – any general input

Response Fields Definitions

NameData TypeDescription
RegisterId * VarChar(50)

Alphanumeric reference field.

UserInput * String

Response value to request for a user input.

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

Success

Failure

Cancel

Example:

HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=

  1. Type: NUMERIC
Request to Terminal
<request>
	<RegisterId>9724703</RegisterId>
	<AuthKey>giVVxrGs5bn</AuthKey>
	<UserInput title="Enter phone" maxlen="10" type="n"/>
</request>
Response from Terminal
<xmp>
	<response>
		<RegisterId>9724703</RegisterId>
		<Message>Success</Message>
		<UserInput>1234567890</UserInput>
	</response>
</xmp>
  1. TYPE : ALPHANUMERIC
Request to Terminal
<request>
	<RegisterId>9724703</RegisterId>
	<AuthKey>giVVxrGs5bn</AuthKey>
	<UserInput title="Enter Address" maxlen="20" type="an"/>
</request>
Response from Terminal
<xmp>
	<response>
		<RegisterId>9724703</RegisterId>
		<Message>Success</Message>
		<UserInput>No 101 15th Ave</UserInput>
	</response>
</xmp>
  1. TYPE : ALPHA
Request to Terminal
<request>
	<RegisterId>9724703</RegisterId>
	<AuthKey>giVVxrGs5bn</AuthKey>
	<UserInput title="Enter name" maxlen="15" type="a"/>
</request>
Response from Terminal
<xmp>
	<response>
		<RegisterId>9724703</RegisterId>
		<Message>Success</Message>
		<UserInput>David</UserInput>
	</response>
</xmp>
  1. TYPE : MONEY
Request to Terminal
<request>
	<RegisterId>9724703</RegisterId>
	<AuthKey>giVVxrGs5bn</AuthKey>
	<UserInput title="Enter amount" maxlen="5" type="$n"/>
</request>
Response from Terminal
<xmp>
	<response>
		<RegisterId>9724703</RegisterId>
		<Message>Success</Message>
		<UserInput>50.89</UserInput>
	</response>
</xmp>
  1. TYPE : INFO
Request to Terminal
<request>
	<RegisterId>9724703</RegisterId>
	<AuthKey>giVVxrGs5bn</AuthKey>
	<UserInput title="Enter Address" maxlen="20" type="i"/>
</request>
Response from Terminal
<xmp>
	<response>
		<RegisterId>9724703</RegisterId>
		<Message>Success</Message>
		<UserInput>No:101, 20th Ave</UserInput>
	</response>
</xmp>

Get Card Request

The GetCard request API allows the POS system to prompt the customer to present their card using a supported method—such as swiping or manually entering the card number—on the terminal. Once the card is provided, the relevant card data is securely transmitted back to the POS for further use.

Use Case

This API is ideal for merchants who support features like gift cards, loyalty programs, or customer registration. For example, when a customer wants to redeem points, link their account, or activate a gift card, the merchant can trigger this request to let the customer enter their card details directly on the terminal—avoiding manual entry on the POS and ensuring a secure and smooth experience.

Follow the steps and field references below to prompt a GetCard request on the payment terminal.

Request Fields Definitions

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alphanumeric reference field.

AuthKey * String(25) O

AuthKey authorizes the Host system to use the SPIn™ Web Service; required if the terminal is configured to use AuthKey.

GetCard * Input M

Instructs the terminal to initiate a card capture operation, prompting the customer to present their card via swipe, tap, insert, or manual entry. The card data is then securely returned to the POS.

Note:

The following attributes are part of the <GetCard> tag structure but are not supported in the current release and will be ignored by the terminal:

prompt: Custom message to be displayed on the terminal screen.

timeout: Time (in seconds) to wait for card input.

Response Fields Definitions

NameData TypeDescription
RegisterId VarChar(50)

Alphanumeric reference field.

GetCard Object

Contains card information fields. Present only in successful responses.

Message VarChar(50)

Provides a descriptive result message in case of failure (e.g., “Invalid card input”).

Track2 String

Sub-tag under GetCard. Provides the Track 2 data when the card is swiped.

Track1 String

Sub-tag under GetCard. Provides the Track 1 data when the card is swiped.

Account String

Sub-tag under GetCard. Returns the card number when entered manually.

EntryType String

Specifies the card input method. Possible values: Swipe, Manual Entry.

Example:

Response from Terminal: HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=

Request to Terminal
<request>
	<RegisterId>1842005</RegisterId>
	<AuthKey>NQnb45vZr6</AuthKey>
	<GetCard prompt="" timeout="120"/>
</request>
Response from Terminal Example 1: Swipe
<xmp>
	<response>
		<RegisterId>1842005</RegisterId>
		<TPN/>
		<GetCard>
			<Track1 data="B921986148302846^"/>
			<Track2 data="921986148302846="/>
			<EntryType>Swipe</EntryType>
		</GetCard>
	</response>
</xmp>
Response from Terminal Example 2: Manual Entry
<xmp>
	<response>
		<RegisterId>1842005</RegisterId>
		<TPN/>
		<GetCard>
			<Account data="921986139610277"/>
			<EntryType>Manual Entry</EntryType>
		</GetCard>
	</response>
</xmp>
Response from Terminal Example 3: (failure)
<xmp>
	<response>
		<ResultCode>1</ResultCode>
		<Message>Invalid card input</Message>
	</response>
</xmp>

Batch Report Request

The broadcast batch report service allows users to retrieve the status and details of the current open batch, which includes all transactions processed during the user’s business hours. The ReportType request field specifies the type of report to be generated.

  • The Summary Report provides an overview of the batch, including totals for each transaction type.

  • The Daily Report offers a detailed breakdown of every transaction conducted on each day.

Follow the steps and references outlined in this section to retrieve the status and details of a current open batch.

Request Fields Definition

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alphanumeric reference field.

AuthKey * String(25) O

Specifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey.

ReportType * String(25) M

It refers to the type of the report either “Summary” or “Daily”.

TransType * String(10) M

TransType must be set to “Report” for this open batch daily or summary report request

MerchantId * VarChar(12) O

Optional – For regular transactions when Multi MID (MMID) is not enabled.

Mandatory – When Multi MID (MMID) is enabled, the MerchantId must be provided. This should be the TPN (Terminal Provider Number) through which the transaction is intended to be processed.

In the iPOSpays environment, each MID is tied to a specific TPN, so it's essential to send the correct TPN to ensure the transaction routes to the appropriate MID.

Response Fields Definitions

NameData TypeDescription
RegisterId * VarChar(50)

Alphanumeric reference field.

ResultCode * String

It responded with a Result Code

Message * VarChar(50)

Alphanumeric field providing detailed result message for each result code:

Success

Failure

Cancel

TransReport * Text

It responds with an open batch summary or daily report.

If ReportType is Summary while request -> “TransReport” is responded with an open batch summary report including the total of each transaction type (i.e. card & alternate payments).

If Report Type is Daily while request -> “TransReport” is responded with an open batch daily report of every transaction conducted.

Example:

HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=

  • Summary Report
Request to Terminal
HTTPS://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
<request>
	<RegisterId>9724703</RegisterId>
	<AuthKey>giVVxrGs5bn</AuthKey>
	<MerchantId>123124125126</MerchantId>
	<ReportType>Summary</ReportType>
	<TransType>Report</TransType>
</request>
Response from Terminal
<xmp>
	<response>
		<RegisterId>9724703</RegisterId>
		<ResultCode>0</ResultCode>
		<Message>Success</Message>
		<TransReport>App=DvPayLiteCredit, SaleAmt=23.29, TrnsCnt=2, ReturnAmt=16.00, VoidAmt=0.00, AuthAmt=0.00, TicketAmt=0.00, ReversalAmt=0.00, CashAdvanceAmt=0.00, TotalAmt=7.29</TransReport>
		<TransReport>App=DvPayLiteCashAlter, SaleAmt=16.0, ReturnAmt=0.00, VoidAmt=0.00, TotalAmt=16.0</TransReport>
	</response>
</xmp>
  • Daily Report:
Request to Terminal
<request>
	<RegisterId>9724703</RegisterId>
	<AuthKey>giVVxrGs5bn</AuthKey>
	<MerchantId>123124125126</MerchantId>
	<ReportType>Daily</ReportType>
	<TransType>Report</TransType>
</request>
Success Response
<xmp>
	<response>
		<RegisterId>9724703</RegisterId>
		<ResultCode>0</ResultCode>
		<Message>Success</Message>
		<TransReport>
			<App>DvPayLiteCredit</App>
			<Total>2</Total>
			<TotalAmt>7.29</TotalAmt>
			<Trans>NUM=1, TransType=SALE, Amt=23.29</Trans>
			<Trans>NUM=2, TransType=REFUND, Amt=16.00</Trans>
		</TransReport>
		<TransReport>
			<App>DvPayLiteCashAlter</App>
			<Total>1</Total>
			<TotalAmt>16.00</TotalAmt>
			<Trans>NUM=1, TransType=CASH, Amt=16.00</Trans>
		</TransReport>
	</response>
</xmp>
Negative Response
<xmp>
	<response>
		<Message>Failure</Message>
		<RegisterId>9724733</RegisterId>
		<ResultCode>1</ResultCode>
		<RespMSG>There is no transaction in th batch</RespMSG>
		<Voided>false</Voided>
		<TransType>Report</TransType>
	</response>
</xmp>

Level 2 & Level 3 Data

Level 2 and Level 3 (L2/L3) data should be sent to the processors to exercise interchange benefits for eligible cards.

Follow the steps and references outlined in this section to transmit Level 2 and Level 3 transaction data from the cash register application to the integrated Dejavoo payment terminal.

Example

https://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction= (opens in a new tab)

Request to Terminal
https://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
<request>
	<RegisterId>1103024</RegisterId>
	<AuthKey>ulHLsaxfbg</AuthKey>
	<PaymentType>Credit</PaymentType>
	<TransType>Sale</TransType>
	<Amount>10.00</Amount>
	<RefId>61</RefId>
	<AuthCode>TAS852</AuthCode>
	<TaxAmount>0.52</TaxAmount>
	<LocalTaxFlag>TaxProvided</LocalTaxFlag>
	<NationalTaxAmount>1.04</NationalTaxAmount>
	<CustRef>123456</CustRef>
	<DestZipCode>12345</DestZipCode>
	<CustomerVatReg>12345678</CustomerVatReg>
	<SummaryCommodityCode>01</SummaryCommodityCode>
	<TaxRateApplied>15.00</TaxRateApplied>
	<TotalDiscountAmount>0</TotalDiscountAmount>
	<PoNumber>10123456</PoNumber>
	<FreightAmount>0</FreightAmount>
	<DutyAmount>0</DutyAmount>
	<ShipfromZipCode>11111</ShipfromZipCode>
	<DestCountryCode>840</DestCountryCode>
	<MerchantTaxId>999999</MerchantTaxId>
	<CustomerTaxId>999999</CustomerTaxId>
	<LineItemCount>1</LineItemCount>
	<Level3LineItems>
		<group>
			<CommodityCode>12</CommodityCode>
			<Description>Item1</Description>
			<ProductCode>12</ProductCode>
			<Quantity>1</Quantity>
			<UnitOfMeasure>ITM</UnitOfMeasure>
			<UnitCost>10.40</UnitCost>
			<VatTaxAmount>0</VatTaxAmount>
			<VatTaxRate>0</VatTaxRate>
			<DiscountAmount>0</DiscountAmount>
			<DiscountRate>0</DiscountRate>
			<LocalTaxAmount>0.52</LocalTaxAmount>
			<NationalTaxAmount>1.04</NationalTaxAmount>
			<LocalTaxRate>5.00</LocalTaxRate>
			<StateTaxRate>10.00</StateTaxRate>
			<TaxAmount>1.56</TaxAmount>
			<TaxRate>15.00</TaxRate>
			<TotalAmount>11.96</TotalAmount>
		</group>
	</Level3LineItems>
</request>
Response from Terminal
<xmp>
	<response>
		<Message>APPROVED</Message>
		<RefId>61</RefId>
		<RegisterId>7121902</RegisterId>
		<ResultCode>1</ResultCode>
		<RespMSG>APPROVED</RespMSG>
		<PaymentType>Sale</PaymentType>
		<Voided>false</Voided>
		<TransType>Sale</TransType>
		<SN>B17912107210009</SN>
		<ExtData>Amount=10.00,dueAmnt=,isPartialApprovalTxn=false,approvedAmnt=,InvNum=,CardType=,Tip=4.00,
Fee=0.00,Disc=0.00,DiscLabel=,BatchNum=1,CashBack=0.00,AcntLast4=,AcntFirst4=,BIN=,Name=DenovoPay,
FeeLabel=,BaseAmount=10.00,TxnCode=1,TaxCity=2.00,Tax1Label=Local Tax,customCashMessage=,customCreditMessage=,,TaxState=1.00,Tax2Label=State Tax,TipLine=0,RespCode=,RRN=,TraceNum=,HostTxnId=,txnId=,PrintSaveMsg=savingssss $0.73,L2L3flag=,TxnType=4,EntryType=Swipe,TotalAmt=17.00,TaxAmount=3.00,isGiftMode=false,
GiftBalAmount=,ebtCashBalAmount=,isWalletMode=false,txnLabel=SALE,surveyQuestion=,surveyAnswer=,
walletPayMethod=,walletTxnPaymentNum=,walletTxnData=,deviceId=,walletConfirmationId=,SignLine=,SignPath=,profileId=,
profileName=,offlinePin=false,fallBackMode=0,,networkMode=,txnStartTime=0,txnEndTime=0,pagoWalletFlashMessage=,
pagoConfirmationCode=,pagoCommittedTransactionId=,pagoMerchantTransactionId=,
ReducedTax=$0.00,ReducedTaxFee=0.00,RTaxLabel=,ExpDate=,MSRPLabel=,MSRPAmount=,DateTime=20230929073517,
declineReason=</ExtData>
	</response>
</xmp>
NameData TypeDescription
TaxRateApplied * String

Sum of all tax rate

TotalDiscountAmount * String

Sum of each item discount

PoNumber * String

PO number is a unique number given to a particular order placed before the seller and allows numbers.

DiscountRate * String

Item level discount rate

LocalTaxAmount * String

Sum of local tax amount for item level

NationalTaxAmount * String

Sum of national tax amount for item level

LocalTaxRate * String

Local tax rate for item level

StateTaxRate * String

State tax rate for item level

TaxAmount * String

Sum of all tax amount for item level

TaxRate * String

Sum of all tax rate for item level

MerchantTaxId * String

Vat merchant tax identification number

CustomerTaxId * String

Vat customer tax identification number

Send Card Price for L2/L3

In case the host calculates the card price, follow the steps and references outlined in this section to transmit the card and cash prices, along with other Level 2 and Level 3 transaction data, from the cash register application to the integrated Dejavoo payment terminal.

Example

Request to Terminal
https://test.SPInpos.net:443/SPIn/cgi.html?TerminalTransaction=
<request>
	<RegisterId>1103024</RegisterId>
	<AuthKey>ulHLsaxfbg</AuthKey>
	<PaymentType>Credit</PaymentType>
	<TransType>Sale</TransType>
	<Amount>10.00</Amount>
	<RefId>14</RefId>
	<AuthCode>TAS852</AuthCode>
	<LineItemCount>1</LineItemCount>
	<FeeCalculated>true</FeeCalculated>
	<TaxCalculated>true</TaxCalculated>
	<TotalCardAmountWithoutDiscount>10.40</TotalCardAmountWithoutDiscount>
	<TotalCashAmountWithoutDiscount>10.00</TotalCashAmountWithoutDiscount>
	<TotalCardAmountWithDiscount>10.40</TotalCardAmountWithDiscount>
	<TotalCashAmountWithDiscount>10.00</TotalCashAmountWithDiscount>
	<FeeAmount>0.40</FeeAmount>
	<Tax1Fee>0.02</Tax1Fee>
	<Tax2Fee>0.04</Tax2Fee>
	<Tax1Label>LocalTax</Tax1Label>
	<Tax2Label>StateTax</Tax2Label>
	<Tax1CardAmount>0.52</Tax1CardAmount>
	<Tax1CashAmount>0.50</Tax1CashAmount>
	<Tax2CardAmount>1.04</Tax2CardAmount>
	<Tax2CashAmount>1.00</Tax2CashAmount>
	<TotalCardAmount>11.96</TotalCardAmount>
	<TotalCardDiscount>0</TotalCardDiscount>
	<TotalCashAmount>11.50</TotalCashAmount>
	<TotalCashDiscount>0</TotalCashDiscount>
	<LineItems>
		<group>
			<ProductName>Item1Name</ProductName>
			<CardDiscountAmount>0</CardDiscountAmount>
			<CardTotal>10.4</CardTotal>
			<CashDiscountAmount>0</CashDiscountAmount>
			<CashTotal>10.0</CashTotal>
			<Quantity>1</Quantity>
			<UnitMeasure>ITM</UnitMeasure>
			<Description>Item1 desc</Description>
			<ItemCode>10001</ItemCode>
			<UnitCostCardPrice>10.40</UnitCostCardPrice>
			<UnitCostCashPrice>10.00</UnitCostCashPrice>
		</group>
	</LineItems>
</request>
Response from Terminal
<xmp>
	<response>
		<Message>APPROVED</Message>
		<RefId>14</RefId>
		<RegisterId>7121902</RegisterId>
		<ResultCode>1</ResultCode>
		<RespMSG>APPROVED</RespMSG>
		<PaymentType>Sale</PaymentType>
		<Voided>false</Voided>
		<TransType>Sale</TransType>
		<SN>B17912107210009</SN>
		<ExtData>Amount=10.40,dueAmnt=,isPartialApprovalTxn=false,approvedAmnt=,InvNum=,CardType=,Tip=4.00,
Fee=0.00,Disc=0.00,DiscLabel=,BatchNum=1,CashBack=0.00,AcntLast4=,AcntFirst4=,BIN=,Name=DenovoPay,
FeeLabel=,BaseAmount=10.00,TxnCode=1,TaxCity=2.00,Tax1Label=LocalTax,customCashMessage=,customCreditMessage=,,
TaxState=1.00,Tax2Label=State Tax,TipLine=0,RespCode=,RRN=,TraceNum=,HostTxnId=,txnId=,PrintSaveMsg=savingssss $0.73,L2L3flag=,TxnType=4,EntryType=Swipe,TotalAmt=17.00,TaxAmount=3.00,isGiftMode=false,GiftBalAmount=,
ebtCashBalAmount=,isWalletMode=false,txnLabel=SALE,surveyQuestion=,surveyAnswer=,walletPayMethod=,
walletTxnPaymentNum=,walletTxnData=,deviceId=,walletConfirmationId=,SignLine=,SignPath=,profileId=,
profileName=,offlinePin=false,fallBackMode=0,,networkMode=,txnStartTime=0,txnEndTime=0,pagoWalletFlashMessage=,
pagoConfirmationCode=,pagoCommittedTransactionId=,pagoMerchantTransactionId=,ReducedTax
=$0.00,ReducedTaxFee=0.00,RTaxLabel=,ExpDate=,MSRPLabel=,MSRPAmount=,DateTime=20230929073517,declineReason=</ExtData>
	</response>
</xmp>

Display Cart Items on Terminal

The Display Cart Items feature allows you to show line items on the terminal screen, enabling customers to review their cart during checkout. This can be used flexibly depending on your integration flow.

Terminal Listening Behavior

When you send only line item requests, the terminal remains in listening mode. This allows you to continue sending updates as items are added to the cart. However, once a payment request is sent—either on its own or as part of a combined request—the terminal exits listening mode and cannot accept further requests until it returns to the listening screen.

Customer Alert with notifyCustomer

To enhance the customer’s checkout experience, the notifyCustomer tag can be used to trigger an audible tone on the payment terminal whenever a cart update is received. This is particularly useful in fast-paced retail environments where items are scanned rapidly or when the customer’s attention needs to be directed toward the screen.

By setting this optional Boolean field to true, the terminal emits a subtle notification sound every time a new cart item is displayed. If set to false or omitted, the terminal will update silently without auditory cues.

Use Case 1: Real-Time Cart Updates

This flow is suitable for environments where items are added one by one, such as scanning at a supermarket checkout. The terminal updates in real time to display the cart contents as they’re sent.

The key point here is that the terminal only shows what is included in each request—it doesn’t maintain a history of previous items. This gives you full control over how the cart appears on the terminal.

There are two main ways to use this:

Full Cart View

Send the full list of items in each request, so the terminal displays an incrementally growing cart.

Example:

  • Send: Item A → terminal shows: A
  • Send: A, B → terminal shows: A, B
  • Send: A, B, C → terminal shows: A, B, C

Single Item View

Send only the new item each time. The terminal will show just that item, replacing the previous one.

Example:

  • Send: Item A → terminal shows: A
  • Send: Item B → terminal shows: B
  • Send: Item C → terminal shows: C

Whether the terminal displays a running list of all items or just the most recent one depends entirely on how you format the line item request. The terminal simply displays what it receives.

Once the cart is ready, send a payment request. The terminal automatically transitions to the payment screen, and if tipping is enabled for the TPN, the tip screen will appear before proceeding.

Tip screen appears first because tipping was enabled for the TPN
Tip screen appears first because tipping was enabled for the TPN
At this point, the terminal is no longer listening and cannot accept any additional requests.
At this point, the terminal is no longer listening and cannot accept any additional requests.

Sample Request: Displaying Cart Items Only

This XML request is used when you want to show cart items on the terminal screen without initiating payment. The terminal remains in listening mode, allowing additional line items to be sent and displayed in real time.

<request>
	<AuthKey>f9eGebRfss</AuthKey>
	<TPN>z11devtest03</TPN>
	<PosID>2122</PosID>
	<notifyCustomer>true</notifyCustomer> <!-- Plays a tone on the terminal when the cart is updated to alert the customer -->
	<Cart>
		<Amounts>
			<Amount>
				<Name>Discounts</Name>
				<Value>1141</Value>
			</Amount>
			<Amount>
				<Name>Subtotal</Name>
				<Value>2154</Value>
			</Amount>
			<Amount>
				<Name>Taxes</Name>
				<Value>599</Value>
			</Amount>
			<Amount>
				<Name>Total</Name>
				<Value>2753</Value>
				<Total/>
			</Amount>
		</Amounts>
		<Items>
			<Item>
				<Name>Lunch 4</Name>
				<Price>807</Price>
				<UnitPrice></UnitPrice>
				<Quantity>1</Quantity>
				<CustomInfos>
					<CustomInfo>
						<Name>Total</Name>
						<Value>2753</Value>
					</CustomInfo>
					<CustomInfo>
						<Name>Total</Name>
						<Value>2753</Value>
					</CustomInfo>
				</CustomInfos>
				<AdditionalInfo></AdditionalInfo>
				<Modifiers>
					<Modifier>
						<Name>Modifier 3</Name>
						<Options>
							<Option>
								<Name>Value 2</Name>
								<Price>233</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
					<Modifier>
						<Name></Name>
						<Options>
							<Option>
								<Name>Business Lunch</Name>
								<Price>-208</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
					<Modifier>
						<Name></Name>
						<Options>
							<Option>
								<Name>AutoDisc10</Name>
								<Price>-104</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
				</Modifiers>
			</Item>
			<Item>
				<Name>Borsch</Name>
				<Price>723</Price>
				<UnitPrice></UnitPrice>
				<Quantity>1</Quantity>
				<CustomInfos>
					<CustomInfo>
						<Name>Total</Name>
						<Value>2753</Value>
					</CustomInfo>
					<CustomInfo>
						<Name>Total</Name>
						<Value>2753</Value>
					</CustomInfo>
				</CustomInfos>
				<AdditionalInfo></AdditionalInfo>
				<Modifiers>
					<Modifier>
						<Name>Mix</Name>
						<Options>
							<Option>
								<Name>Third</Name>
								<Price>350</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
					<Modifier>
						<Name>Mikhail Test</Name>
						<Options></Options>
					</Modifier>
					<Modifier>
						<Name>Fat</Name>
						<Options>
							<Option>
								<Name>Low fat</Name>
								<Price>1167</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
					<Modifier>
						<Name></Name>
						<Options>
							<Option>
								<Name>Glass</Name>
								<Price>15</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
					<Modifier>
						<Name></Name>
						<Options>
							<Option>
								<Name>Business Lunch</Name>
								<Price>-403</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
					<Modifier>
						<Name></Name>
						<Options>
							<Option>
								<Name>AutoDisc10</Name>
								<Price>-202</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
					<Modifier>
						<Name></Name>
						<Options>
							<Option>
								<Name>Changed</Name>
								<Price>-224</Price>
								<Quantity>1</Quantity>
							</Option>
						</Options>
					</Modifier>
				</Modifiers>
			</Item>
		</Items>
	</Cart>
</request>

Use Case 2: Display Cart with Immediate Payment

In this flow, the POS sends a single request that includes both the full list of cart items and the payment request. The terminal displays the cart, along with a CHECKOUT button.

When the customer taps CHECKOUT, the terminal proceeds to payment.

While this may seem efficient, there’s a trade-off: it relies on the customer to press the CHECKOUT button on the terminal each time. This extra step can slow down the checkout process or lead to confusion—especially in fast-paced or unattended environments.

For smoother operation, especially in retail settings with high throughput or minimal staff interaction, it’s often better to keep the checkout action under the POS’s control by using real-time cart updates followed by a separate payment request.

Sample Request: Displaying Cart Items with Payment Request
<request>
    <PaymentType>Credit</PaymentType>
    <TransType>Sale</TransType>
    <Amount>1.00</Amount>
    <Tip>0.00</Tip>
    <CashbackAmount>0.00</CashbackAmount>
    <Frequency>OneTime</Frequency>
    <CustomFee>0.00</CustomFee>
    <RefId>1</RefId>
    <notifyCustomer>true</notifyCustomer>
    <RegisterId>7767720</RegisterId>
    <AuthKey>4kCHrpZJNA</AuthKey>
    <PrintReceipt>No</PrintReceipt>
    <SigCapture>No</SigCapture>
 
    <Cart>
        <Amounts>
            <Amount>
                <Name>Discounts</Name>
                <Value>1141</Value>
            </Amount>
            <Amount>
                <Name>Subtotal</Name>
                <Value>2154</Value>
            </Amount>
            <Amount>
                <Name>Taxes</Name>
                <Value>599</Value>
            </Amount>
            <Amount>
                <Name>Total</Name>
                <Value>2753</Value>
                <Total/>
            </Amount>
        </Amounts>
 
        <Items>
            <Item>
                <Name>Lunch 4</Name>
                <Price>807</Price>
                <UnitPrice></UnitPrice>
                <Quantity>1</Quantity>
                
                <CustomInfos>
                    <CustomInfo>
                        <Name>Total</Name>
                        <Value>2753</Value>
                    </CustomInfo>
                    <CustomInfo>
                        <Name>Total</Name>
                        <Value>2753</Value>
                    </CustomInfo>
                </CustomInfos>
 
                <AdditionalInfo></AdditionalInfo>
 
                <Modifiers>
                    <Modifier>
                        <Name>Modifier 3</Name>
                        <Options>
                            <Option>
                                <Name>Value 2</Name>
                                <Price>233</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                    <Modifier>
                        <Name></Name>
                        <Options>
                            <Option>
                                <Name>Business Lunch</Name>
                                <Price>-208</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                    <Modifier>
                        <Name></Name>
                        <Options>
                            <Option>
                                <Name>AutoDisc10</Name>
                                <Price>-104</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                </Modifiers>
            </Item>
 
            <Item>
                <Name>Borsch</Name>
                <Price>723</Price>
                <UnitPrice></UnitPrice>
                <Quantity>1</Quantity>
 
                <CustomInfos>
                    <CustomInfo>
                        <Name>Total</Name>
                        <Value>2753</Value>
                    </CustomInfo>
                    <CustomInfo>
                        <Name>Total</Name>
                        <Value>2753</Value>
                    </CustomInfo>
                </CustomInfos>
 
                <AdditionalInfo></AdditionalInfo>
 
                <Modifiers>
                    <Modifier>
                        <Name>Mix</Name>
                        <Options>
                            <Option>
                                <Name>Third</Name>
                                <Price>350</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                    <Modifier>
                        <Name>Mikhail Test</Name>
                        <Options></Options>
                    </Modifier>
                    <Modifier>
                        <Name>Fat</Name>
                        <Options>
                            <Option>
                                <Name>Low fat</Name>
                                <Price>1167</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                    <Modifier>
                        <Name></Name>
                        <Options>
                            <Option>
                                <Name>Glass</Name>
                                <Price>15</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                    <Modifier>
                        <Name></Name>
                        <Options>
                            <Option>
                                <Name>Business Lunch</Name>
                                <Price>-403</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                    <Modifier>
                        <Name></Name>
                        <Options>
                            <Option>
                                <Name>AutoDisc10</Name>
                                <Price>-202</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                    <Modifier>
                        <Name></Name>
                        <Options>
                            <Option>
                                <Name>Changed</Name>
                                <Price>-224</Price>
                                <Quantity>1</Quantity>
                            </Option>
                        </Options>
                    </Modifier>
                </Modifiers>
            </Item>
        </Items>
    </Cart>
</request>

Cart Display XML Tag Reference

TagsDetailsComment
PosID

Optional

Track which register sent the request if multiple registers use the same terminal.

Cart

Optional

Tag that contains all the cart item details.

Amounts

Mandatory

Section that specifies total amounts. Displayed at the bottom of the screen.

Amount

Optional

A single line that will be shown in the Amounts section.

Name

Optional

Text for the line with the amount.

Value

Optional

Use decimals with two digits after the decimal point or integer values. Negative values are possible.

Total

Optional

Highlights which line should be displayed in a large font as the final total value.

Items

Mandatory

Section that shows items.

Item

Mandatory

Information about a single item.

Name

Mandatory

Item name. The terminal displays this in regular font.

Price

Optional

Item price. Recommended to use decimals with two digits or integer values.

Quantity

Optional

Quantity for the item. Displayed inline with the item name as x[quantity].

CustomInfos

Optional

Tag used to send custom data related to the item if required.

CustomInfo

Optional

Information about a single piece of additional data.

Name

Optional

Custom tag name.

Value

Optional

Custom tag value/data.

Additional Info

Optional

Description or other data to be displayed specific to the item.

Modifiers

Optional

Section that shows additional details about an item.

Modifier

Optional

Information about a single modifier.

Name

Optional

Modifier name.

Options

Optional

Section that contains additional information about an item that needs to be displayed on the screen.

Option

Optional

Information about one option.

Name

Optional

Option name, displayed in a small font under the item name.

Price

Optional

Price for the option. Use two-digit decimals or integers. Negative values are allowed.

Quantity

Optional

Integer or decimal value shown inline as x[value].

notifyCustomer

Optional

A Boolean tag that plays an audible tone or notification sound on the terminal each time the cart display is updated.

Possible values: true or false.

Use this to enhance customer awareness during scanning or cart updates.

HSA/FSA Card Acceptance

Health Savings Account (HSA) and Flexible Spending Account (FSA) cards are commonly used to pay for qualified medical, health, and wellness-related expenses. With this capability, healthcare providers (e.g., clinics, dental offices, pharmacies) can process payments for eligible services and products directly using HSA/FSA cards.

Follow the steps and references outlined in this section to accept and transmit HSA/FSA card data from the integrated Dejavoo payment terminal to the payment processor.

HTTPS://spinpos.net:443/spin/cgi.html?TerminalTransaction=

Request to Terminal
<request>
	<PaymentType>Credit</PaymentType>
	<TransType>Sale</TransType>
	<Amount>50.00</Amount>
	<Tip>0.00</Tip>
	<CashbackAmount>0.00</CashbackAmount>
	<CustomFee>0.00</CustomFee>
	<RefId>1</RefId>
	<RegisterId>1103024</RegisterId>
	<AuthKey>ulHLsaxfbg</AuthKey>
	<HSA_TotalAmount>30.00</HSA_TotalAmount>
	<HSA_RxAmount>10.00</HSA_RxAmount>
	<HSA_ClinicAmount>10.00</HSA_ClinicAmount>
	<HSA_DentalAmount>10.00</HSA_DentalAmount>
	<PrintReceipt>No</PrintReceipt>
	<SigCapture>No</SigCapture>
</request>

Get Customer Signatures

Merchants can use Dejavoo terminals to collect customer signatures for various purposes, including agreements, prescriptions, treatment plans, or even after completing transactions. These documents are sent directly from the POS system to the terminal for the customer's review and signature.

Follow the steps and references outlined in this section to configure the requests required by the cash register application to facilitate the collection of customer signatures.

Example:

HTTPS://test.spinpos.net:443/spin/cgi.html?TerminalTransaction=

Request to Terminal
<request>
	<RegisterId>3434801</RegisterId>
	<AuthKey>cTqG9fapET</AuthKey>
	<GetSign/>
</request>

Multi MID

Multi Merchant IDs (MMID) allows businesses operating under a single payment terminal to route transactions to different Merchant IDs (MIDs), each associated with a specific business entity, department, or service category. This is especially useful for environments like salons, medical offices, or multi-brand retail locations where different revenue streams must be tracked and settled separately.

In the iPOSpays environment, each MID is tied to a specific TPN (Terminal Provider Number). When MMID is enabled:

  • The TPN tag must contain the Master TPN, which represents the primary terminal setup.

  • The MerchantId tag must contain the transacting TPN, which determines the MID under which the transaction should be processed.

Sample MerchantId tag

<MerchantId>123456789143</MerchantId>

Error Sample

Respose Message
<xmp>
	<response>
		<Message>Error</Message>
		<ResultCode>2</ResultCode>
		<RespMSG>Terminal not connected to SPIn Proxy server</RespMSG>
	</response>
</xmp>

Type of Errors:

<ResultCode>2</ResultCode> — error from SPIn Proxy

<ResultCode>1</ResultCode> — error from Terminal

Error Codes and Their Meaning

For a complete list of error codes and their explanations, please visit our Error Codes Reference Page.

Error Codes & Messages
SPIn specificationREST API