spin specification

Revision History

Date	Version	Details
10/1/2022	1.0	Initial release
10/10/22	1.1	Added support for Tags
11/1/22	1.2	Added support for iPOSToken
20/2/23	1.3	Added PerformedBy Tag
5/4/2023	1.4	Added userChoice option to PaymentType
21/7/23	1.5	Added support for User input Summary report to fetch batch details from payment device
30/1/24	1.6
06/2/2024	1.7	Added support for Level data Dual pricing request ISVID indicator

SPIn API’s

SPIn interface (Semi-integration) integration can be done either using REST API or SOAP API.

Note: To integrate using REST API, please refer to the following documentation link https://app.theneo.io/dejavoo/spin/spin-rest-api-methods

To Integrate using SOAP API (XML request & response) refer to this document.

Warning: Copyright and Proprietary Information

Information in this document is subject to change without prior notice.

No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, optical, magnetic, chemical, manual, or otherwise, without the prior written permission of i-POS Systems LLC.

All trademarks mentioned are proprietary to their respective owners.

Introduction

iPOS System’s SPin™ Interface is a semi-integration solution that facilitates fast and simple integration with 3rd party point-of-sale systems such as Integrated POS, Restaurant Management Systems, Kiosks, Cash Registers, Till, etc.

Why SPIn?

SPIn creates a cloud-based connection that allows the Merchant’s system (Host System), a.k.a cash registers, billing software, POS, or Till, to generate the amount due and send to the payment device and the device after finishing the transaction transfers the payment data back to the Host System. This makes reconciliation easier and prevents human errors.

No sensitive cardholder information such as PAN, expiration date, etc is passed to the Host System in the process thus removing the PCI compliance burden for the merchants.

Prerequisite

SO or Merchant login into iPOSPays portal

Dejavoo Android Payment Device

TPN (Device profile) with SPIn enabled
- Get TPN (Our sales team can help you with this step)
- Enable SPIn
- Download Parameter in Payment Device

Setting up a Payment Device for Semi-Integration

Get ISO or Merchant Login

Login: (UAT/Sandbox URL)

Go to https://.ipospays.tech/
Type your username & password to login.

Get TPN:

If you don’t have a TPN then reach us through sales@dejavoosystems.com to get a TPN. While sending the request kindly mention that you want to enable SPIn for the TPN.

Enable SPIn:

You can enable SPIn or cross check if it is enabled for your existing TPN or new TPN.

Image 1.2

Step 1: Click “S.T.E.A.M 🡪 Edit Parameters” (Refer: Image 1.2, hand 1 & 2)

Step 2: Search and select the TPN and click “Edit Parameters” (Refer: Image 1.2, hand 3 & 4)

Image 1.3

Step 3: Click the “Integration” tab and select SPIn 🡪 Cloud (Refer: Image 1.3)

Copy the Register Id and Auth Key, you will need the values while calling the API from the Host System.

Download Parameter:

Once SPIn is enabled, then download parameters on the device to reflect the changes into the device.

Image 1.4

After downloading the parameters, your device will look like the below image.

SPIn Proxy (Troubleshooting)

To make sure the connection is established between SPIn and the device, we offer SPIn Proxy for troubleshooting.

Step 1: Click “Troubleshooting 🡪 SPIn Proxy” (Refer: Image 1.6, hand 1 & 2)

Step 2: Enter your TPN (Refer: Image 1.6, hand 3)

Step 3: Click “Check POS Connection” (Refer: Image 1.6, hand 4)

If the arrow between the SPIn logo and Payment Device logo is lit up in green, then the connection is established successfully. If the arrow is lit up in red, then the connection is not established and there is some issue.

Then, reach us through support@dejavoosystems.com

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

TPN check

Click “Check Register Connection” (Refer: Image 1.6, hand 5) and select “Show TPN”, the connected device will receive a pop up like the below image.

Image 1.7

Once you confirm from the device, If the arrow lights up in green and the TPN appears on the portal then the connection is established successfully (Refer: Image1.8).

Image 1.8

If the arrow is lit up in red, then the connection is not established and there is some issue. (Refer: Image 1.9). Then, reach us through support@dejavoosystems.com.

Image 1.9

Auth Key Check

