ProcessTransaction Function Reference

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

1. Request Example
2. Request Fields
3. Response Example
4. Response Fields
5. Status Codes

Request Example

# A sample XML Request



   
      
         
            sale
            creditcard
            20.00
            4111111111111111
            1220
            your username
            your password
         
      
   

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.

Basic Transaction Parameters

Parameter	Value	Description
GatewayUserName	String	Always required.
GatewayPassword	String	Always required.
TransactionType	sale auth capture void refund credit update adjustment safe only	Type of transaction to be processed. Required unless SAFE_Action is specified.
PaymentType	creditcard check	"creditcard" is assumed if no value provided, required for all check/ach transactions.
Amount	Decimal	Amount to be processed, required for all sales and auths.
TipAmount	Decimal	Required for all adjustment transactions. Any amount provided in this field is added to the "amount" value as part of the total charge to the customer.
Tax	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	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.
OrderDescription	String	Order description, appears by default on gateway-generated receipts. Recommended for all sales and auths.
OrderID	String	Can be used to tie transactions back to a record/transaction ID in your system.
PONumber	String	Can be used to track Customer PO numbers with the transaction, also used for Level 2 and Level 3 credit card processing qualifications.
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.
IPAddress	String	IP address of the customer submitting the transaction, highly recommended for ecommerce transactions.

Credit Card Transaction Parameters

Parameter	Value	Description
CCNumber	15-16 Digit Number	Required for all credit card sales and auths unless track data, encrypted data, or SAFE ID is being provided. No spaces or dashes.
CCExpDate	MMYY	Required when sending cc_number.
CVV	3-4 Digit Number	Recommended when sending cc_number for added chargeback protection. NEVER store this number in your system, it is prohibited by PCI.
Track1	String	Track fields are used when sending unencrypted track data from a swiped transaction. This is highly discouraged in favor of using an encrypted swiper out of security and liability concerns.
Track2	String	Track fields are used when sending unencrypted track data from a swiped transaction. This is highly discouraged in favor of using an encrypted swiper out of security and liability concerns.
Track3	String	Track fields are used when sending unencrypted track data from a swiped transaction. This is highly discouraged in favor of using an encrypted swiper out of security and liability concerns.
MagData	String	Encrypted data string provided by an encrypted card reader when swiping a card. This is the officially recommended and supported method of processing swiped transactions. Requires a supported card reader injected with the proper encryption key, contact AGMS for details.
MagHardware	MAGTEK IDTECH	Required when sending MagData.

Check/ACH Transaction Parameters

The following fields are in place to support integrated ACH/check processing which will be available in the near future.

Parameter	Value	Description
CheckName	String	Name of bank account holder, required for all check/ACH sales and auths that are not processed on a SAFE ID.
CheckABA	9 Digit Number	Bank routing number, required for all check/ACH sales and auths that are not processed on a SAFE ID.
CheckAccount	Numeric	Bank account number, required for all check/ACH sales and auths that are not processed on a SAFE ID.
AccountHolderType	business personal	Not required, defaults to personal if omitted.
AccountType	checking savings	Not required, defaults to checking if omitted.
SecCode	PPD WEB TEL CCD	Required for all check/ACH sales and auths that are not processed on a SAFE ID. Fill in the ACH Standard Entry Class (SEC) code that corresponds to how the transaction information was collected.

SAFE Transaction Parameters

Parameter	Value	Description
SAFE_Action	add_safe update_safe delete_safe	Used to execute a SAFE action alongside the transaction or when running a "safe only" transaction. See the Features section regarding Customer SAFE for details.
SAFE_ID	Integer	Required for update_safe or delete_safe to specify to which SAFE record to apply the action.

Customer Billing Parameters

Customer's information as it appears on their method of payment.

Parameter	Value	Description
FirstName	String	Required for all sales and auths.
LastName	String	Required for all sales and auths.
Company	String	Recommended for all corporate sales and auths.
Address1	String
Address2	String
City	String
State	String
Zip	String
Country	String
Phone	String
Fax	String
EMail	String	Automatic customer email receipts will be sent to this address, if you have them enabled.
Website	String

Customer 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	String
ShippingLastName	String
ShippingCompany	String
ShippingAddress1	String
ShippingAddress2	String
ShippingCity	String
ShippingState	String
ShippingZip	String
ShippingCountry	String
ShippingEMail	String
ShippingPhone	String
ShippingFax	String
Tracking_Number	String
Shipping_Carrier	ups fedex dhl usps UPS Fedex DHL USPS

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	String
custom_field_2	String
custom_field_3	String
custom_field_4	String
custom_field_5	String
custom_field_6	String
custom_field_7	String
custom_field_8	String
custom_field_9	String
custom_field_10	String

Response Example

