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

  1. 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.

    • Example: HTTP 401 Unauthorized – This occurs if the client is not authorized to access the requested resource.

  2. JSON-RPC Errors (Method-Specific Errors):
    These errors 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.

    • Example: Invalid parameters – A required parameter is missing or incorrectly formatted.

  3. Response Handling for Methods That Start Processing:
    Some methods do not immediately complete their operation upon receiving the request. Instead, they begin processing and return a response indicating that the request is valid and processing has started.

    • Response Contains a Result:
      For methods that start processing, the response will include a Result field. If the request is valid, the Result field indicates that the operation has begun, but the task is not yet completed.

      • Error in the Result Field: If an issue occurs during processing (like a user cancellation or a timeout), the error will be returned inside the Result field, signaling that the request was valid, but some problem prevented the task from completing.

    • Key Point: If the response contains a Result field, it means processing has started. The response could either contain a successful result or an error related to the processing, depending on what happened during the execution.

  4. 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: The transaction was declined by the host.
      • Processing failure: The host determined that the transaction request was invalid for some reason.

    • 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 More

Example Error Response

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