SPIn specification
API Docs

SPIn specification API

Version History

DateVersionDetails
10/01/22 1.0

Initial release

10/10/22 1.1

Added support for Tags

11/01/22 1.2

Added support for iPOSToken

20/02/23 1.3

Added PerformedBy Tag

5/04/23 1.4

Added userChoice option to PaymentType

21/07/23 1.5

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

30/01/24 1.6

06/02/24 1.7

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

10/09/24 1.8

Enabled cart Items display API

Prerequisite

  • SO or Merchant login into iPOSPays portal
  • Dejavoo Android Payment Device
  • TPN (Device profile) with SPIn enabled
    1. Get TPN (Our sales team can help you with this step)
    2. Enable SPIn
    3. 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.

SPIN2.png

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

SPIN3.png

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

SPIN4.png

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

SPIN5.png

SPIn Proxy (Troubleshooting)

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

SPIN6.png

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

SPIN7.png

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

SPIN8.png

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.

SPIN9.png

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.

SPIN10.png

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? (opens in a new tab)

Production URL : https://spinpos.net:443/SPIn/cgi.html? (opens in a new tab)

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

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

2. Debit: Sale, Return

3. EBT_Food – Sale, Return

4. EBT_Cash – Sale, Return

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

Note: Cash Advance is only available for certain processors

Amount * Float(10) M/O

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

Note: This is the total amount. If 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:

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

2.Merchant – print Merchant copy only

3. Customer – print Customer copy only

Both – (default) print both Merchant and Customer copies

SigCapture * VarChar(3) O

If SigCapture is set to “No” in 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) M

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

Same as Tag1

Tag3 * VarChar(8) M

Same as Tag1

PerformedBy * VarChar(100) M

This tag will identify the user who performed the transaction. In-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
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

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

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 Definition

NameData TypeM/ODescription
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

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

Tip * Float(10) O

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

Note: Tip must be enabled on terminal

RefId * VarChar(50) M

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

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alpha numeric reference field. Echo back the original value from 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 Definition

NameData TypeM/ODescription
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) O

Dollar amount of 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

NameData TypeDescription
RefId * VarChar(50)

Alpha numeric reference field. Echo back the original value from 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)

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

NameData TypeM/ODescription
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

NameData TypeDescription
RefId * VarChar(50)

Alpha numeric reference field. Echo back the original value from 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)

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

PaymentType * VarChar(50)

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

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

Transaction Status Request

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 Definition

NameData TypeM/ODescription
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 – Status

RefId * VarChar(50) M

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

PrintReceipt * VarChar(50) O

An optional tag. Possible values:

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

2. Merchant – print Merchant copy only

3. Customer – print Customer copy only

4. Both – print both Merchant and Customer copies

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alpha numeric reference field. Echo back the original value from 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)

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

PaymentType * VarChar(50)

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

RespMSG * VarChar(50)

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>
  • Response from Terminal:
 
<xmp>
 
<response>
 
<RefId>3</RefId>
 
<RegisterId>3</RegisterId>
 
<TPN>123456789123</TPN>
 
<InvNum>1</InvNum>
 
<ResultCode>0</ResultCode>
 
<RespMSG>Approved</RespMSG>
 
<Message>Approved</Message>
 
<AuthCode>292249</AuthCode>
 
<PNRef>1807027</PNRef>
 
<PaymentType>Credit</PaymentType>
 
<ExtData>InvNum=1,CardType=VISA,BatchNum=1,Tip=0.00, CashBack=0.00,Fee=0.00,AcntLast4=1234,Name=Dejavoo, TotalAmt=1.00,DISC=0.00,EBTFSAvailBalance=0.00, EBTCashAvailBalance=0.00, EntryType=Swipe,TaxCity=0.00,TaxState=0.00,Cust1=,Cust1Value=,
Cust2=,Cust2Value=,Cust3=,Cust3Value=,AcntFirst4=4111,TaxAmount=0.00/ExtData>
 
</response>
 
</xmp>

Request for Settlement

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

Request Fields Definition

NameData TypeM/ODescription
RegisterId * VarChar(50) M

Alpha numeric reference field.

TPN * VarChar(12) O

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

