This section explains how to use the AGMS Gateway's Hosted Payment Page API, which allows you to generate completely customized payment pages hosted on the AGMS Gateway.
This API utilizes SOAP XML and supports both SOAP 1.1 and SOAP 1.2.
Web Service WSDL Lcocation:
Hosted Payment Page Location - Template 1:
https://gateway.agms.com/HostedPaymentForm/HostedPaymentPage.aspx?hash=[Your HPP Hash]
Hosted Payment Page Location - Template 2:
https://gateway.agms.com/HostedPaymentForm/HostedPaymentPage2.aspx?hash=[Your HPP Hash]
The ReturnHostedPaymentSetup function is used to generate a unique HPP hash which references the unique configuration of your page. Sending this hash to the dedicated HPP URL will display your specific form for use by a customer.
Web Service URL:
This page contains the following details on the ProcessTransaction API function:
The following fields can be passed into the AGMS Transaction API to process a transaction. For more information on what fields are required for a specific transaction, review Transaction Types. Please note that all fields are case sensitive.
|HPPFormat||Integer||Specify which template you intend to use, not required as all hashes are interchangeable between templates.|
|Type of transaction to be processed.|
|ACHEnabled||Boolean||Whether or not to enable check/ACH as an available payment method.|
|OrderDescription||String||Displays on the page next to the amount to describe what the payment is for.|
|Amount||Decimal||Amount to be processed, required for all sales and auths unless a SAFE ID is provided or the form is a donation form.|
|Donation||Boolean||If true, the form is treated as a donation form where the amount is editable by the user. If an Amount value is provided, that value will be the default value of the amount field when the page loads.|
|RetURL||String||The URL to immediately return the user to after the transaction is complete. The user will be redirected here immediately, with no pause on any other page. If this URL is not provided, a generic thank-you page will be displayed showing the transaction details. It is recommended that the URL provided is an https URL, otherwise the user's browser may trigger an unsecure content warning.|
|AutoSAFE||1 or 0||If 1 is passed, the form will automatically tokenize the customer and payment information into the Customer SAFE with no ability for the customer to disable that behavior.|
|UsageCount||Integer||The number of times that the form can be successfully used before no longer being available. Leave blank to allow the form to be used an unlimited number of times.|
|StartDate||YYYY-MM-DD||The date to automatically enable the form.|
|StartTime||HH:MM:SS or HH:MM||The time of day to automatically enable the form, in 24h format. Times are in local timezone as configured by administrator in the gateway settings.|
|EndDate||YYYY-MM-DD||The date to automatically disable the form.|
|EndTime||HH:MM:SS or HH:MM||The time of day to automatically disable the form, in 24h format. Times are in local timezone as configured by administrator in the gateway settings.|
|ProcessorID||Integer||If multiple processing accounts are configured in the same gateway account, use this field to specify which account to use. If gateway is configured for only one processing account, this field is not required.|
|SAFE_ID||Integer||If specified, user doesn't need to enter their payment info and stored information is used.|
|SupressAutoSAFE||1 or 0||If 1 is passed, HPP Format 1 will not show a checkbox allowing the customer to save their information in the Customer SAFE. By default, template 1 will show this checkbox.|
Optionable parameters can have a value set, and can also be set as Visible, Required, or Disabled. The visible parameter displays the field to the user, required forces the user to complete the field in order to submit the transaction, and disabled controls whether the form is editable or not.
To pass data into the form as hidden values which are then stored with the transaction behind-the-scenes, send a value but leave Visible as empty or false.
The Value column represents the type of input expected for the first listed value field. Fields ending in "_Required", "_Visible", and "_Disabled" are all Boolean fields.
|Decimal||The amount of the transaction that was sales tax. The tax_amount is not added in to the total amount charged to the cardholder, this field is informational only and is also used for Level 2 and Level 3 processing qualifications.|
|Decimal||The amount of the transaction that was shipping. The shipping_amount is not added in to the total amount charged to the cardholder, this field is informational only.|
|String||Can be used to tie transactions back to a record/transaction ID in your system.|
|String||Can be used to track Customer PO numbers with the transaction, also used for Level 2 and Level 3 credit card processing qualifications.|
|String||Required for all sales and auths.|
|String||Required for all sales and auths.|
|String||Recommended for all corporate sales and auths.|
|String||Automatic customer email receipts will be sent to this address, if you have them enabled.|
Information for the individual that the product is being shipped to or where the services are being provided. These fields are optional.
Custom fields are fields that can be used by you to store any additional parameters that you need. Custom fields can be custom labeled in the gateway settings, so instead of "Custom Field 1" it could display as "Shirt Size". The parameter names below are the default generic values, however you can also define custom field aliases, such as "shirt_size" in place of "custom_field_1" in the init.php configuration.
The following fields are returned by the HPP API after executing a ReturnHostedPaymentSetup request.
|ReturnHostedPaymentSetupResult||String||A generated hash which can be used with one of the HPP URLs to load your configured payment page.|
The following fields are posted back to your server if a return_url is provided.
|authcode||Integer||Transaction authorization code as provided by the processor.|
|avsmsg||String||Text description of the avs code.|
|transid||Integer||A unique ID generated by the gateway for this transaction. This should be stored in your system along with your local transaction record for future reconciliation with gateway records.|
|authmsg||String||Text description of the authorization response.|
|statuscode||Integer||1 = APPROVAL
2 = DECLINE
10 = VALIDATION ERROR
20 = DATA ERROR OR SYSTEM ERROR
30 = EXCEPTION
|avscode||String||Y, D, or M = Exact 5 character numeric zip match
A or B = Address (street number) match only
W = 9 character numeric zip match only
Z, P, or L = 5 character numeric zip match only
N or C = No address or zip match
U = Address unavailable
G or I = Non-U.S. issuer does not participate in AVS program
R = Issuer system unavailable
E = Not a mail/phone/ecommerce order
S = AVS service not supported
0, O, or B = AVS not available
|cvv2code||String||M = CVV2/CVC2 Match
N = CVV2/CVC2 No Match
P = Not Processed
S = Merchant has indicated that CVV2/CVC2 is not present on card
U = Issuer is not certified and/or has not provided Visa encryption keys.
|cvv2msg||String||Text description of the cvv2code.|
|safeid||Integer||If safe_action was used, a safeid is returned.|
|statusmsg||String||Text description of the statuscode.|