Click “Check Register Connection” (Refer: Image 1.6, hand 5) and select “Show Auth Key”, the connected device will receive a pop up.

Once you confirm from the device, If the arrow lights up in green and the Auth Key appears on the portal then the connection is established successfully.

If the arrow is lit up in red, then the connection is not established and there is some issue. Then, reach us through support@dejavoosystems.com

Server/Register/POS to Terminal Request Format

Transaction Request

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

Sandbox URL : HTTPS://test.SPInpos.net:443/SPIn/cgi.html?

Production URL : HTTPS://SPInpos.net:443/SPIn/cgi.html?

Note 1: 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 status check API to check the status.

Note 2: If the Server/Register/POS sends another request before the timeout, SPIn proxy will send “Terminal in use” error. If the Terminal is not ready to receive transaction due to whatever reasons ( usually the terminal is not in the idle screen to receive the request or it is busy processing other operation, or still not completed previous transaction ), it will return “Service busy” error

Request Fields Definition

Name	Data Type	M/O	Description
AuthKey	String(25)	M	Specifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service
PaymentType	String(20)	M	Identifies EDC type: Credit, Debit, EBT, userChoice, Gift Note: If userChoice value is set to PaymentType upon request, then it will enable customers (end-users) to opt Credit/Debit/EBT while they are doing payment. And in response PaymentType will have the value of what the customer opted for during payment.
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: Credit: Sale, Return, Void, Auth, Capture, CashAdvance* Debit: Sale, Return EBT_Food – Sale, Return EBT_Cash – Sale, Return 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 tip is added, 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
RefId	VarChar(50)	M	Alpha numeric reference field. Must be unique for the open batch scope. Set by the host system and, Mandatory for all deployments. Used for Tip or other transaction adjustment requests related to a given transaction, for example, Tip Adjustment or Void Transaction request must have a RefId value of an original transaction. For Table payment type RefId is not required to be unique within a batch.
RegisterId	VarChar(50)	M	Alpha numeric reference field.
TPN	VarChar(12)	O	Alphanumeric. TPN is possible to use instead of RegisterId only for Dejavoo SPIn Proxy connection. The pair <RegisterId>21123001</RegisterId> <AuthKey>12345678</AuthKey> has to work in 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: No – transaction receipt won’t be printed on terminal Merchant – print Merchant copy only Customer – print Customer copy only Both – (default) print both Merchant and Customer copies
SigCapture	VarChar(3)	O	If *SigCapture* is set to “No” in request, it will suppress a signature capture event during the transaction. If this element is not present, or if set to “Yes” then Terminal will capture the signature (if Terminal is capable of it).
Tag1	VarChar(8)		iPOSPays supports upto 3 tags. Enable tagging on the gateway STEAM module. Label for this Tag is to be configured in STEAM. After processing Tag value will be printed on merchant copy. on iPOSPays portal transaction can be filtered using this tag value. Settlement report will include this tage value.
Tag2	VarChar(8)		Same as Tag1
Tag3	VarChar(8)		Same as Tag1
PerformedBy	VarChar(100)		This tag will identify the user who performed the transaction. In-case of Cloudpos+Pinpad transaction, this tag will identify the merchant user (i.e. email-id of merchant) who initiated the transaction. Terminal will upload this information to the portal as part of Signature upload and this information will be visible on the portal and available on transaction report to download.

Response Fields Definitions

