Issues with error extraction in API response validation

[meglio]

iATS PHP Examples speak very little about how to interpret and extract API errors. As a result, an iATS partner that uses the PHP API wrapper cannot provide detailed and meaningful error messages to their clients.

Take as an example the following PHP code using the iATS PHP wrapper:

public static function validateIatsResponse($resp) {
        if (empty($resp) || !is_array($resp)) {
            if (is_string($resp)) {
                throw new RuntimeException($resp);
            } else {
                throw new RuntimeException('Unknown format of the iATS API Response.');
            }
        }
        if (array_key_exists('AUTHORIZATIONRESULT', $resp)) {
            $authRes = trim($resp['AUTHORIZATIONRESULT']);
            if (substr($authRes, 0, 2) !== 'OK') {

                // Handle cases like these:
                // 0Error:Invalid expiry date
                // 0Error:Invalid credit card number
                if (strtoupper(substr($authRes, 0, 7)) == '0ERROR:') {
                    throw new RuntimeException(substr($authRes, 7));
                }

                $msg = "Request not approved, an error has occurred—possibly due to problems
in delivery, attempt to submit invalid or missing data, etc. iATS does not currently have a list of possible error messages as they can be sent due to different types of processing and from different components, etc.";
                if (strtoupper(substr($authRes, 0, 5)) === 'ERROR') {
                    $msg .= 'Reported error message: ' . $authRes;
                }
                throw new RuntimeException($msg);
            }
        }
        if (array_key_exists('code', $resp) && array_key_exists('message', $resp)) {
            throw new RuntimeException('CODE: ' . $resp['code'] . ', MESSAGE: ' . $resp['message']);
        }
        return $resp;
    }

This code not only follows the examples from iATS documentation, but also additionally parses error messages from authentication results messages prefixed with 0Error. Please note that looking for "0ERROR:" substring in AUTHORIZATIONRESULT is something that can be found imperically, but is not documented.

Using iATS' PHP library usually looks like the following code:

$response = $iATS_CL->createCreditCardCustomerCode($request);
$response = self::validateIatsResponse($response);
$customerCode = $response['CUSTOMERCODE'];
if (empty($customerCode)) {
    throw new RuntimeException('Customer code of the newly created token is empty.');
}

As it can be seen, one has to guess to extract any useful error details, yet there is still no good way which would always allow to extract useful error message and use it to give feedback to clients.

Ideally, PHP wrappers should do the API result validation on its own and
just throw some kind of IatsApiException with correct error message and code,
which the API user can then display to their clients.

In simpler words, the API client should only care about how to handle exceptions, but it is the API library that should throw them with useful information structured.

[Greg-Boggs]

Sounds good to me. Pull Requests to improve the error handling are welcome.

[meglio]

Hi Greg. Only iATS team can improve error handling of its PHP wrapper because the response format is not documented. Also, it is common practice for a PHP library to throw exceptions with meaningful error messages and codes, instead of asking library users to extract the error messages from raw text strings and/or do guesswork regarding undocumented response format.

Currently, we have no other options but to output a generic error message - this confuses clients and they will contact our and your support team every time they cannot guess the issue on their own. As a result, by improving the error handling in iATS PHP library, you will improve the experience of the iATS users and avoid some support requests.

[Greg-Boggs]

We will be working on this feature in the near future. We'll ping you when we have a new version with more robust error message handling.

[meglio]

Thanks, greatly appreciated!