Here you can find codes and descriptions of all errors that may occur when you communicate with the Switch APIs.

If after reading this section you are still not sure how to interpret and solve a specific error, please contact our Support Team.

• Error Code Format: XX.YY.ZZZZ (numeric)
• 01.YY.ZZZZ: Validation Errors
  The request failed because there are issues with the data being sent.
• 02.YY.ZZZZ: Soft Declines
  The request was declined. Yet, subsequent attempts may be successful.
• 03.YY.ZZZZ: Hard Declines
  The request was declined. Most hard declines require the issuer or customer to rectify issues before a subsequent attempt can be made.
• 04.YY.ZZZZ: Communication
  Problems in the communication between Switch and the processor. If these issues are recurring, it is important to check for the root cause.
• 05.YY.ZZZZ: Implementation
  Errors raised when the integration with Switch was performed incorrectly.
• 06.YY.ZZZZ: Risk
  Possible fraudulent activities.
• 99.YY.ZZZZ: Unhandled Errors
  The request failed due to unspecified reasons. Further analysis might be needed.

Validation Errors

Soft Declines

Hard Declines

Communication

Implementation

Risk

Unhandled Errors

Error Testing

Error handling is an important step in integration. To aid with error testing we have made triggering these errors a straightforward process. You only need to mind the amount set when you create a transaction.

In order to come up with the right amount to trigger the error you are looking for, mind the following instructions.

• Amount: XZZZZ.YY (numeric);
• The integer part of the amount represents the error code that will be returned. The decimal part of the amount represents the element from which the error originates (e.g. 0.10 for charge, 0.20 for instrument, 0.30 for payment, 0.40 for refund, 0.50 for reversal);
• Do not include the "." separators and the leading "0"s in this number.

Examples:

• "amount": 6020000.20 Results in an instrument error (0.20), error code 06.02.0000.
• "amount": 3030001.30 Results in a payment error (0.30), error code 03.03.0001.

Let’s use the first amount to exemplify the procedures involved in triggering an error. "amount": 6010000.20 Results in an instrument error (0.20), error code 06.01.0000.

CREATE CHARGE: REQUEST PARAMETERS
    $ curl -vX POST https://api-test.switchpayments.com/v2/charges -u accountId:privateKey -d '{
      "charge_type": "card_onetime",
      "amount": 6020000.20,
      "currency": "EUR",
      "events_url": "https://merchant.com/events",
      "channels": ["card_onetime_no_processor"]
    }

"amount": 6020000.20

All transactions begin with a charge. When creating this charge, you should input the amount that corresponds to the error you intend to trigger.

Additionally, you should note that the amount that defines the error is always the charge_amount, even if the current resource allows for a different amount to be set (e.g. payments, refunds).

"channels": ["card_onetime_no_processor"]

You should use a no_processor Switch channel for error testing. Channels result from a concatenation of the charge_type applied and the actual channel used for the transaction, hence the ["card_onetime_no_processor"] in this case. To gain access to this test channel and proceed with error testing you should contact our Support Department.

CREATE CHARGE: RESPONSE PARAMETERS
    {
        "id": "675d32208a91bd3ad70641ba7f810036c65f5bb75ea9897f",
        "external_ids": null,
        "charge_type": "card_onetime",
        "charge_type_label": "Card One-Time",
        "amount": 6020000.2,
        "currency": "EUR",
        "events_url": "https://merchant.com/events",
        "redirect_url": "",
        "metadata": {},
        "instrument_params": null,
        "failure_code": null,
        "failure_description": null,
        "channels": [
            {
                "id": "d33577bcdc1ed9e106c050ff02bcccc285d57c5c5ea98619",
                "label": "card_onetime_no_processor",
                "processor": "no_processor"
            }
        ],
        "confirmed": true,
        "created_at": "2020-04-29T14:04:47.145730+00:00",
        "expires_at": null,
        "updated_at": "2020-04-29T14:04:47.145770+00:00",
        "request_log": {
            "ip_address": "89.155.14.252",
            "country": "PT",
            "user_agent": "PostmanRuntime/7.24.1",
            "library_version": null
        },
        "external": false
    }

The error we are triggering is generated in an instrument. Next, create an instrument deriving from the previous charge, using the correspondent charge_id.

CREATE CHARGE: RESPONSE PARAMETERS
      {
        "charge": "675d32208a91bd3ad70641ba7f810036c65f5bb75ea9897f",
        "name": "John doe",
        "number": "4111111111111111",
        "expiration_month": 12,
        "expiration_year": 2020,
        "cvc": "007"
    }

You should find the error in the response. In this case, we triggered a 06.02.0000: Unsafe Transaction. The respective instrument generated is invalid, as observable in the Switch Dashboard.

CREATE INSTRUMENT: RESPONSE PARAMETERS
    {
    "message": "Transaction Error",
    "metadata": {
        "failure_description": null
    },
    "failure_description": "Unsafe Transaction",
    "failure_code": "06.02.0000"
  }

If after reading this section you are still not sure how to trigger a specific error, please contact our Support Department.