AGMS Gateway Hosted Payment Page API

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.

API Protocol

This API utilizes SOAP XML and supports both SOAP 1.1 and SOAP 1.2.

Hosted Payment Page API: WSDL

Web Service WSDL Lcocation:
https://gateway.agms.com/roxapi/AGMS_HostedPayment.asmx?WSDL

Hosted Payment Page URLs

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]

Hosted Payment Page API: ReturnHostedPaymentSetup Function

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:
https://gateway.agms.com/roxapi/AGMS_HostedPayment.asmx?op=ReturnHostedPaymentSetup

ReturnHostedPaymentSetup Function Reference

This page contains the following details on the ProcessTransaction API function:

  1. Request Fields
  2. Response Fields
  3. Return URL Response Fields

Request Fields

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.

Form Configuration Parameters

Parameter Value Description
GatewayUserName String Always required.
GatewayPassword String Always required.
HPPFormat Integer Specify which template you intend to use, not required as all hashes are interchangeable between templates.
TransactionType sale
auth
safe only
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 Billing Parameters

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.

Parameter Value Description
Tax
Tax_Required
Tax_Visible
Tax_Disabled
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.
Shipping
Shipping_Required
Shipping_Visible
Shipping_Disabled
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.
OrderID
OrderID_Required
OrderID_Visible
OrderID_Disabled
String Can be used to tie transactions back to a record/transaction ID in your system.
PONumber
PONumber_Required
PONumber_Visible
PONumber_Disabled
String Can be used to track Customer PO numbers with the transaction, also used for Level 2 and Level 3 credit card processing qualifications.
FirstName
FirstName_Required
FirstName_Visible
FirstName_Disabled
String Required for all sales and auths.
LastName
LastName_Required
LastName_Visible
LastName_Disabled
String Required for all sales and auths.
Company
Company_Required
Company_Visible
Company_Disabled
String Recommended for all corporate sales and auths.
Address1
Address1_Required
Address1_Visible
Address1_Disabled
String
Address2
Address2_Required
Address2_Visible
Address2_Disabled
String
City
City_Required
City_Visible
City_Disabled
String
State
State_Required
State_Visible
State_Disabled
String
Zip
Zip_Required
Zip_Visible
Zip_Disabled
String
Country
Country_Required
Country_Visible
Country_Disabled
String
Phone
Phone_Required
Phone_Visible
Phone_Disabled
String
Fax
Fax_Required
Fax_Visible
Fax_Disabled
String
EMail
EMail_Required
EMail_Visible
Email_Disabled
String Automatic customer email receipts will be sent to this address, if you have them enabled.
Website
Website_Required
Website_Visible
Website_Disabled
String

Optionable Shipping Parameters

Information for the individual that the product is being shipped to or where the services are being provided. These fields are optional.

Parameter Value Description
ShippingFirstName
ShippingFirstName_Required
ShippingFirstName_Visible
ShippingFirstName_Disabled
String
ShippingLastName
ShippingLastName_Required
ShippingLastName_Visible
ShippingLastName_Disabled
String
ShippingCompany
ShippingCompany_Required
ShippingCompany_Visible
ShippingCompany_Disabled
String
ShippingAddress1
ShippingAddress1_Required
ShippingAddress1_Visible
ShippingAddress1_Disabled
String
ShippingAddress2
ShippingAddress2_Required
ShippingAddress2_Visible
ShippingAddress2_Disabled
String
ShippingCity
ShippingCity_Required
ShippingCity_Visible
ShippingCity_Disabled
String
ShippingState
ShippingState_Required
ShippingState_Visible
ShippingState_Disabled
String
ShippingZip
ShippingZip_Required
ShippingZip_Visible
ShippingZip_Disabled
String
ShippingCountry
ShippingCountry_Required
ShippingCountry_Visible
ShippingCountry_Disabled
String
ShippingEmail
ShippingEmail_Required
ShippingEmail_Visible
ShippingEmail_Disabled
String
ShippingPhone
ShippingPhone_Required
ShippingPhone_Visible
ShippingPhone_Disabled
String
ShippingFax
ShippingFax_Required
ShippingFax_Visible
ShippingFax_Disabled
String
ShippingTrackingNumber_Required
ShippingTrackingNumber
ShippingTrackingNumber_Visible
ShippingTrackingNumber_Disabled
String
ShippingCarrier
ShippingCarrier_Required
ShippingCarrier_Visible
ShippingCarrier_Disabled
ups
fedex
dhl
usps
UPS
Fedex
DHL
USPS

Optionable Custom Parameters

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.

Parameter Value Description
Custom_Field_1
Custom_Field_1_Required
Custom_Field_1_Visible
Custom_Field_1_Disabled
String
Custom_Field_2
Custom_Field_2_Required
Custom_Field_2_Visible
Custom_Field_2_Disabled
String
Custom_Field_3
Custom_Field_3_Required
Custom_Field_3_Visible
Custom_Field_3_Disabled
String
Custom_Field_4
Custom_Field_4_Required
Custom_Field_4_Visible
Custom_Field_4_Disabled
String
Custom_Field_5
Custom_Field_5_Required
Custom_Field_5_Visible
Custom_Field_5_Disabled
String
Custom_Field_6
Custom_Field_6_Required
Custom_Field_6_Visible
Custom_Field_6_Disabled
String
Custom_Field_7
Custom_Field_7_Required
Custom_Field_7_Visible
Custom_Field_7_Disabled
String
Custom_Field_8
Custom_Field_8_Required
Custom_Field_8_Visible
Custom_Field_8_Disabled
String
Custom_Field_9
Custom_Field_9_Required
Custom_Field_9_Visible
Custom_Field_9_Disabled
String
Custom_Field_10
Custom_Field_10_Required
Custom_Field_10_Visible
Custom_Field_10_Disabled
String

Response Fields

The following fields are returned by the HPP API after executing a ReturnHostedPaymentSetup request.

Key Value Description
ReturnHostedPaymentSetupResult String A generated hash which can be used with one of the HPP URLs to load your configured payment page.

Return URL Response Fields

The following fields are posted back to your server if a return_url is provided.

Key Value Description
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.