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