Name	Data Type	Description
RefId	VarChar(50)	Alpha numeric reference field. Echo back the original value from request.
RegisterId	VarChar(50)	Alpha numeric 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)	Alpha numeric field from SPIn Proxy or Terminal
Message	VarChar(50)	Alpha numeric field from SPIn Proxy or Terminal.
AuthCode	VarChar(50)	Alpha numeric field from Processor.
PNRef	VarChar(50)	Alpha numeric field from SPIn Proxy or Terminal.
PaymentType	VarChar(50)	Alphabetical string indicating a payment type used for processing transactions. Payment Type can be switched based on rules embedded into a payment application, for example, Credit Visa card can be processed as Debit either based on automatic BIN table look up or based on user selection at Credit/Debit prompt.
Voided	VarChar(50)	True/False – Flag used to define if a transaction has been voided. Used more with Status transaction type
TransType	String(20)	Identifies the type of transaction performed
SN	VarChar(50)	Serial Number of the terminal that performed the transaction
ExtData	VarChar(512)	Additional transaction data. List and explanation of data InvNum: invoice number CardType: VISA, MASTERCARD, AMEX, DISCOVER, DINERSCLUB, JCB, ENROUTE, DEBIT, EBT BatchNum: batch number Tip: tip amount CashBack: cashback amount Fee: merchant fee AcntLast: last 4 digit of account number Name: cardholder name (if card swipe) TotalAmt: total amount DISC: discount amount SHFee: Service and Handling Fee, if enabled EBTFSAvailBalance: EBT Food Stamp Balance, if provided by Host EBTCashAvailBalance: EBT Cash Balance, if provided by Host EntryType: Entry method used to provide account data. Supported Entry Types – Swipe, Manual, CHIP, Contactless and CHIP Contactless, and CHIP/Swipe (Fallback occurred) GiftBalAmount: Balance amount available for the gift card used, if provided by the Host Note: Check transaction does not have this field.
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 IAD: Issuer Application Data ARC: Authorization Response Code
Sign	Base64	Base64 encoded signature image in b/w bitmap format
iPOSToken	VarChar(100)	Tokenized Card number + Expiry date. This is iPOSPays token – Not processor token. Hence, this token can be used only while transacting thru iPOSPays gateway. Please refer to the iposTransact API document on how to use this token to perform a transaction on the card on file.

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>

<RefId>2</RefId>

<RegisterId>3</RegisterId>

<AuthKey>234123-74653252-663525223</AuthKey>

<TPN>123456789123</TPN>

<PrintReceipt>Both</PrintReceipt>

<PerformedBy>sample@email-account-id</PerformedBy>


     </request>

Approval 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=,EBTCashA
vailBalance=,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:

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>

Capture Request

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

Request Fields Definitions

Name	Data Type	M/O	Description
RefId	VarChar(50)	M	Alpha numeric reference field. Echo back the original value from request.
RegisterId	VarChar(50)	M	Alpha numeric reference field.
TPN	VarChar(12)	O	Alpha numeric 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	Base dollar amount of the original transaction. ($$$$$$$.CC)
Tip	Float(10)	M	Dollar amount of tip to be added to the transaction. ($$$$$$$.CC) Note: Tip must be enabled on terminal
RefId	VarChar(50)	M	Alpha numeric reference field. Must be the same as a Reference ID from original transaction.

Response Fields Definitions

Name	Data Type	Description
RefId	VarChar(50)	Alpha numeric reference field. Echo from original request.
RegisterId	VarChar(50)	Alpha numeric reference field. Echo from original request.
TPN	VarChar(12)	Alpha numeric TPN field.
ResultCode	VarChar(50)	Transaction status: 0-succeeded, 1-failed.
Message	VarChar(50)	Alpha numeric 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)	Alphabetical string indicating a payment type used for processing transactions. Payment Type can be switched based on rules embedded into a payment application, for example, Credit Visa card can be processed as Debit either based on automatic BIN table look up or based on user selection at Credit/Debit prompt.

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 Transaction is valid only in a Restaurant environment. Host system must use data from the original transaction in order for the Terminal to locate the transaction and modify the Tip amount.

Request Fields Definitions

Name	Data Type	M/O	Description
RegisterId	VarChar(50)	M	Alpha numeric reference field.
TPN	VarChar(12)	O	Alpha numeric 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)	M	Dollar amount of tip to be added to the transaction. ($$$$$$$.CC) Note: Tip must be enabled on terminal
RefId	VarChar(50)	M	Alpha numeric reference field. Must be the same as a Reference ID from original transaction.

Response Fields Definitions

Name	Data Type	Description
RefId	VarChar(50)	Alpha numeric reference field. Echo from original request.
RegisterId	VarChar(50)	Alpha numeric reference field.
TPN	VarChar(!2)	Alpha numeric TPN field.
ResultCode	VarChar(50)	Transaction status: 0-succeeded, 1-failed.
Message	VarChar(50)	Alpha numeric 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)	Alphabetical string indicating a payment type used for processing transaction. Payment Type can be switched based on rules embedded into a payment application, for example, Credit Visa card can be processed as Debit either based on automatic BIN table look up or based on user selection at Credit/Debit prompt.

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

