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 | ✅ | ✅ |
What made this section unhelpful for you?
Signature
Signature that terminals returns is .PNG image coded in Base64 format.
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.
| ||
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.
| ||
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.
| ||
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)
| ||
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 |
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.
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 |
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 |
|
1001 | Not Found |
|
1002 | Not Implemented |
|
1003 | Not Supported |
|
1004 | Not Allowed |
|
1005 | Low Battery |
NOTE: not implemented on Android devices) |
1006 | Internal Error |
|
1007 | Format Error |
|
1008 | Wrong Payment Or Transaction Type |
|
1009 | Authentication Failed |
|
1010 | Missing Reference ID |
|
1011 | Duplicate Reference ID |
|
1012 | Cancelled |
|
1013 | Bad Request |
|
1014 | Communication Error |
|
1015 | Declined |
|
1016 | Payment Type Mismatch |
|
1017 | Incorrect Merchant ID |
|
1018 | PINpad Communication Error |
|
1019 | No Debit Keys Loaded |
|
1020 | No Open Batch |
|
1021 | Pending SnF Transaction |
|
1022 | Untipped Transactions Remain |
|
1023 | Open Tab |
|
20xx - Error response from SPIN Proxy Server
Status Code | Detailed Message | Description |
2001 | Terminal not connected to SPIn Proxy server |
|
2002 | Active AuthKey not found |
|
2003 | Register not found |
|
2004 | Route not found |
|
2005 | Active route not found |
|
2006 | Not pars request |
|
2007 | The operation has timed out |
|
2008 | Terminal in use |
|
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
Response Attributes
Show child attributes
Response Attributes
Show child attributes
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)