SPIn specification
API Docs

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

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.

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>
	<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>
	<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.

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>
	<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.

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>
	<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.

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

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

MerchantId * Numeric O

Merchant number (1-N). If not specified in multi-merchant mode, all merchants will be settled.

Param * String(20) M

Type of Settlement request:

1. Close: normal closing

2. Force: Force batch totals

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

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

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

This option allows you to display cart items on the terminal. The response will be the same as the payment response.

Use Case:

Merchants can send the item list from their POS application to the consumer facing Dejavoo payment terminal. This will allow the consumer to confirm their purchased items and make the payment.

How it Works

“ITEMS” screen.

  • When the merchant initiates the request from the cash register, the request will include the cart items with their card and cash prices or just the card price. The display of both prices depends on the register's configuration, and the request will be sent to the payment terminal and displayed on the ITEMS screen accordingly.

  • Once the request is initiated, the payment terminal will display each cart item with its respective amount on the ITEMS screen. The item list can be scrolled, allowing the customer to review and confirm the items before proceeding with payment.

  • Both the card and cash prices of the transaction will be displayed so the customer can easily compare the difference between paying with a card and cash.

Follow the steps and references outlined in this section to display cart items on the payment terminal.

TagsDetailsComment
Item *

Mandatory

Information about a single item.

Name *

Mandatory

Item name. The terminal displays this in regular font.

Items *

Mandatory

Section that shows items

Amounts *

Mandatory

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

PosID

Optional

This is a recommended field to track which register sent the request if multiple registers use the same terminal.

Cart

Optional

Tag that contains all the cart item details

Amount

Optional

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

Name

Optional

Text for the line with the amount.

Value

Optional

Recommended to 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.

Price

Optional

Item price. Recommended to use decimals with two digits after the decimal point 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. Recommended to use decimals with two digits after the decimal point or integer values. Negative values are possible.

Quantity

Optional

Integer or decimal will be shows in line with option as x[you value]

Sample request for cart items to be displayed in the payment flow

This option allows you to display cart items in the terminal. Response will be the same as payment response.

Request to Terminal
<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>
  <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>

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>

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 specificationFreedom to Design