Void Transaction is used to cancel a previously authorized transaction until the batch is closed. Host system must use data from the original transaction in order for the Terminal to locate the transaction and process Void request.

Request Fields Definitions

Name	Data Type	M/O	Description
RegisterId	VarChar(50)	M	Alpha numeric reference field.
TPN	VarChar(12)	O	Alpha numeric 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	Alpha numeric reference field. Must be the same as a Reference ID from original transaction.

Response Fields Definitions

Name	Data Type	Description
RefId	VarChar(50)	Alpha numeric reference field. Echo from original request.
RegisterId	VarChar(50)	Alpha numeric reference field.
TPN	VarChar(12)	Alpha Numeric TPN field.
ResultCode	VarChar(50)	Transaction status: 0-succeeded, 1-failed.
Message	VarChar(50)	Alpha numeric 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 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

Transaction status request is used by the Host System to check the result of any previously requested transaction, typically, in event when communication between Host System and Terminal was interrupted while transaction request was pending.

Request Fields Definitions

Name	Data Type	M/O	Description
RegisterId	VarChar(50)	M	Alpha numeric reference field.
TPN	VarChar(12)	O	Apha numeric 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	Alpha numeric reference field. Must be the same as a Reference ID from the original transaction.
PrintReceipt	VarChar(50)	O	An optional tag. Possible values: No – (default) transaction receipt won’t be printed on terminal Merchant – print Merchant copy only Customer – print Customer copy only Both – print both Merchant and Customer copies

Response Fields Definitions

Name	Data Type	Description
RefId	VarChar(50)	Alpha numeric reference field. Echo from original request.
RegisterId	VarChar(50)	Alpha numeric reference field.
TPN	VarChar(12)	Alpha numeric TPN field.
ResultCode	VarChar(50)	Transaction status: 0-succeeded, 1-failed.
Message	VarChar(50)	Alpha numeric field providing detailed result message for each result code: 0 – Approved (transaction was successful) 1 – Not Found (transaction not found) 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 original transaction. Populated if a transaction was found in the DB.
RespMSG	VarChar(50)	Alpha numeric field from gateway. Populated if transaction was found in the DB.
AuthCode	VarChar(50)	Alpha numeric field from gateway. Populated if transaction was found in the DB.
PNRef	VarChar(50)	Alpha numeric 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 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>

Transaction Status Response from terminal to server:

<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

Request for settlement is used to initiate the terminal batch settlement with the payment processor.

Request Fields Definitions

Name	Data Type	M/O	Description
RegisterId	VarChar(50)	M	Alpha numeric reference field.
TPN	VarChar(12)	O	Apha numeric TPN field.
AuthKey	String(25)	M	Specifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service
RefId	VarChar(50)	M	Alpha numeric 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: Close: normal closing Force: Force batch totals

Response Fields Definitions

Name	Data Type	Description
RefId	VarChar(50)	Alpha numeric reference field. Echo from original request.
RegisterId	VarChar(50)	Alpha numeric reference field.
TPN	VarChar(12)	Alpha numeric TPN field.
ResultCode	VarChar(50)	Overall status of all application’s ResultCode in ExtData: 0-succeeded, 1-failed.
Message	VarChar(50)	Alpha numeric field providing detailed result message for each result code: 0–Success 1- Failure
AuthCode	VarChar(50)	Alpha numeric 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 a selected terminal model is equipped with the integrated printer, the Terminal printer can be utilized as an external printer for the Integrated POS System’s printing functionality.

Terminal is capable in printing text in «Courier New» font

Default printer width is 24 characters per line.

Request Fields Definitions

Name	Data Type	M/O	Description
AuthKey	String(25)	M	Specifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service
RegisterId	VarChar(50)	M	Alpha numeric reference field.
TPN	VarChar(12)	O	Alpha numeric TPN field.
RefId	VarChar(50)	O	Alpha numeric reference field.
printer	N/A	M	Indicates a block of text for printing 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
lf	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

