SPIn specification API

Initial release

Added support for Tags

Added support for iPOSToken

Added PerformedBy Tag

Added userChoice option to PaymentType

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

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

Enabled cart Items display API

Added fee support tag in sale request

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

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.

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

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.

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

Note: Tip must be enabled on terminal

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

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

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.

Alpha numeric reference field.

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>

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

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

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

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.

Same as Tag1

Same as Tag1

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.

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

Alpha numeric reference field.

TPN sent in the request is returned

Transaction number identified on terminal

Unique alphanumeric invoice field.

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

Alpha numeric field from SPIn Proxy or Terminal

Alpha numeric field from SPIn Proxy or Terminal.

Alpha numeric field from Processor.

Alpha numeric field from SPIn Proxy or Terminal.

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.

True/False – Flag used to define if a transaction has been voided. Used more with Status transaction type

Identifies the type of transaction performed

Serial Number of the terminal that performed the transaction

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

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

Base64 encoded signature image in b/w bitmap format

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.

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

Alpha numeric reference field.

Alpha numeric TPN field.

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

Identifies the type of transaction to be run – Capture

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

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

Note: Tip must be enabled on terminal

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

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

Alpha numeric reference field. Echo from original request.

Alpha numeric TPN field.

Transaction status: 0-succeeded, 1-failed

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)

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.

Alpha numeric reference field.

Alpha numeric TPN field.

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

Identifies the type of transaction to be run – TipAdjust

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

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

Note: Tip must be enabled on terminal

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

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

Alpha numeric reference field.

Alpha numeric TPN field.

Transaction status: 0-succeeded, 1-failed

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)

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.

Alpha numeric reference field.

Alpha numeric TPN field.

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

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

Identifies the type of transaction to be run – Void

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

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

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

Alpha numeric reference field.

Alpha numeric TPN field.

Transaction status: 0-succeeded, 1-failed

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)

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

Alpha numeric reference field.

Alpha numeric TPN field.

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

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

Identifies the type of transaction to be run – Status

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

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

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

Alpha numeric reference field.

Alpha numeric TPN field.

Transaction status: 0-succeeded, 1-failed

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)

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

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

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

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

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.

Base64 encoded signature image in b/w bitmap format

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

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.

Alpha numeric reference field.

Alpha numeric TPN field.

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

Alpha numeric reference field.

Identifies the type of transaction to be run – Settle

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

Type of Settlement request:

1. Close: normal closing

2. Force: Force batch totals

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

Alpha numeric reference field.

Alpha numeric TPN field.

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

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

0 – Success

1 - Failure

Alpha numeric field from gateway.

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

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

Alpha numeric reference field.

Alpha numeric TPN field.

Alpha numeric reference field.

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

Text to print

Indicates that text should be printed in bold

Indicates that text should be printed centered

Indicates that printer should feed a line after current string

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

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

Alpha numeric reference field.

Alpha numeric TPN field.

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

Alpha numeric reference field.

Alpha numeric TPN field.

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

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

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

Alpha numeric reference field.

Alpha numeric TPN field.

Response to Request for a user choice

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

Success

Failure

Cancel

Alpha numeric reference field.

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

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

Alpha numeric reference field.

Response value to request for a user input.

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

Success

Failure

Cancel

Alpha numeric reference field.

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

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

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

Alpha numeric reference field.

It responded with a Result Code

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

Success

Failure

Cancel

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.

Sum of all tax rate

Sum of each item discount

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

Item level discount rate

Sum of local tax amount for item level

Sum of national tax amount for item level

Local tax rate for item level

State tax rate for item level

Sum of all tax amount for item level

Sum of all tax rate for item level

Vat merchant tax identification number

Vat customer tax identification number

Mandatory

Information about one item

Mandatory

Item name. Terminal shows in regular font

Mandatory

Section that shows items

Mandatory

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

Optional

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

Optional

Tag that contains all the cart item details

Optional

One line that will be shown in Amounts section

Optional

Text for line with amount

Optional

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

Optional

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

Optional

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

Optional

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

Optional

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

Optional

Information about single additional data

Optional

Custom tag name

Optional

Custom tag value/data

Optional

Description or any data that to be displayed specific to item

Optional

Section that shows additional details for item

Optional

Information about one modifier

Optional

Modifier name.

Optional

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

Optional

Information about one option

Optional

Option name shows in small fond under Item name

Optional

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

Optional

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

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.

There is an error in the request message format.

Check a request format.

A terminal does not have SPIn Connection. The Connection is not created.

On the Terminal Details page create a new SPIn Proxy connection.

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

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

A terminal operates another request.

Wait when the previous request is completed and repeat a new request to a terminal.

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

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

Terminal was reconnected after receiving the request and before providing the response

Do Status request to check transaction Status