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.