The AGMS Code Libraries are built to allow you to integrate your system or app with the AGMS Gateway with minimal effort. The libraries handle all setup, validation, request, and response with the APIs, leaving you to simply set the inputs and handle the output.
Libraries are built in a number of languages with varying support of API endpoints and features. Some may only support the Transaction API while others support all of them. Please see the README of the library itself for details. If you have a project that requires support of a language, feature, or API not currently included in our library, please contact us for assistance.
While our Code Samples are only meant to be a quick demonstration of an API connection to give you a jump start in creating your own integration, our Code Libraries are intended for quick drop-in and immediate production use.
The AGMS Code Library is licensed under the MIT License.
Copyright ©2014 Avant-Garde Marketing Solutions, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Each library has a file that needs to be included in your code to load the library. In this file are a number of static configuration options which need to be customized for your account, preference, and environment in order for the library to function properly.
// AGMS Code Library: PHP Library Configuration - Using Composer
require __DIR__.'/vendor/autoload.php';
\Agms\Utility\Settings::$Setting_Name = 'Setting Value';
// AGMS Code Library: PHP Library Configuration - Without Composer
// If not using Composer, all library files will need to be included
// See init.php in the PHP Library Code Package for an example
require('lib/Agms/Utility/Settings.php');
\Agms\Utility\Settings::$Setting_Name = 'Setting Value';
// Load the Ruby Library
require 'agms'
// The settings can be configured either through a yml file
// or by passing individual values
// Configure through the yml file
Agms::Configuration.init('init.yml')
// Configure through individual values
Agms::Configuration.verbose = True
// Load the Python Library
import 'agms'
// The settings can be configured either though a ini file
// or by passing individual values
// Configure through the ini file
agms.Configuration.init('init.ini')
// Configure through individual values
agms.Configuration.verbose = True
| Setting | Value | Details |
|---|---|---|
| Path_To_Agms_Folder | Absolute location of your AGMS Code Library Folder | In example code, this path is automatically set to be the path of the init file. |
| Debug | true or false | Setting as true will enable trace options and output errors and exceptions for development purposes. DO NOT enable for production use. |
| Verbose | true or false | Setting as true will output raw request/responses for development purposes. DO NOT enable for production use. |
| Api_Username | Your gateway username | Can be overriden at runtime when instantiating AGMS API object. |
| Api_Password | Your gateway password | Can be overriden at runtime when instantiating AGMS API object. |
| Api_Account | Your gateway account number | Can be overriden at runtime when instantiating AGMS API object. |
| Api_Key | Your gateway API key | Can be overriden at runtime when instantiating AGMS API object. |
| Ua_String | Your software/system name and version | Your identifier for what service, website, or app is sending this request, sent and stored with each request. Allows you to track what sent the request and which version of code it was using. i.e. "My Shopping Cart 1.2" |
| Transport_Method | CURL or SOAPCLIENT | Which method will be used to send web service requests and receive responses. |
| Hpp_Template | TEMPLATE_1 or TEMPLATE_2 | Which Hosted Payment Page form Template to use for generating links. If invalid option or no option specified, TEMPLATE_2 will be used. If a specific HPP Generation request has set its own hpp_format parameter, this value will be ignored and overriden by that value. |
| Custom_Name_[1-10] | Your custom field label | Define your own names for custom fields 1-10 to match how you've named them in the gateway for easier code readability. |
| Minimum_Amount | Decimal amount | The minimum amount that all transactional amount fields must meet or be above in order for the library to process them. Does not restrict parameter fields for reporting methods. To help deter fraud or damage resulting from a programming error, set a realistic limit for transaction amounts. |
| Maximum_Amount | Decimal amount | The maximum amount that all transactional amount fields must meet or be above in order for the library to process them. Does not restrict parameter fields for reporting methods. To help deter fraud or damage resulting from a programming error, set a realistic limit for transaction amounts. |
If the library encounters any issue in setup, validation, or web service connection it will throw exceptions to allow these errors to be handled by the developer during runtime. More detail on error codes and messages provided by the gateway service can be found in the SOAP XML API documentation.
| Exception Class | Throw conditions |
|---|---|
| AuthenticationException | Error 401 Unauthorized returned from gateway. |
| AuthorizationException | Error 403 Forbidden returned from gateway. |
| ClientErrorException | The request body is doesn't validate to the WSDL or is empty. Thrown prior to attempting request to gateway. |
| ConfigurationException | The init file is not properly configured, current server environment is not compatible with library, or required dependencies are missing. |
| ConnectionException | An error occurred when trying to communicate with the gateway or the gateway could not be reached. |
| DownForMaintenanceException | Error 503 Service Unavailable returned from gateway. |
| InvalidParameterException | Thrown when a configuration or assignment is attempted to an invalid fieldname or when the value provided is of the wrong type/format. |
| InvalidRequestException | Thrown when an unrecognized gateway op/method request is attempted. |
| NotFoundException | Error 404 Not Found returned from gateway. |
| RequestValidationException | Thrown when final validation of entire request body fails just prior sending request to gateway. |
| ResponseException | Thrown when the gateway communication was successful, but the content of the gateway response indicates error or failure. A declined transaction will not throw an exception. |
| ServerErrorException | Error 500 Server Error returned from gateway. |
| SSLCertificateException | Returned when SSL Certificate validation failed due to mismatch, expiration, or other session error. |
| NoResponseException | Thrown when gateway returns no error code, typically due to an SSL error. |
| UnexpectedException | A malformed response body is returned from server and cannot be parsed properly to determine what went wrong. |
| UpgradeRequiredException | Error 426 Upgrade Required returned from gateway. |