Error Codes and Messages

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

It contains the following 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` - terminal's error `2` - SPIn proxy error
`StatusCode`	Shows specific 4-digit response code for specific situation or terminal statement. There are 3 basic sets of 4-digit codes depending on the side of the SPIn transaction, the place where this message comes from, and the result of the transaction. The number of sets may be extended in the future. The logic is 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 the terminal, or the terminal did not provide a response in an appropriate time. See the list of possible status codes below.
`Message`	Short message about response status.
`DetailedMessage`	Text message in English that describes the 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 messages not in English, they may add a translation for every code on their side.
`DelayBeforeNextRequest`	Time in seconds that is recommended to wait before sending the next request. This returns when the SPIn Proxy service is busy with a 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 an incorrect or inapplicable payment or transaction type.
`1009`	Authentication Failed	Authentication failed (auth key mismatch). Usually this means you need to pull parameters on a terminal or check that the register sends the 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 inapplicable 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 the 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 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 the terminal has a connection to the Internet and to SPIn proxy, and shows that it is ready for transaction.
`2002`	Active AuthKey not found	AuthKey in request is wrong or does not exist. Usually this means a misprint in AuthKey.
`2003`	Register not found	TPN wrong or does not exist. Possible that the request goes to the 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 the server side. Terminal is not active. Two or more devices used the same TPN.
`2006`	Not pars request	Invalid request; it may happen if there's extra space in some values.
`2007`	The operation has timed out	Terminal did not provide a response during the timeout time. Default timeout is 120 seconds. Settlement default timeout is 420 seconds.
`2008`	Terminal in use	Terminal is operating on a previous request; in this case the API returns `DelayBeforeNextRequest` in `GeneralResponse` as a recommendation of the time until the 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

Response

200

Response Attributes

GeneralResponse — object

Attribute	Type
`HostResponseCode`	string
`HostResponseMessage`	string
`ResultCode`	string
`StatusCode`	string
`Message`	string
`DetailedMessage`	string
`DelayBeforeNextRequest`	string

400

Response Attributes

GeneralResponse — object

Attribute	Type
`ResultCode`	string
`StatusCode`	string
`Message`	string
`DetailedMessage`	string
`DelayBeforeNextRequest`	string

Response

{
  "GeneralResponse": {
    "HostResponseCode": "00",
    "HostResponseMessage": "APPROVAL-Approved and completed",
    "ResultCode": "0",
    "StatusCode": "0000",
    "Message": "Approved",
    "DetailedMessage": "APPROVAL VTLMC1",
    "DelayBeforeNextRequest": null
  }
}

{
  "GeneralResponse": {
    "ResultCode": "1",
    "StatusCode": "1013",
    "Message": "Bad Request",
    "DetailedMessage": "Bad Request",
    "DelayBeforeNextRequest": null
  }
}