Name	Data Type	Description
RefId	VarChar(50)	Alpha numeric reference field. Echo from original request.
RegisterId	VarChar(50)	Alpha numeric reference field.
TPN	VarChar(12)	Apha numeric TPN Field
Message	VarChar(50)	Alpha numeric field providing detailed result message for each result code: Success – Printout was successful No Paper – Paper needs to be replaced Error – Other Error

Example

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>Qk2uCAAAAAAAAD4AAAAoAAAACwEAADw
AAAABAAEAAAAAAHAIAADEDgAAxA4AAAAAAAAAAAAAAAAAAP</img>

</printer>

</request>

Response from Terminal:

<xmp>

<response>

<RefId>2</RefId> 

<RegisterId>3</RegisterId> 

<TPN>123456789123</TPN>

<Message>Success</Message> 

</response>

</xmp>

Notes

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

Use this API to prompt for card holder choice that will be prompted on the payment device. The option selected by the card holder will be passed back to the register. For example, a register can start a transaction asking the user if they have a debit card. If yes, the register can enable a debit transaction.

Request Fields Definitions

Name	Data Type	M/O	Description
RegisterId	VarChar(50)	M	Alpha numeric reference field.
TPN	VarChar(12)	O	Apha numeric 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

Name	Data Type	Description
RegisterId	VarChar(50)	Alpha numeric reference field.
TPN	VarChar(12)	Alpha numeric TPN field
UserChoice	String	Response to Request for a user choice
Message	VarChar(50)	Alpha numeric field providing detailed result message for each result code: Success Failure Cancel

Response from 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 Case:

In a restaurant setting, the POS application can send a prompt like asking for the order number, directly to the waiter’s payment device. The waiter responds with the order number back to the POS application. Based on the response, the payment amount will be triggered for that specific order. This will reduce the roundtrip for the waiter from the cash counter to the table.

Request Fields Definitions

Name	Data Type	M/O	Description
RegisterId	VarChar(50)	M	Alpha numeric 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

Name	Data Type	Description
RegisterId	VarChar(50)	Alpha numeric reference field.
UserInput	String	Response value to request for a user input.
Message	VarChar(50)	Alpha numeric field providing detailed result message for each result code: Success Failure Cancel

Example

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

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>

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>

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>

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>

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

By using broadcast batch report service, the customer can retrieve the status and details of the current open batch. The customer can use the ReportType request field to indicate what type of report they want to get. The Summary report provides brief batch information, including totals for every transaction type. The Daily report provides a detailed description of every transaction conducted.

Request Fields Definitions

Name	Data Type	M/O	Description
Register ID	VarChar(50)	M	Alpha numeric 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

Name	Data Type	Description
RegisterId	VarChar(50)	Alpha numeric reference field.
ResultCode	String	It responded with a Result Code
Message	VarChar(50)	Alpha numeric 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

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

Summary Report

Request: -

<request>

  <RegisterId>9724703</RegisterId>

  <AuthKey>giVVxrGs5bn</AuthKey>

  <ReportType>Summary</ReportType>

  <TransType>Report</TransType>

</request>

Success Response: -

<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

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

Level 2 or Level 3 (L2/L3) data provides commercial shoppers with additional information about purchases on their card statements. It allows companies to track how much is spent on their corporate cards where a single card may have multiple users.

Companies can also track the amount of sales tax to pay or reconcile transactions using a unique customer code. Transactions submitted with L2/L3 data that meet requirements have lower interchange rates.

Example

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

Request: –

<AuthKey>ulHLsaxfbg</AuthKey>

<PaymentType>Credit</PaymentType>

<LocalTaxFlag>TaxProvided</LocalTaxFlag>

<group>

</group>

</Level3LineItems>

</request>

Response: –

<xmp>

<Message>APPROVED</Message>

<RespMSG>APPROVED</RespMSG>

<Voided>false</Voided>

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

Name	Data Type	Description
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

Dual pricing request

Merchants can create inventory and select the items and complete the transactions in different modes.

Example

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

Request: –

<AuthKey>ulHLsaxfbg</AuthKey>

<PaymentType>Credit</PaymentType>

<Tax1Label>LocalTax</Tax1Label>

<Tax2Label>StateTax</Tax2Label>

<group>

</group>

</LineItems>

</request>

Response: –

<xmp>

<Message>APPROVED</Message>

<RespMSG>APPROVED</RespMSG>