1. Close: normal closing

2. Force: Force batch totals

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alpha numeric reference field. Echo back the original value from 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 Definition

NameData TypeM/ODescription
AuthKey * String(25) M

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

RegisterId * VarChar(50) M

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

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

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

t * VarChar(40) M

Text to print

b * N/A O

Indicates that text should be printed in bold

c * N/A O

Indicates that text should be printed centered

If * N/A O

Indicates that printer should feed a line after current string

inv * N/A O

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

Response Fields Definitions

NameData TypeDescription
RefId * VarChar(50)

Alpha numeric reference field. Echo back the original value from request.

RegisterId * VarChar(50)

Alpha numeric reference field.

TPN * VarChar(12)

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

NameData TypeM/ODescription
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.

UserChoice * String M

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

title – specifies a title for the choice menu

count – specifies number of choices

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

Choice * String M

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

Response Fields Definitions

NameData TypeDescription
RegisterId * VarChar(50)

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

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

User Input Request

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

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

NameData TypeM/ODescription
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

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

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

  1. Type: NUMERIC
  • Request to Terminal:
 
<request>
 
 <RegisterId>9724703</RegisterId>
 
 <AuthKey>giVVxrGs5bn</AuthKey>
 
 <UserInput title="Enter phone" maxlen="10" type="n"/>
 
</request>
  • Response from Terminal:
 
<xmp>
 
 <response>
 
   <RegisterId>9724703</RegisterId>
 
   <Message>Success</Message>
 
   <UserInput>1234567890</UserInput>
 
 </response>
 
</xmp>

2.. TYPE : ALPHANUMERIC

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

Batch Report Request

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 Definition

NameData TypeM/ODescription
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.

ReportType * String(25) M

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

TransType * String(10) M

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

Response Fields Definitions

NameData TypeDescription
RegisterId * VarChar(50)

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= (opens in a new tab)

  • 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>
NameData TypeDescription
TaxRateApplied * String

Sum of all tax rate

TotalDiscountAmount * String

Sum of each item discount

PoNumber * String

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

DiscountRate * String

Item level discount rate

LocalTaxAmount * String

Sum of local tax amount for item level

NationalTaxAmount * String

Sum of national tax amount for item level

LocalTaxRate * String

Local tax rate for item level

StateTaxRate * String

State tax rate for item level

TaxAmount * String

Sum of all tax amount for item level

TaxRate * String

Sum of all tax rate for item level

MerchantTaxId * String

Vat merchant tax identification number

CustomerTaxId * String

Vat customer tax identification number

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= (opens in a new tab)

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

Example:

CodeDescription
100001CP-PINPAD which indicates cloud pos pinpad transaction
100002Tonic POS ISV
  • 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>

Cart Items

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

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

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

Mandatory

Information about one item

Name *

Mandatory

Item name. Terminal shows in regular font

Items *

Mandatory

Section that shows items

Amounts *

Mandatory

Section that specify total amounts. Displayed on the bottom of the screen

PosID

Optional

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

Cart

Optional

Tag that contains all the cart item details

Amount

Optional

One line that will be shown in Amounts section

Name

Optional

Text for line with amount

Value

Optional

Recommended using decimal with to two dots after decimal point of use integer values. Possible use minuses

Total

Optional

Highlights which line need to show in big font as the final total value

Price

Optional

Item price. Recommended using decimal with to two dots after decimal point of use integer values

Quantity

Optional

Quantity for item. Will be shows in line with Item name as x[you value]

CustomInfos

Optional

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

CustomInfo

Optional

Information about single additional data

Name

Optional

Custom tag name

Value

Optional

Custom tag value/data

Additional Info

Optional

Description or any data that to be displayed specific to item

Modifiers

Optional

Section that shows additional details for item

Modifier

Optional

Information about one modifier

Name

Optional

Modifier name.

Options

Optional

Section that contents additional information about item that need to show on the screen

Option

Optional

Information about one option

Name

Optional

Option name shows in small fond under Item name

Price

Optional

Price for option. Recommended using decimal with to two dots after decimal point of use integer values. Possible use minuses

Quantity

Optional

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

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

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

SPIn specificationTap to Pay on Android