# A sample XML Response



   
      
         
            1
            Approved
            539333
            9999
            Y
            
            M
            
            
            
            
            
            
            
            11111
            
            
         
      
   

Response Fields

The following fields are returned in an array, in this order, by the AGMS Transaction Class after executing a transaction using the process method.

Key	Value	Description
STATUS_CODE	Integer	1 = APPROVAL 2 = DECLINE 10 = VALIDATION ERROR 20 = DATA ERROR OR SYSTEM ERROR 30 = EXCEPTION
STATUS_MSG	String	Text description of the response_code.
TRANS_ID	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.
AUTH_CODE	Integer	Transaction authorization code as provided by the processor.
AVS_CODE	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
AVS_MSG	String	Text description of the avs_message.
CVV2_CODE	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.
CVV2_MSG	String	Text description of the cvv_message.
ORDERID	Integer	The Order ID provided in your transaction request.
SAFE_ID	Integer	If safe_action was used, a safe_id is returned.
FULLRESPONSE	String	Full response from live processing host (development purposes).
POSTSTRING	String	Raw poststring sent to live processing host (development purposes).
BALANCE	Decimal	Not used, reserved for gift card transactions.
GIFTRESPONSE	String	Not used, reserved for gift card transactions.
MERCHANT_ID	Integer	The ID for your AGMS Gateway account.
CUSTOMER_MESSAGE	String	Internal use only.
RRN	String	Internal use only.

Status Codes

Status Code	Details
1 APPROVAL	Transaction executed successfully and was approved.
2 DECLINE	Transaction executed successfully, however it was declined by the processor.
10 VALIDATION ERROR	Possible Status Code 10 messages: GatewayUserName is required. GatewayPassword is required. SAFE_ID is required when performing an update_customer action. CCNumber is required. CCExpDate is not in the required format. CCExpDate should be in the format MMYY. CheckName is required. CheckABA is required. CheckAccount is required. Amount must be numeric and of the format x.xx. Amount is required. If used, Tax must be numeric and of the format x.xx. If used, Shipping must be numeric and of the format x.xx. If used, State must use the 2 character abbreviation. If used, Country must use the 2 character abbreviation. TransactionType must be either 'sale', 'auth', 'capture', 'void', 'refund', 'offline', 'validate', 'update', or 'adjustment' OR SAFE_Action must be 'add_safe', 'update_safe', or 'delete_safe'. TransactionID is required for a refund. TransactionID is required for a update. TransactionID is required for a void. TransactionID is required for a capture. If used, Shipping_Carrier must be either 'ups', 'fedex', 'dhl', 'usps', 'UPS', 'Fedex', 'DHL', or 'USPS'. SAFE_ID is required.
20 DATA ERROR OR SYSTEM ERROR	A data or system error occurred at the processing network, see status message for details.
30 EXCEPTION	A fatal error occurred on the gateway itself and an exception was thrown when attempting to run the transaction, see the status message for details. If you encounter a status code 30, contact AGMS with details of the issue for assistance.

TransactionAPI Function Reference

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

1. Request Example
2. Request Fields
3. Response Example
4. Response Fields
5. Status Codes

Request Example

# A sample XML Request



   
      
         
            2014-09-24
            2015-11-09
            your username
            your password
            1009999
            abcdef0123456789abcdef0123456789abcdef012345678
         
      
   

Request Fields

The following fields can be passed into the AGMS Transaction API to query for a list of transactions and their full details. Please note that all fields are case sensitive.

Parameter	Value	Description
GatewayUserName	String	Always required.
GatewayPassword	String	Always required.
AccountNumber	String	Always required.
TransactionAPIKey	String	Always required.
StartDate	YYYY-MM-DD	Beginning of date range to search.
EndDate	YYYY-MM-DD	End of date range to search.
Amount	Decimal	Specific amount processed.
TransactionType	sale auth capture void refund update adjustment safe only	Type of transaction processed.
PaymentType	creditcard check
FirstName	String
LastName	String
Company	String
Address	String
City	String
State	String
Zip	String
Country	String
Phone	String
Email	String
Safe_ID	Numeric
TransactionID	Numeric
ProcessorID	Numeric
CreditCardLast4	Numeric

Response Example