<Voided>false</Voided>

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

ISVID Indicator

ISV ID will create a new minor channel.

EX:

100001 – CP-PINPAD which indicates cloud pos pinpad transaction.

Request: –

<AuthKey>ulHLsaxfbg</AuthKey>

<PaymentType>Credit</PaymentType>

<TransType>AddLevel3Item</TransType>

</request>

Response: –

<xmp>

<Message>APPROVED</Message>

<RespMSG>APPROVED</RespMSG>

<Voided>false</Voided>

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

How to set custom operation timeout for transaction

As mentioned before, default timeout after which SPIn Proxy will send “operations timed out” error is 120 seconds. Sometimes the register/POS/Server may need a longer operation time out. In case of curbside check-out where the merchant has to take the device to the customer’s car register/pos/server may have to wait longer.

Use the OperationalTimeout tag for setting custom timeouts.

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

Appendix B: SPIn Proxy Internal Errors

SPIn Proxy types of error messages and standard solutions.

internal Proxy error it is an error when Proxy returns message like:

<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

List of Messages in for 2:

<RespMSG>…</RestMSG>	Description	What to do
Active route not found	A terminal does not have an active SPIn Connection. The Connection is created, but is disabled.	On the Terminal Details page check that SPIn Proxy is activated for this terminal.
Not pars request	There is an error in the request message format.	Check a request format.
Route not found	A terminal does not have SPIn Connection. The Connection is not created.	On the Terminal Details page create a new SPIn Proxy connection.
Terminal not connected to SPIn proxy server	A terminal is not connected to the internet or it is inaccessible due to network settings. The terminal might be just disconnected due to reconnecting to the network, a terminal restart, being in sleep mode, or being in SPIn bypass mode.	Check a terminal whether it works or not and be sure that terminal is on the SPIn mode screen and online. Send a status request to get actual connection status to continue to work with a terminal. see Check Terminal Connection Status
The operation has timed out	A request was sent to a terminal, but the terminal did not provide a response at a proper time. Probably the terminal lost a connection, was switched off, a discharged battery, some bug on a terminal, a terminal not in the IDLE screen and busy by some process e.g. a terminal menu is open and a transaction not in focus. Possible that the terminal will respond to this transaction after a timeout event, a transaction will be performed and approved on a host side and added to a settlement report. But SPIn Proxy cannot guarantee a delivery on this POS request and a timeout is the best response in this case. Default timeout 120 seconds.	Check a terminal whether it works or not and be sure that terminal is on the SPIn mode screen and online. Do Status request to check transaction Status Alternative way: Repeat the transaction with the same parameters if the transaction was already performed you will get an error “Duplicated ReferenceID”. Continue to perform transactions
This terminal handles a different query	A terminal operates another request.	Wait when the previous request is completed and repeat a new request to a terminal.
Terminal in use	Register/Server/Host will get this error if it attempts to send a second request before the full time out period of previous request.	Wait for transaction timing out before attempting another transaction
Invalid Reference ID	Reference Id value sent from Register/POS/Server will have to be unique per transaction within the batch.	Change the reference id value and retry the transaction
Reconnected	Terminal was reconnected after receiving the request and before providing the response	Do Status request to check transaction Status

Table of Contents

Write to us

Revision History

SPIn API’s

Warning: Copyright and Proprietary Information

Introduction

Why SPIn?

Prerequisite

Setting up a Payment Device for Semi-Integration

Get TPN:

Enable SPIn:

Download Parameter:

SPIn Proxy (Troubleshooting)

TPN check

Auth Key Check

Server/Register/POS to Terminal Request Format

Transaction Request

Capture Request

Request to Terminal:

Response from Terminal:

Tip Adjustment Request

Request to Terminal:

Response from Terminal:

Void Transaction Request

Request to Terminal:

Transaction Status Request

Request to Terminal

Transaction Status Response from terminal to server:

Request for Settlement

Request to Terminal

Response from Terminal:

Printout Request

Example

Response from Terminal:

User Choice Request

Response from Terminal:

Response from Terminal:

User Input Request

Batch Report Request

Level data

Dual pricing request

ISVID Indicator

How to set custom operation timeout for transaction

Appendix B: SPIn Proxy Internal Errors

List of Messages in for 2: