API explorerDejavoo web site
API explorer
Dejavoo web site

Dark mode

SPIn REST API Methods

Base URL

Production:

https://api.spinpos.net

SandBox:

https://test.spinpos.net/spin

Gift

undefined

Receipt format

Tags

Description

DvPay

DvPay Lite

Aura

LG

Large Text

✅

✅

✅

INV

Inverted text

✅

✅

✅

CD

All text inside this tag will be formatted as condensed

✅

✅

✅

B

All text inside this tag will be formatted as bold

✅

✅

✅

BR

Extra line feed

✅

✅

✅

C

 The text inside this tag will be horizontally centered

✅

✅

✅

R

The text inside this tag will be aligned to the right. Use it for long text that takes few lines

✅

✅

✅

L

The text inside this tag will be aligned to the left

✅

✅

✅

IMG

This tag includes base64-encoded monochrome BMP or PNG image data in request. Response contents PNG

✅

BMP only

QR

The text inside this tag will encoded and printed as QR code

✅

✅

POST

/

Select
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 curl --location 'https://api.spinpos.net/' \ --data '{ "Printer": "<L>Test text format</L> <L>Normal text</L> <LG> <L>Large Text</L> </LG> <INV> <L>Inverted text</L> </INV> <CD> <L>Condensed text</L> </CD> <B> <L>Bold text</L> </B> <INV> <LG> <L>Large Inverted text</L> </LG> </INV> <CD> <LG> <L>Large Condensed text</L> </LG> </CD> <LG> <B> <L>Large Bold text</L> </B> </LG> <INV> <B> <L>Bold Inverted text</L> </B> </INV> <CD> <B> <L>Bold Condensed text</L> </B> </CD> <BR /> <L>Text alignment</L> <L>Left text</L> <C>Center text</C> <R>Right text</R> <L>Left text</L> <R>Right text</R> <BR /> <L>Image</L> <IMG>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</IMG> <BR /> <L>Line Width</L> <L>123456789012345678901234567890</L> <BR /> <L>QR code</L> <QR>https://app.theneo.io/dejavoo/spin</QR> <BR /> <L>Feed</L> <BR /> <BR /> <BR /> <BR /> <BR /> <BR /> <BR /> <BR />", "Tpn":"", "Authkey":"", "SPInProxyTimeout":125 }'
Was this section helpful?

What made this section unhelpful for you?

Signature

Signature that terminals returns is .PNG image coded in Base64 format.

Was this section helpful?

What made this section unhelpful for you?

Extended Data for Responses

Parameter

Comment

DvPay

DvPay Lite

AcntFirst4

first 4 digits of PAN

AcntLast4

last 4 digits of PAN

AcqRefData

long acquirer reference ID (used in Mercury/Vantiv processor).

Amount

reflects the transaction amount provided in SPin request.

AppName

application name (Settlement only)

AVSRsp

AVS response from the payment host

BatchNum

current batch number

BIN

BIN of the card

CardType

card type/processing network.

  • VISA
  • MASTERCARD
  • AMEX (American Express)
  • DISCOVER
  • PAYPAL
  • DINERSCLUB
  • JCB
  • CUP (China Union Pay)
  • ENROUTE
  • DEBIT
  • EBT

Cashback

cashback amount

ClerkId

clerk/server ID

ControlNum

fiscal control number

Cust1

custom prompt #1 title (see Cust1 field)

Cust1Value

value entered by used during #1 custom prompt

Cust2

custom prompt #2 title (see Cust2 field)

Cust2Value

value entered by used during #2 custom prompt

Cust3

custom prompt #3 title (see Cust3 field)

Cust3Value

value entered by used during #3 custom prompt

CVVRsp

CVV response from the payment host

DISC

debit discount amount

Donation

donation amount

EBTCashAvailBalance

EBT Cash available balance

EBTCashBeginBalance

EBT Cash begin balance

EBTCashLedgerBalance

EBT Cash ledger balance

EBTFSAvailBalance

EBT SNAP available balance

EBTFSBeginBalance

EBT SNAP begin balance

EBTFSLedgerBalance

EBT SNAP ledger balance

EntryType

entry method used to provide card data.

  • Swipe
  • Manual
  • CHIP
  • Specific
  • Contactless
  • CHIP Contactless
  • CHIP/Swipe (Fallback only)
  • CHIP/Manual (Fallback only)
  • CHIP Contactless/Swipe (Fallback only)
  • CHIP Contactless/Manual (Fallback only)

ExpDate

card expiry date

Fee

total fee amount

InvNum

transaction invoice number. If invoice number is missing, transaction number will be used instead

Language

transaction language.

  • English
  • French
  • Hebrew (AURA only)

Name

URL-encoded cardholder name

NumTrans

the number of transactions within batch (Settlement only)

Receipt

settlement report copy (Settlement copy, for more see Digital Receipt format)

RefNo

Mercury/Vantiv reference number

RewardCode

Loyalty promo code

RewardQR

Loyalty QR code

Rsp

response code (Settlement only)

  • 0 – success
  • 1 – failure

RwdBalance

Loyalty balance

RwdIssued

Loyalty reward issued

RwdPoints

Loyalty points acquired

SHFee

Service and Handling Fee, if enabled

Status

payment host response message (Settlement only)

SVC

debit surcharge amount

TableNum

table number

TaxAmount

commercial tax amount

TaxCity

fiscal city tax amount

TaxState

fiscal state tax amount

TicketNum

ticket number

Tip

tip amount

TipAmt

total tip amount (Settlement only)

TotalAmt

total transaction amount

Was this section helpful?

What made this section unhelpful for you?

Error Codes and Messages

Each response has section GeneralResponse section that informs about successful result or error with error code and description

It contents the next data

Parameter

Comment

HostResponseCode

This response code comes from the payment processor as is. It is usually referring to ISO 8583-1987.

HostResponseMessage

Meanings for host response code that comes from the payment processor as is. It is usually referring to ISO 8583-1987.

ResultCode

0 - success

1 - terminals error

2 spin prosy error

StatusCode

Shows specific 4-digit response code for specific situation or terminal statement

The are 3 basic sets of 4-digit codes depends on a side of spin transaction and a place where this message comes from and a result of transaction. Number of sets may be extended in the future. The logic close to HTTP Status Codes.

  • 0xxx - successful responses from terminal application. The response comes from a terminal application.
  • 1xxx - error responses from terminal app. The response was sent from a terminal.
  • 2xxx - error response from SPIN Proxy server. The response did not reach terminal or terminal did not provide a response in appropriate time.

List of possible status codes see below.

Message

Short message about response status

DetailedMessage

Text message in English that describes Status Code.

Register application may show this message or use StatusCode only and show their own messages for every StatusCode. For example if a register needs to show the messages not in English they may add translation for every code on their side.

DelayBeforeNextRequest

Time in seconds that recommended to wait before send next request. This returns when SPIn Proxy service is busy with previous request.

StatusCode list of values

0xxx - Successful responses from terminal application

Status Code

Detailed Message

Description

0000

Approved

The transaction or a service request was approved

0001

Partial Approval

  • The transaction was partially approved by the host
  • One or more (but not all) applications approved the settlement request

NOTE: On the test host for partial approval you need to make a sale with $50 base amount and $2 tips - TSYS (depends on the host)

1xxx - Error responses from terminal app

Status Code

Detailed Message

Description

1000

Terminal Busy

  • The terminal is busy processing another SPIN request
  • The terminal is in SPIN bypass mode

1001

Not Found

  • Get Parameter or Set Parameter service could not find requested parameters
  • Status request could not find a matching transaction record
  • Void request could not find a matching transaction record
  • Tip Adjustment request could not find a matching transaction record
  • Get request could not find matching transaction records
  • TSYS level 3 request could not find a matching transaction record

1002

Not Implemented

  • Unsupported service requested (Invoice, GetCard, etc.)

1003

Not Supported

  • Get PIN service request could not find a proper payment application
  • Tip Adjustment request could not find a proper payment application
  • Upload SnF request could not find a proper payment application
  • Batch Report request could not find a proper payment application
  • Disclaimer service requested on a terminal with no touch capability

1004

Not Allowed

  • A Void Auth requested for a processor that does not allow Void Auth
  • A non-EBT voucher transaction requested
  • A manual Debit card entry attempted and the processor is not BridgePay
  • A tip amount is sent in an Auth request
  • A custom fee is sent in an Auth or EBT request

1005

Low Battery

  • Battery charge is low

NOTE: not implemented on Android devices)

1006

Internal Error

  • Printer service requested when the terminal is out of paper
  • Unexpected internal terminal error happened

1007

Format Error

  • The SPIN request uses an unsupported markup language or the request is malformed

1008

Wrong Payment Or Transaction Type

  • The transaction request uses incorrect or inapplicable payment or transaction type

