SPIn Proxy RESTful API

## Sections
• [Sale](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/sale.md): Sale is the most common request that user to do payment on a terminal.All the responses have GeneralResponse section that informs about successful result or error. See Error Codes and Messages.
• [Return](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/return.md): Return is an independent operation and it does not relate to any Sale transaction. Please use a unique ReferenceID for Return request. You may do return on any amount. For a terminal app Return operation is not related to any Sale that you did in the past. Return does charge back and behaves as Sale only vice-versa and add money on card balance.
• [Tip Adjust](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/tip-adjust.md)
• [Auth](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/auth.md)
• [Capture](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/capture.md)
• [Void](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/void.md): Void operation cancels operation that it is referring to. Void need to do before Settlement. You cannot do Void after Settlement in this case you will need to do Return. Insert line aboveInsert line belowDelete Void may be done for Sale , Return , Auth , Capture requests. Insert line aboveInsert line belowDelete To do void you need to know ReferenceID and amount of transaction that you void.
• [Summary Report](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/summary-report.md)
• [Daily Report](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/daily-report.md)
• [Printer](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/printer.md)
• [Status](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/status.md)
• [Status List](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/status-list.md)
• [Offline Status](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/offline-status.md)
• [Settle](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/settle.md)
• [Get Signature](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/get-signature.md): Prompts a dialog on terminal to draw a signature on terminal screen.
• [User Choice](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/user-choice.md)
• [User Input](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/user-input.md)
• [Disclaimer](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/disclaimer.md)
• [Terminal Connection Status](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/common-terminal-status.md)
• [Select Invoice](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/select-invoice.md)
• [Payment Invoice](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/payment-invoice.md)
• [Abort Transaction](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/abort-transaction.md)
• [Cart](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/cart.md)
• [Get Card](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/get-card.md)
• [Balance](https://app.theneo.io/dejavoo/spin/spin-rest-api-methods/sale-copy.md): Sale is the most common request that user to do payment on a terminal.All the responses have GeneralResponse section that informs about successful result or error. See Error Codes and Messages.
• [Reload](https://app.theneo.io/dejavoo/spin/gift/reload.md)
• [Reissue](https://app.theneo.io/dejavoo/spin/gift/reissue.md)
• [Refund](https://app.theneo.io/dejavoo/spin/gift/refund.md)
• [Redeem](https://app.theneo.io/dejavoo/spin/gift/redeem.md)
• [Inquire](https://app.theneo.io/dejavoo/spin/gift/inquire.md)
• [Deactivate](https://app.theneo.io/dejavoo/spin/gift/deactivate.md)
• [Activate](https://app.theneo.io/dejavoo/spin/gift/activate.md)
• [Void](https://app.theneo.io/dejavoo/spin/gift/gift-void.md)
• [Signature](https://app.theneo.io/dejavoo/spin/signature.md): Signature that terminals returns is .PNG image coded in Base64 format.
• [Extended Data for Responses](https://app.theneo.io/dejavoo/spin/extended-data-for-responses.md): 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
• [Error Codes and Messages](https://app.theneo.io/dejavoo/spin/error-codes-and-messages.md): 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
• [Transaction types scheme](https://app.theneo.io/dejavoo/spin/transaction-types-scheme.md): 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:
• [Remove Level3 Item](https://app.theneo.io/dejavoo/spin/l2l3/remove-level3-item.md)
• [View Level3 Item](https://app.theneo.io/dejavoo/spin/l2l3/view-level3-item.md)
• [Add Level3 Item](https://app.theneo.io/dejavoo/spin/l2l3/add-level3-item.md)
• [Get Intermediate Status](https://app.theneo.io/dejavoo/spin/intermediate-status/get-intermediate-status.md)
• [Post Intermediate Status](https://app.theneo.io/dejavoo/spin/intermediate-status/post-intermediate-status.md)
• [CEDP Sale](https://app.theneo.io/dejavoo/spin/cedp/cedp-sale.md): As part of VISA’s updated CEDP (Cardholder Enhanced Data Program), Level 3 data is now required for commercial and corporate card transactions to qualify for optimized interchange rates.Insert line topInsert line belowDelete To support this, please ensure you are submitting accurate, complete, and properly formatted Level 3 data in your requests. Poor data quality (e.g., missing fields, incorrect values, or placeholder data) may lead to downgraded interchange qualification or rejections.Insert line topInsert line belowDelete This includes fields such as item descriptions, quantities, unit costs, tax amounts, and other line-item details. The cleaner and more complete the data, the better the chances of qualifying for enhanced rates.
• [Samples](https://app.theneo.io/dejavoo/spin/cedp/samples.md): Below are 2 sample requests showing the expected tagging format. Please use these as a reference when submitting Level 3 data.
• [Post Callback](https://app.theneo.io/dejavoo/spin/post-callback.md)
• [Callback Get Last Callback](https://app.theneo.io/dejavoo/spin/callback-get-last-callback.md)
• [Capture CEDP](https://app.theneo.io/dejavoo/spin/capture-cedp.md)
• [Upload Transaction](https://app.theneo.io/dejavoo/spin/upload-transaction.md)
• [Auto Rental Sale](https://app.theneo.io/dejavoo/spin/autorental/auto-rental-sale.md)
• [Auto Rental Auth](https://app.theneo.io/dejavoo/spin/autorental/auto-rental-auth.md)
• [Auto Rental Capture](https://app.theneo.io/dejavoo/spin/autorental/auto-rental-capture.md)