Skip to content

Error Handling in Synqpay

Synqpay uses the JSON-RPC protocol to handle errors during communication between the client and the payment device. This document explains how errors are structured and handled within this protocol, including the error hierarchy and various types of errors that may be encountered.

Error Hierarchy

Transport Layer Errors

These errors occur at the transport layer and are not related to the processing of the JSON-RPC request itself. They typically indicate issues with the underlying connection or authorization. This is the highest level of errors that may occur, emphasizing their position at the top of the error hierarchy.

Each transport layer error contains additional data regarding the specific issue, such as HTTP status codes or connection error details, to help identify and resolve the problem.

Example: HTTP 401 Unauthorized

This occurs if the client is not authorized to access the requested resource.

JSON-RPC Errors (Method-Specific Errors)

All methods process the requests and return a response once the processing is complete. The response will indicate whether the operation was successful or not. Hence, the response will either include an Error object or the method's Result object according to JSON-RPC and method specs, depending on the outcome of the request.

The Error objects are thrown when the request cannot be processed due to issues within the method itself, such as invalid parameters or an unsupported operation. Each method specifies the types of errors it may throw, and these errors prevent the request from being processed. The errors are listed in the Errors page

Example

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "1234",
    "error": {
        "code": 102,
        "message": "payment method is missing"
    }
}

Response Handling for Methods with Processing Results

Some methods include result field within the Result object. This field indicates whether the processing was successful or not:

  • Successful Processing: The result field confirms that the operation was completed successfully.
  • Error During Processing: If an issue occurs during processing (e.g., user cancellation or timeout), the result field will indicate the failure and provide more details about the processing.

See Result Enumerator for possible outcome for this field.

  • Key Point: The presence of a result field in the response is typical for methods involving longer operations, such as transaction processing, or cancelable operations. This field provides the final outcome of the operation once it is complete.

Example: User canceled the transaction processing

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "jsonrpc": "2.0",
    "id": "1234",
    "result": {
        "result": "CANCELED",
        "commandStatus": "COMPLETED",
        "transaction": {
            "transactionStatus": "DECLINED",
            "transactionTime": "2025-04-07T11:52:35.699+03:00",
            "referenceId": "dac40c6a-8a0e-465e-82b1-9347bf5eee11",
            "terminalId": "0881818",
            "appVersion": "1.4.0-rc.1",
            "transactionType": "SALE",
            "amount": 110,
            "totalAmount": 110,
            "tipAmount": 0,
            "currency": 376,
            "transactionId": "",
            "terminalNo": 0,
            "cvvResponse": "NO_CVV",
            "cardHolderIdResponse": "NO_CARDHOLDER_ID"
        }
    }
}

Transaction-Specific Errors

Transaction requests have a special error handling structure. The result field in the response indicates whether the transaction was successful or not, but there's an additional level of error handling when HOST_ERROR is encountered.

  • Approved Transaction:
    If the transaction is successfully approved, the result will be OK, and the transaction has been processed.

  • Transaction Failure with HOST_ERROR:
    If the transaction is not approved, the result may be HOST_ERROR. This indicates that the transaction could not be processed because of a host-level decision, such as Online decline where The transaction was declined by the host or Processing failure where The host determined that the transaction request was invalid for some reason. In the case of a HOST_ERROR, the transaction object is nested within the result object and contains additional details about the transaction, including the host error:

    • hostErrorCode: A code representing the specific error returned by the host.
    • hostErrorMessage: A human-readable message describing the error returned by the host.

  • Best Practice:
    While the HOST_ERROR in the result field indicates a failure, it is recommended to also check the transactionStatus field (e.g., CAPTURED, DECLINED, etc.) for more detailed information about the transaction status See Transaction Processing.

Example: Host declined the transaction

 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
  {
  "jsonrpc": "2.0",
  "id": "37f4a784-1e2d-4f1e-89e6-1b302dcd7644",
  "result": {
      "result": "HOST_ERROR",
      "commandStatus": "COMPLETED",
      "transaction": {
          "transactionStatus": "DECLINED",
          "hostErrorCode": 4,
          "hostErrorMessage": "סירוב בחברת האשראי",
          "transactionTime": "2025-04-07T11:55:26.959+03:00",
          "referenceId": "0d4c1252-2b15-4efe-86d0-028ea2516fc4",
          "terminalId": "0881818",
          "appVersion": "1.4.0",
          "transactionType": "SALE",
          "amount": 110,
          "totalAmount": 110,
          "tipAmount": 0,
          "currency": 376,
          "transactionId": "25040711552608818183141",
          "systemTraceNumber": "03001004",
          "cardName": "מסטרקארד רגיל",
          "maskedPan": "510046XXXXXX7315",
          "panSuffix": "7315",
          "terminalNo": 1,
          "creditTerms": "REGULAR",
          "panEntryMode": "CONTACTLESS"
          ...
      }
  }
}