1009

Authentication Failed

  • Authentication failed (auth key mismatch). Usually this means need to pull parameters on a terminal or check that register sends correct AuthKey.

1010

Missing Reference ID

  • The reference ID is missing in a request that requires it

1011

Duplicate Reference ID

  • A transaction with a requested reference ID already exists in the batch

1012

Cancelled

  • User cancelled the transaction or it was interrupted for an unknown reason

1013

Bad Request

  • Incorrect printer service request
  • User Choice service request has no nested items to choose from
  • User Input service request does not specify the input type
  • Software Download service request is missing one or more mandatory parameters
  • Load Key or Delete Key service request is missing one or more mandatory parameters
  • A transaction request has no payment or transaction type
  • 0 amount requested for an unapplicable transaction
  • Amount length is invalid
  • Invalid ATM amount for PointOfBanking or BridgePay
  • A tip amount is sent when tip is disabled or in "on percent" mode
  • Cashback amount of 0 entered by the user when terminal is configured for a non-zero cashback
  • Fee, tip and cashback amounts are greater than the total amount of the transaction
  • Invalid clerk ID requested
  • Tip Adjustment request has no amount, tip or reference ID
  • Get request is missing range parameters
  • Get request has an invalid range
  • TSYS level 3 request has no auth code

1014

Communication Error

  • Communication error with a third party host occurred

1015

Declined

  • Load Key or Delete Key request failed
  • Settlement requested with no payment applications installed
  • A transaction is declined offline or by the host
  • A settlement request is declined by the host

1016

Payment Type Mismatch

  • Payment type of the transaction is not applicable for the card

1017

Incorrect Merchant ID

  • Invalid merchant ID specified in request

1018

PINpad Communication Error

  • A communication error with the PINpad device occurred

1019

No Debit Keys Loaded

  • An encrypted PIN was requested by the transaction, but the terminal has no keys loaded

1020

No Open Batch

  • No application that has an open batch during a settlement request

1021

Pending SnF Transaction

  • Settlement has been requested, but the terminal is in SnF mode and has pending transactions to upload

1022

Untipped Transactions Remain

  • Settlement has been requested, but the terminal is in restaurant mode and has untipped transactions

1023

Open Tab

  • Settlement has been requested, but the terminal has an open tab

20xx - Error response from SPIN Proxy Server

Status Code

Detailed Message

Description

2001

Terminal not connected to SPIn Proxy server

  • need to check that terminal has connection to the Internet and to SPIn proxy and shows that it is ready for transaction

2002

Active AuthKey not found

  • AuthKey in request does is wrong or does not exists. Usually this means misprint in AuthKey

2003

Register not found

  • TPN wrong or does not exists
  • Possible that the request goes to wrong server test instead of prod or vice-versa

2004

Route not found

  • TPN does not have configuration for SPIn proxy

2005

Active route not found

  • Connection was blocked on server side
  • Terminal is not active
  • Two or more devices used the same TPN

2006

Not pars request

  • Invalid request it may happen if self extra space in some values

2007

The operation has timed out

  • Terminal did not provide response during timeout time. Default timeout is 120 seconds. Settlement default timeout is 420 seconds

2008

Terminal in use

  • Terminal operate previous request in this case API returns DelayBeforeNextRequest in GeneralResponse as a recommendation to specify time when timeout will happen.

2009

Transaction not found

2010

Communication error

2011

Terminal is not available

21xx - Error response from SPIN Proxy Server Async Requests with Call-back

Status Code

Detailed Message

Description

2101

Callback Url was not specified

2102

Invalid XML document

2110

Internal exception

Responses

200
Object

Response Attributes

GeneralResponseobject

Show child attributes

400
Object

Response Attributes

GeneralResponseobject

Show child attributes

Response

{
  "GeneralResponse": {
    "HostResponseCode": "00",
    "HostResponseMessage": "APPROVAL-Approved and Completed",
    "ResultCode": "0",
    "StatusCode": "0000",
    "Message": "Approved",
    "DetailedMessage": "APPROVAL VTLMC1",
    "DelayBeforeNextRequest": null
  }
}
Was this section helpful?

What made this section unhelpful for you?

Transaction types scheme

Description: scheme describes how which transaction types can apply to original transaction, for example you can't do Void and Tip adjust without sale (Sale root)

Sale root:

Refund/Return root:

Auth - capture root:

Was this section helpful?

What made this section unhelpful for you?