Business::CPI::Role::Exception - Exceptions from the gateway
version 0.924
This role is meant to be used by the drivers to encapsulate gateway exceptions, put them in the required format, and rethrowing them as real Perl exceptions (using Throwable).
The type is a string, that will contain one of the predefined values mentioned below. The examples will refer to HTTP Status, but the exceptions are not limited to HTTP errors. The gateway API doesn't need to be RESTful.
Part or all of the data provided to the gateway was not valid. Example: the buyer name contained numbers.
The data sent to the gateway was not complete. Example: the buyer name was missing.
The request could not be made because it's formatted in a way the gateway did not expect. Most likely this is due to an error in the Business::CPI driver.
Example: the gateway responded with HTTP status 405, 406, 417, etc, supposing a RESTful API.
Some item in the request references an item which was not found in the gateway, or the request returns HTTP status 404.
The API user is not authorized to make this request (HTTP Status 403).
The API user is not properly authenticated (HTTP Status 401).
The transaction has already been executed. Example: a shopping cart which has already been payed, or a refund that has already been requested.
The gateway API could respond HTTP 200 OK, but it's not always the case. When it responds with error, and this is the reason, the type will be duplicate_transaction.
Some business logic in the gateway determined that this request could not be completed. Example: requesting a refund of a payment which is still processing. That is, the payment exists (not "resource_not_found"), the request is valid, the data is complete and valid, but it cannot be fulfilled.
The gateway API responded with one of the following HTTP Status, for example: 408, 502, 503 or 504. That is, either a timeout occurred, or the server reported to be unavailable.
There was an internal server error in the gateway.
The gateway threw some kind of exception that Business::CPI was unable to parse.
A human readable message of the error, preferably in English, either generated by Business::CPI, the driver, or the gateway. This serves only for debuging purposes, and not for your code to parse this and handle the exception.
Plain HashRef (i.e., not blessed) containing any extra data regarding the exception that might be useful. For example:
{ raw_lwp_request => $req, # $res->isa('HTTP::Request') raw_lwp_response => $res, # $res->isa('HTTP::Response') http_status_code => 400, error_code => 'XM-231', message => 'That currency is currently not supported', context => 'currency', exception_id => 'e171eadad51791966aad6ac10bb6d16354d1952', }
That HashRef is supposed to be non-standard, as a way of keeping information that is only relevant to certain gateways. Although some things might be standardized, such as the LWP request and response, for instance. Again, this is still being designed.
This is very EXPERIMENTAL. We're still designing the interface, and the error codes are not defined yet. This role will not be usable before the documentation of all error codes.
André Walker <andre@andrewalker.net>
This software is copyright (c) 2015 by André Walker.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Business::CPI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Business::CPI
CPAN shell
perl -MCPAN -e shell install Business::CPI
For more information on module installation, please visit the detailed CPAN module installation guide.