# A sample XML Response



   
      
         
            
               
                  434685
                  sale
                  creditcard
                  20
                  2.00
                  3.00
                  big transaction detail test
                  1AFSS224
                  256645
                  4****1111
                  1220
                  Joe
                  Smith
                  Smith Enterprises
                  125 Main St
                  Suite C
                  Blaine
                  MN
                  55443
                  US
                  222-222-2222
                  333-333-3333
                  joe@smith.com
                  www.smith.com
                  Joe
                  Smith
                  Smith Enterprises
                  125 Main St
                  Suite C
                  Blaine
                  MN
                  55443
                  US
                  joe@smith.com
                  1Z223452433282822
                  ups
                  128.101.101.101
                  custom 1
                  custom 2
                  custom 3
                  custom 4
                  custom 5
                  custom 6
                  custom 7
                  custom 8
                  custom 9
                  custom 10
                  1
                  Approved
                  434685
                  9999
                  11/26/2014 9:18:56 AM
                  11/26/2014 9:18:56 AM
                  11/26/2014 9:18:57 AM
                  agmsdemo
                  LogResponse
                  AGMS PHP Library Sample Code (AGMS PHP Lib 0.5.6)
                  True
                  Visa
               
               
                  434684
                  sale
                  creditcard
                  0.01
                  4****1111
                  1220
                  2
                  Declined
                  434684
                  1234
                  11/26/2014 9:18:56 AM
                  11/26/2014 9:18:56 AM
                  11/26/2014 9:18:56 AM
                  agmsdemo
                  LogResponse
                  AGMS PHP Library Sample Code (AGMS PHP Lib 0.5.6)
               
               
                  434683
                  sale
                  creditcard
                  20
                  4****1111
                  1220
                  1
                  Approved
                  434683
                  9999
                  11/26/2014 9:18:55 AM
                  11/26/2014 9:18:55 AM
                  11/26/2014 9:18:55 AM
                  agmsdemo
                  LogResponse
                  AGMS PHP Library Sample Code (AGMS PHP Lib 0.5.6)
                  False
               
            
         
      
   

Response Fields

The following fields are returned in an array, in this order, by the AGMS Transaction Class after executing a transaction using the process method.

Key	Value	Description
id	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.
transactiontype	String	The type of transaction processed.
paymenttype	String	The type of payment processed.
amount	String	The amount of the transaction processed.
responsestatuscode	Integer	1 = APPROVAL 2 = DECLINE 10 = VALIDATION ERROR 20 = DATA ERROR OR SYSTEM ERROR 30 = EXCEPTION
responsestatusmsg	String	Text description of the response_code.
responsetransid	String	Same as Transaction ID.
responseauthcode	Integer	Transaction authorization code provided by the processor.
transactiondate	String	Date that the transaction was settled.
createdate	String	Date that the transaction was created.
moddate	String	Date that the transaction was last edited.
createuser	String	Gateway user who created the transaction.
moduser	Integer	Last gateway user to edit the transaction.
useragent	Integer	User agent string from the program, app, website, or system used to submit the transaction.
cardpresent	Boolean	If True, the transaction was processed as a swiped card present transaction. If false, the transaction was keyed (or ecommerce).

Optional Transaction Data Fields

The following fields are also returned when the transaction contains them. If a field was not populated for that transaction, it will not be included in the response.

Parameter	Value	Description
orderdescription	String
orderid	String
tipamount	Decimal
tax	Decimal
shipping	Decimal
ponumber	String
ipaddress	String	As provided with the transaction submission.
ccnumber	15-16 Digit Number	Truncated to only show the first and last 4 digits.
ccexpdate	MMYY
safeaction	add_safe update_safe delete_safe
responsesafeid	Integer
checkname	String
checkaba	String
checkaccount	String
accountholdertype	String
accounttype	String
seccode	String
firstname	String
lastname	String
company	String
address1	String
address2	String
city	String
state	String
zip	String
country	String
phone	String
fax	String
email	String
website	String
shippingfirstname	String
shippinglastname	String
shippingcompany	String
shippingaddress1	String
shippingaddress2	String
shippingcity	String
shippingstate	String
shippingzip	String
shippingcountry	String
shippingemail	String
shippingphone	String
ShippingFax	String
trackingnumber	String
shippingcarrier	ups fedex dhl usps UPS Fedex DHL USPS
receipttype	String
customfield1	String
customfield2	String
customfield3	String
customfield4	String
customfield5	String
customfield6	String
customfield7	String
customfield8	String
customfield9	String
customfield10	String

Status Codes

Status Code	Details
1 APPROVAL	Request was successful.
10 VALIDATION ERROR	Possible Status Code 10 messages: GatewayUsername is required. GatewayPassword is required. AccountNumber is required. TransactionAPIKey is required. Amount must be numeric and of the format x.xx. Amount is required. TransactionType must be either 'sale', 'auth', 'capture', 'void', 'refund', 'offline', 'validate', 'update', or 'adjustment' OR SAFE_Action must be 'add_safe', 'update_safe', or 'delete_safe'.
30 EXCEPTION	A fatal error occurred on the gateway itself and an exception was thrown when attempting to run the transaction, see the status message for details. If you encounter a status code 30, contact AGMS with details of the issue for assistance.