Table of Contents

Revision History

Warning: Copyright and Proprietary Information

Introduction

Why SPIn?

Prerequisite

SPIn Proxy (Troubleshooting)

Server/Register/POS to Terminal Request Format

How to set custom operation timeout for transaction

Appendix B: SPIn Proxy Internal Errors

List of messages in

Write to us

devsupport@denovosystem.com

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)

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

NameData TypeM/ODescription
AuthKeyString(25)MSpecifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service 
PaymentTypeString(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.

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

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

TipFloat(10)O

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

Note: Tip must be enabled on terminal

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

RegisterIdVarChar(50)MAlpha numeric reference field.
TPNVarChar(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>

CashbackAmountFloat(10)OCashback amount of the transaction. ($$$$$$$.CC). Only valid on Debit or EBT payment types. Available on builds later than 5/17/19 and Aura
PrintReceiptVarChar(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
SigCaptureVarChar(3)OIf 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).
Tag1VarChar(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.
Tag2VarChar(8) Same as Tag1
Tag3VarChar(8) Same as Tag1
PerformedByVarChar(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

NameData TypeDescription
RefIdVarChar(50)Alpha numeric reference field. Echo back the original value from request. 
RegisterIdVarChar(50)Alpha numeric reference field.
TPNVarChar(12)TPN sent in the request is returned 
TransNumVarChar(50)Transaction number identified on terminal
InvNumVarChar(50)Unique alphanumeric invoice field.
ResultCodeVarChar(50)Transaction status: 0-Approved, 1-Declined/Failed due to reason returned by terminal 2- Failed due to reason returned by  SPIn Proxy
RespMSGVarChar(50)Alpha numeric field from SPIn Proxy or Terminal
MessageVarChar(50)Alpha numeric field from SPIn Proxy or Terminal.
AuthCodeVarChar(50)Alpha numeric field from Processor.
PNRefVarChar(50)Alpha numeric field from SPIn Proxy or Terminal.
PaymentTypeVarChar(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.
VoidedVarChar(50)True/False – Flag used to define if a transaction has been voided. Used more with Status transaction type
TransTypeString(20)Identifies the type of transaction performed
SNVarChar(50)Serial Number of the terminal that performed the transaction
ExtDataVarChar(512)

Additional transaction data. 

List and explanation of 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 digit 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 and CHIP Contactless, and CHIP/Swipe (Fallback occurred)
  15. GiftBalAmount: Balance amount available for the gift card used, if provided by the Host

Note: Check transaction does not have this field.

EMVDataVarChar(100)

Additional transaction data specific to EMV transactions required to be present on 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
SignBase64Base64 encoded signature image in b/w bitmap format
iPOSTokenVarChar(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

NameData TypeM/ODescription
RefIdVarChar(50)MAlpha numeric reference field. Echo back the original value from request. 
RegisterIdVarChar(50)MAlpha numeric reference field.
TPNVarChar(12)OAlpha numeric TPN field.
AuthKeyString(25)OSpecifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey. 
TransTypeString(20)MIdentifies the type of transaction to be run – Capture
AmountFloat(10)MBase dollar amount of the original transaction. ($$$$$$$.CC)
TipFloat(10)M

Dollar amount of tip to be added to the transaction. ($$$$$$$.CC)

Note: Tip must be enabled on terminal

RefIdVarChar(50)MAlpha numeric reference field. Must be the same as a Reference ID from original transaction. 

Response Fields Definitions

NameData TypeDescription
RefIdVarChar(50)Alpha numeric reference field. Echo from original request. 
RegisterIdVarChar(50)Alpha numeric reference field. Echo from original request. 
TPNVarChar(12)Alpha numeric TPN field.
ResultCodeVarChar(50)Transaction status: 0-succeeded, 1-failed.
MessageVarChar(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) 

PaymentTypeVarChar(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>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, 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

NameData TypeM/ODescription
RegisterIdVarChar(50)MAlpha numeric reference field.
TPNVarChar(12)OAlpha numeric TPN field.
AuthKeyString(25)OSpecifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey. 
TransTypeString(20)MIdentifies the type of transaction to be run – TipAdjust
AmountFloat(10)MBase dollar amount of the original transaction. ($$$$$$$.CC)
TipFloat(10)M

Dollar amount of tip to be added to the transaction. ($$$$$$$.CC)

Note: Tip must be enabled on terminal

RefIdVarChar(50)MAlpha numeric reference field. Must be the same as a Reference ID from original transaction. 

Response Fields Definitions

NameData TypeDescription
RefIdVarChar(50)Alpha numeric reference field. Echo from original request. 
RegisterIdVarChar(50)Alpha numeric reference field.
TPNVarChar(!2)Alpha numeric TPN field.
ResultCodeVarChar(50)Transaction status: 0-succeeded, 1-failed.
MessageVarChar(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) 

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

NameData TypeM/ODescription
RegisterIdVarChar(50)MAlpha numeric reference field.
TPNVarChar(12)OAlpha numeric TPN field
PaymentTypeString(20)MIdentifies EDC type: Credit, Debit, Check, Gift, Loyalty
AuthKeyString(25)OSpecifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service 
TransTypeString(20)MIdentifies the type of transaction to be run – Void
AmountFloat(10)MBase dollar amount of the original transaction. ($$$$$$$.CC)
RefIdVarChar(50)MAlpha numeric reference field. Must be the same as a Reference ID from original transaction. 
 

Response Fields Definitions

NameData TypeDescription
RefIdVarChar(50)Alpha numeric reference field. Echo from original request. 
RegisterIdVarChar(50)Alpha numeric reference field.
TPNVarChar(12)Alpha Numeric TPN field. 
ResultCodeVarChar(50)Transaction status: 0-succeeded, 1-failed.
MessageVarChar(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) 

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

NameData Type     M/ODescription
RegisterIdVarChar(50)   MAlpha numeric reference field.
TPNVarChar(12)   OApha numeric TPN field
PaymentTypeString(20)   MIdentifies EDC type: Credit, Debit, Check, Gift, Loyalty
AuthKeyString(25)   OSpecifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service 
TransTypeString(20)   MIdentifies the type of transaction to be run – Status
RefIdVarChar(50)  MAlpha numeric reference field. Must be the same as a Reference ID from the original transaction. 
PrintReceiptVarChar(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

NameData TypeDescription
RefIdVarChar(50)Alpha numeric reference field. Echo from original request. 
RegisterIdVarChar(50)Alpha numeric reference field.
TPNVarChar(12)Alpha numeric TPN field. 
ResultCodeVarChar(50)Transaction status: 0-succeeded, 1-failed.
MessageVarChar(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) 

PaymentTypeVarChar(50)Alphabetical string indicating a payment type used for processing original transaction. Populated if a transaction was found in the DB. 
RespMSGVarChar(50)Alpha numeric field from gateway. Populated if transaction was found in the DB.
AuthCodeVarChar(50)Alpha numeric field from gateway. Populated if transaction was found in the DB.
PNRefVarChar(50)Alpha numeric field from gateway. Populated if transaction was found in the DB.
EMVDataVarChar(100)

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

  1. AID: Application ID from ICC
  2. AppName: Application Name from ICC
  3. TVR: Terminal verification results
  4. TSI: Transaction status information

Populated if transaction was found in the DB.

SignBase64

Base64 encoded signature image in b/w bitmap format.

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

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

NameData TypeM/ODescription
RegisterIdVarChar(50)MAlpha numeric reference field.
TPNVarChar(12)OApha numeric TPN field.
AuthKeyString(25)MSpecifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service 
RefIdVarChar(50)MAlpha numeric reference field. 
TransTypeString(20)MIdentifies the type of transaction to be run – Settle
MerchantIdNumericOMerchant number (1-N). If not specified in multi-merchant mode, all merchants will be settled.
ParamString(20)M

Type of Settlement request:

  • Close: normal closing
  • Force: Force batch totals
 

Response Fields Definitions

NameData TypeDescription
RefIdVarChar(50)Alpha numeric reference field. Echo from original request. 
RegisterIdVarChar(50)Alpha numeric reference field.
TPNVarChar(12)Alpha numeric TPN field.
ResultCodeVarChar(50)Overall status of all application’s ResultCode in ExtData: 0-succeeded, 1-failed.
MessageVarChar(50)

Alpha numeric field providing detailed result message for each result code:

0–Success 

1- Failure

AuthCodeVarChar(50)Alpha numeric field from gateway.
ExtDataVarChar(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

NameData Type     M/ODescription
AuthKeyString(25)  MSpecifies the Auth-Key, which authorizes Host system to use the SPIn™ Web Service 
RegisterIdVarChar(50)  MAlpha numeric reference field.
TPNVarChar(12)  OAlpha numeric TPN field.
RefIdVarChar(50)  OAlpha numeric reference field. 
printerN/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
tVarChar(40)  MText to print
bN/A  OIndicates that text should be printed in bold 
cN/A  OIndicates that text should be printed centered 
lfN/A  OIndicates that printer should feed a line after current string
invN/A  OIndicates that the following text should be printed inverted. Whole line till <lf> will be inverted.
 

Response Fields Definitions

NameData TypeDescription
RefIdVarChar(50)Alpha numeric reference field. Echo from original request. 
RegisterIdVarChar(50)Alpha numeric reference field.
TPNVarChar(12)Apha numeric TPN Field
MessageVarChar(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

NameData Type       M/ODescription
RegisterIdVarChar(50)  MAlpha numeric reference field.
TPNVarChar(12)  OApha numeric TPN field.
AuthKeyString(25)  OSpecifies 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

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

Response Fields Definitions

NameData TypeDescription
RegisterIdVarChar(50)Alpha numeric reference field.
TPNVarChar(12)Alpha numeric TPN field
UserChoice   StringResponse to Request for a user choice
MessageVarChar(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 TypeM/O

Description

RegisterIdVarChar(50)MAlpha numeric reference field.
AuthKeyString(25)OSpecifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey. 
UserInputInputM

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

RegisterIdVarChar(50)Alpha numeric reference field.
UserInputStringResponse value to request for a user input.
MessageVarChar(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 TypeM/O

Description

Register IDVarChar(50)MAlpha numeric reference field.
AuthKeyString(25)OSpecifies the Auth-Key, which authorizes the Host system to use the SPIn™ Web Service; required if Terminal is configured to use AuthKey. 
ReportTypeString(25)MIt refers to the type of the report either “Summary” or “Daily”.
TransTypeString(10)MTransType must be set to “Report” for this open batch daily or summary report request

Response Fields Definitions

Name

Data Type

Description

RegisterIdVarChar(50)Alpha numeric reference field.
ResultCodeStringIt responded with a Result Code
MessageVarChar(50)

Alpha numeric field providing detailed result message for each result code:

Success / Failure / Cancel

TransReportText

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

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

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

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

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

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

ISVID Indicator

ISV ID will create a new minor channel.

EX:

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

Request: –

<request>

<RegisterId>1103024</RegisterId>

<AuthKey>ulHLsaxfbg</AuthKey>

<PaymentType>Credit</PaymentType>

<TransType>AddLevel3Item</TransType>

<Amount>10.00</Amount>

<RefId>60</RefId>

<AuthCode>TAS852</AuthCode>

<IsvId>100001</IsvId>

</request>

Response: –

<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.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>DescriptionWhat to do
Active route not foundA 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 requestThere is an error in the request message format.Check a request format.
Route not foundA 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 queryA terminal operates another request.Wait when the previous request is completed and repeat a new request to a terminal.
Terminal in useRegister/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 IDReference 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
ReconnectedTerminal was reconnected after receiving the request and before providing the responseDo Status request to check transaction Status