Auth.net (AIM) emulation API **DEPRECATED**
- Jed Danner
- Sarah Geren
- Daniel Ghirelli
Auth.net has deprecated the AIM implementation part of their service, and as such we have deprecated this API as well. However, there are no plans to discontinue this API service for any integrated applications. We do not have any plans at this time to provide an emulated environment based on Auth.net's newer expanded API end-points. For any new integrations we suggest using our HTTP API, REST API, and SOAP Web Service
AIM Implementation
To implement AIM, a developer would design a script that does the following:
- Securely obtains all of the information needed to process a transaction.
- Initiates a secure HTTPS post from their server to:
https://secure.gotobilling.com/gateway/transact.php
- Receives the response from the gateway and processes the response to display the appropriate result to the end user.
Minimum Requirements for AIM
The following is the minimum set of NAME/VALUE pairs that should be submitted to the gateway when using AIM for a credit card transaction
| Field Name | Field Value |
|---|---|
| x_version | 3.1 |
| x_delim_data | True |
| x_relay_response | False |
| x_login | API login ID (Merchant ID) for the payment gateway account |
| x_tran_key | Transaction key or Gateway Pin |
| x_amount | Amount of purchase inclusive of tax |
| x_card_num | Card number |
| x_exp_date | Card expiration date |
| x_type | Type of transaction (AUTH_CAPTURE, AUTH_ONLY, CAPTURE_ONLY, CREDIT, VOID, PRIOR_AUTH_CAPTURE) |
The following is the minimum set of NAME/VALUE pairs that should be submitted to the gateway when using AIM for an eCheck transaction.
| Field Name | Field Value |
|---|---|
| x_version | 3.1 |
| x_delim_data | True |
| x_relay_response | False |
| x_login | API login ID (Merchant ID) for the payment gateway account |
| x_tran_key | Transaction key or Gateway Pin |
| x_amount | Amount of purchase inclusive of tax |
| x_bank_aba_code | ABA routing number |
| x_bank_acct_num | Bank Account Number |
| x_bank_acct_type | Type of Account – Checking, Business Checking or Savings |
| x_bank_name | Name of bank at which account is maintained |
| x_bank_acct_name | Name under which the account is maintained at the bank |
| x_type | Type of transaction (AUTH_CAPTURE, CREDIT) |
| x_echeck_type | Type of eCheck transaction (ARC, PPD, TEL, WEB) |
| x_bank_check_number | The check number (required only for ARC eCheck transaction types) |
Standard Transaction Submission API for AIM
The Standard Transaction Submission API defines the information that can be submitted to the gateway for real-time transaction processing. The API consists of a set of fields that are required for each transaction, and a set of fields that are optional. Under the API, the gateway accepts a NAME/ VALUE pair. The NAME is the field name and indicates to the gateway what information is being submitted. VALUE contains the content of the field.
The following tables contain the data fields that may be submitted to the system with any transaction. The fields are grouped logically in the tables, based on the information submitted. Each table contains the following information:
- Field – Name of the parameter that may be submitted on a transaction.
- Required – Indicates whether the field is required on a transaction. If Conditional, indicates that the field is required based on the existence or value of another field. In cases where a dependency exists, an explanation is provided.
- Value – Lists the possible values that may be submitted for the field. In cases where a format is validated, an explanation is provided.
- Max Length – Indicates the maximum number of characters that may be supplied for each field.
- Description – Provides additional details on how the field is used.
Merchant Account Information
Merchant ID and PIN **DEPRECATED**
For more information on obtaining your PIN, see: Generating a Merchant Gateway Pin
API Access Key Pair
For more information on obtaining an API access key, see: Managing API Access Keys
| Field | Required | Description |
|---|---|---|
| x_access_key | Required | Generated API access key |
| x_access_key_secret | Required | Key secret associated with the given access_key |
The following fields are optional.
| Field Name | Required | Value | Max Length | Description |
|---|---|---|---|---|
| x_test_request | Optional | TRUE, FALSE | 5 | Indicates whether the transaction should be processed as a test transaction. Please refer to Appendix G for further information on this field. |
| source_description | Optional | Varies by merchant | 50 | Used in issue tracking, this is the name and version of the application that is using the service. |
| module_description | Optional | Varies by merchant | 10 | Used in issue tracking, this is auxiliary information pertaining to the merchant such as OS, mobile phone number, device ID, etc . |
Gateway Response Configuration
The following fields determine how a transaction response will be returned once a transaction is submitted to the system.
| FIELD | REQUIRED | VALUE | MAX LENGTH | DESCRIPTION |
|---|---|---|---|---|
| x_delim_data | Required | TRUE | 5 | In order to receive a delimited response from the gateway, this field has to be submitted with a value of TRUE or the merchant has to configure a delimited response through the Merchant Interface. |
| x_relay_response | Required | FALSE | N/A | Indicates whether a relay response is desired. As all AIM transactions are direct response, a value of FALSE is required. |
Customer Name and Billing Address
The customer billing address fields listed below contain information on the customer billing address associated with each transaction.
| FIELD | REQUIRED | VALUE | MAX LENGTH | DESCRIPTION |
|---|---|---|---|---|
| x_first_name | Optional | Any string | 50 | Contains the first name of the customer associated with the billing address for the transaction. |
| x_last_name | Optional | Any string | 50 | Contains the last name of the customer associated with the billing address for the transaction. |
| x_company | Optional | Any string | 50 | Contains the company name associated with the billing address for the transaction. |
| x_address | Optional | Any string | 60 | Contains the address of the customer associated with the billing address for the transaction. |
| x_city | Optional | Any string | 40 | Contains the city of the customer associated with the billing address for the transaction. |
| x_state | Optional | If passed, the value will be verified. Any valid two- digit state code or full state name | 40 | Contains the state of the customer associated with the billing address for the transaction. |
| x_zip | Optional | Any string | 20 | Contains the zip of the customer associated with the billing address for the transaction. |
| x_country | Optional | If passed, the value will be verified. Any valid two- digit country code or full country name (spelled in English) | 60 | Contains the country of the customer associated with the billing address for the transaction. |
| x_phone | Optional | Any string. Recommended format is 3334445555 | 25 | Contains the phone number of the customer associated with the billing address for the transaction. |
| x_fax | Optional | Any string. Recommended format is 3334445555 | 25 | Contains the fax number of the customer associated with the billing address for the transaction. |
| x_display_as | Optional | company, contact | 10 | Contains a value for how the customer account name should be displayed. The default is contact which displays first name and last name. Change to company and include a value in company name to display the customer account name as the company name rather than first name and last name. |
Additional Customer Data
Merchants may provide additional customer information with a transaction, based on their respective requirements.
| FIELD | REQUIRED | VALUE | MAX LENGTH | DESCRIPTION |
|---|---|---|---|---|
| x_cust_id | Optional | Any string | 20 | Unique identifier to represent the customer associated with the transaction. |
| x_customer_ip | Optional | Required format is 255.255.255.255. If this value is not passed, it will default to 255.255.255.255 | 15 | IP address of the customer initiating the transaction. |
| x_customer_tax_id | Optional | digits/numbersonly | 9 | Tax ID or SSN of the customer initiating the transaction. |
Email Settings
The following fields describe how and when emails will be sent when transactions are processed by the system.
| FIELD | REQUIRED | VALUE | MAX LENGTH | DESCRIPTION |
|---|---|---|---|---|
| x_email | Optional | Any valid email address | 255 | Email address to which the customer’s copy of the confirmation email is sent. No email will be sent to the customer if the email address does not meet standard email format checks. |
| x_email_customer | Optional | TRUE, FALSE | 5 | Indicates whether a confirmation email should be sent to the customer. If no value is submitted, system will default to the value configured in the Merchant Interface. |
| x_merchant_email | Optional | Any valid address | 255 | Email address to which the merchant’s copy of the customer confirmation email should be sent. If a value is submitted, an email will be sent to this address as well as the address(es) configured in the Merchant Interface. |
Invoice Information
Based on their respective requirements, merchants may submit invoice information with a transaction. Two invoice fields are provided in the gateway API.
| FIELD | REQUIRED | VALUE | MAX LENGTH | DESCRIPTION |
|---|---|---|---|---|
| x_invoice_num | Optional | Any string | 20 | Merchant-assigned invoice number. |
| x_description | Optional | Any string | 255 | Description of the transaction. |
Transaction Data
The following fields contain transaction-specific information such as amount, payment method, and transaction type.
| FIELD | REQUIRED | VALUE | MAX LENGTH | DESCRIPTION |
|---|---|---|---|---|
| x_amount | Required | Any amount | 15 | Total value to be charged or credited inclusive of tax. |
| x_process_date | Optional | Numeric | 8 | Date on which the transaction is to be processed. If no date is given, the transaction will default to the date it is submitted on. Format:YYYYMMDD |
| x_occurrence_type | Optional | single, week, biweek, month, bimonth, quarter, semiannual, annual | 10 | Selects the type of occurrence the transaction should have. Defaults to single if none is specified. |
| x_allow_recurring | Optional | TRUE,FALSE | 5 | Offers options to the paying customer to select if the payment should be recurring, what schedule to charge recurring payments on, and the maximum number of payments to collect. |
| x_occurrence_number | Optional | Numeric | 3 | Selects the amount of occurrences a recurring transaction should have. Defaults to indefinite if none is specified. |
| x_currency_code | Optional | Valid code | 3 | Currency of the transaction amount. If left blank, this value will default to the value specified in the Merchant Interface. See Appendix I for other values. |
| x_method | Required | CC, ECHECK | N/A | Indicates the method of payment for the transaction being sent to the system. If left blank, this value will default to CC. |
| x_type | Required | AUTH_CAPTURE, AUTH_ONLY, CAPTURE_ONLY, CREDIT, VOID, PRIOR_AUTH_CAPTURE, AVSONLY | N/A | Indicates the type of transaction. If the value in the field does not match any of the values stated, the transaction will be rejected. If no value is submitted in this field, the gateway will process the transaction as an AUTH_CAPTURE |
| x_bank_aba_code | Conditional. Required if x_method = ECHECK. | Valid routing number | 9 | Routing number of a bank for eCheck transactions. |
| x_bank_acct_num | Conditional. Required if x_method = ECHECK | Valid account number | 20 | Checking or savings account number. |
| x_bank_acct_type | Conditional. Required if x_method = ECHECK | CHECKING, BUSINESSCHECKING, SAVINGS | 16 | Describes the type of bank account; if no value is provided, default is set to CHECKING. |
| x_bank_name | Conditional. Required if x_method = ECHECK | Valid bank name | 50 | Contains the name of the customer’s financial institution. |
| x_bank_acct_name | Conditional. Required if x_method = ECHECK | Alphanumeric | 50 | Is the customer’s name as it appears on their bank account. |
| x_echeck_type | Conditional. Required if x_method = ECHECK | ARC, PPD, TEL, WEB | 3 | Indicates the type of eCheck payment request. |
| x_bank_check_number | Conditional; Required if x_echeck_type = ARC or BOC. | Alpha-numeric | 15 | The check number on the customer’s paper check. See Appendix B for details on eCheck types. |
| x_card_name | Optional | Valid Name | 22 | Cardholder Name. |
| x_card_num | Conditional; Required if x_method = CC; | Numeric credit card number | 22 | Credit card number. |
| x_exp_date | Conditional; Required if x_method = CC | MMYY | 4 | Contains the date on which the credit card expires. |
| x_card_code | Optional | Valid CVV2, CVC2 or CID value | 4 | The three or four-digit number on the back of a credit card (on front for American Express). |
| x_trans_id | Conditional; Required if x_type = CREDIT, VOID, or PRIOR_AUTH_CAPTURE | Valid transaction ID | 10 | ID of a transaction previously authorized by the gateway. |
| x_auth_code | Conditional; Required if x_type = CAPTURE_ONLY | Valid authorization code | 6 | Authorization code for a previous transaction not authorized on the gateway that is being submitted for capture. |
| x_authentication_indicator | Optional; Conditional; Required only for AUTH_ONLY and AUTH_CAPTURE transactions processed through cardholder authentication programs. When submitted with other transaction types, this value is ignored. | Valid ECI or UCAF indicator value (obtained by the merchant after the authentication process). | N/A | The commerce indicator (ECI) value for a Visa transaction; or the universal cardholder authentication field indicator (UCAF for a MasterCard transaction. This field is currently supported through FDC Nashville and Vital. This field is also supported by Wells Fargo SecureSource for Visa transactions only. |
| x_cardholder_authentication_value | Optional; Required only for AUTH_ONLY and AUTH_CAPTURE transactions processed through cardholder authentication programs. When submitted with other transaction types, this value is ignored. | Valid CAVV, AVV, or UCAF value (obtained by the merchant after the authentication process). | N/A | The cardholder authentication verification value (CAVV) for a Visa transaction; or account holder authentication value (AVV)/ universal cardholder authentication field (UCAF) for a MasterCard transaction. This field is currently supported through FDC Nashville and Vital. This field is also supported by Wells Fargo SecureSource for Visa transactions only. |
| x_track_data | Optional | For swiped cards this is the track1 and track2 data. Used in providing proof of a swiped card present transaction, which can allow for lower rates when processing. May be track1, track2, or a combined track1/track2 read. Typically recommended to pass the data to GoToBilling exactly as received (track1/track2 combined). Should not be specified if referencing a ticket id. GoToBilling strictly validates the formatting of trackdata. If sending a combined track1/track2, you must use standardized framing characters. Track 1 must begin with % and end with ? Track 2 must begin with ; and end with ? Track 1 must always begin with a capital B (after the start sentinel if provided). The framing characters are optional if only sending track1 or track2. GoToBilling does not allow leading, trailing or separating whitespace or LRC characters in the trackdata format. | ||
| x_reference_id | Optional | Alphanumeric | 32 | Unique reference number for the transaction. Will be passed back in the response once the transaction has processed. |
| x_ach_verification | Optional | 'true','false' | 5 | Flag indicating whether or not to pass the ACH account information through the verification network. If verification is enabled and the verification fails, the transaction will be declined. Defaults to 'false'. |
| x_token | Optional | Alphanumeric, Valid 3DS Payment Token | N/A | A valid 3DS (3D Secure) payment token, issued by a trusted provider offering payment tokenization, must be presented in this field. The x_token field value must be included along with the other conditionally required fields for x_method = CC (x_card_num and x_exp_date). |
Level 2 Data
The system supports Level 2 transaction data by providing the following fields as part of the transaction submission API. The tax, freight, and duty fields allow a delimited string for submitting extended information.
| FIELD | REQUIRED | VALUE | MAX LENGTH | DESCRIPTION |
|---|---|---|---|---|
| x_po_num | Optional | Any string | 25 | Contains the purchase order number. |
| x_tax | Optional | Any valid tax amount | N/A | Contains the sales tax amount OR delimited tax information including the sales tax name, description, and amount. The dollar sign ($) is not allowed when submitting delimited information. |
Gateway Response API
This section describes the response returned by the gateway when a merchant server submits a transaction for processing. The response is a set of fields that give merchants information about the status of a transaction. The fields will be comma delimited by default or delimited by the character specified by the merchant. The merchant server can parse this data and determine the message to display to the customer.
Fields in the Gateway Response
The following table indicates the order of the fields returned in the AIM response from the gateway to the merchant server.
| POSITION IN RESPONSE | FIELD NAME OF VALUE IN RESPONSE | DESCRIPTION |
|---|---|---|
| 1 | Response Code | Indicates the result of the transaction:
|
| 2 | Response Subcode | A code used by the system for internal transaction tracking. |
| 3 | Response Reason Code | A code representing more details about the result of the transaction. |
| 4 | Response Reason Text | Brief description of the result, which corresponds with the Response Reason Code. |
| 5 | Approval Code | For credit cards this will be the six-digit alphanumeric authorization or approval code. For ECHECK verification transactions this will be the AUTH NUM of the verification request, if approved. |
| 6 | AVS Result Code | Indicates the result of Address Verification System (AVS) checks:
|
| 7 | Transaction ID | This number identifies the transaction in the system and can be used to submit a modification of this transaction at a later time, such as voiding, crediting or capturing the transaction. |
| 8 | Invoice Number | Echoed from input value for x_invoice_num. |
| 9 | Description | Echoed from input value for x_description. |
| 10 | Amount | Echoed from input value for x_amount. |
| 11 | Method | Echoed from input value for x_method. |
| 12 | Transaction Type | Echoed from input value for x_type. |
| 13 | Customer ID | Echoed from input value for x_cust_id. |
| 14 | Cardholder First Name | Echoed from input value for x_first_name. |
| 15 | Cardholder Last Name | Echoed from input value for x_last_name. |
| 16 | Company | Echoed from input value for x_company. |
| 17 | Billing Address | Echoed from input value for x_address. |
| 18 | City | Echoed from input value for x_city. |
| 19 | State | Echoed from input value for x_state. |
| 20 | Zip | Echoed from input value for x_zip. |
| 21 | Country | Echoed from input value for x_country. |
| 22 | Phone | Echoed from input value for x_phone. |
| 23 | Fax | Echoed from input value for x_fax. |
| 24 | Echoed from input value for x_email. | |
| 25 | Ship to First Name | Echoed from input value for x_ship_to_first_name. |
| 26 | Ship to Last Name | Echoed from input value for x_ship_to_last_name. |
| 27 | Ship to Company | Echoed from input value for x_ship_to_company. |
| 28 | Ship to Address | Echoed from input value for x_ship_to_address. |
| 29 | Ship to City | Echoed from input value for x_ship_to_city. |
| 30 | Ship to State | Echoed from input value for x_ship_to_state. |
| 31 | Ship to Zip | Echoed from input value for x_ship_to_zip. |
| 32 | Ship to Country | Echoed from input value for x_ship_to_country. |
| 33 | Tax Amount | Echoed from input value for x_tax. |
| 34 | Duty Amount | Echoed from input value for x_duty. |
| 35 | Freight Amount | Echoed from input value for x_freight. |
| 36 | Tax Exempt Flag | Echoed from input value for x_tax_exempt. |
| 37 | PO Number | Echoed from input value for x_po_num. |
| 38 | MD5 Hash | System-generated hash that may be validated by the merchant to authenticate a transaction response received from the gateway. |
| 39 | Card Code (CVV2/CVC2/CID) | Indicates the results of Card Code verification:
|
| 40 | Cardholder Authentication Verification Value - (CAVV) Response Code | Indicates the results of cardholder authentication verification:
incomplete
error
issued card/non-U.S acquirer)
issued card/non-U.S. acquirer)
(U.S.-issued card/non-U.S. acquirer)
(U.S.-issued card/non-U.S. acquirer)
shift |
| 41 | Card Number | If transaction is credit card based this field contains the masked version of the submitted credit card number |
| 42 | Card Type | If transaction is credit card based this field contains the credit card type |
| 43 | Split Tender Id | Echoed from input value for x_split_tender_id. |
| 44 | x_requested_amount | Originally requested transaction amount |
| 45 | x_balance_on_card | Echoed from input value for x_balance_on_card. |
| 46 | x_exp_date | Echoed from input value for x_exp_date. |
| 47 | x_reference_id | Echoed from input value for x_reference_id. |
Response Reason Codes & Response Reason Text
| RESPONSE CODE | RESPONSE REASON CODE | RESPONSE REASON TEXT | NOTES | |
|---|---|---|---|---|
| 1 | 1 | This transaction has been approved. | ||
| 2 | 2 | This transaction has been declined. | ||
| 2 | 3 | This transaction has been declined. | ||
| 2 | 4 | This transaction has been declined. | The code returned from the processor indicating that the card used needs to be picked up. | |
| 3 | 5 | A valid amount is required. | The value submitted in the amount field did not pass validation for a number. | |
| 3 | 6 | The credit card number is invalid. | ||
| 3 | 7 | The credit card expiration date is invalid. | The format of the date submitted was incorrect. | |
| 3 | 8 | The credit card has expired. | ||
| 3 | 9 | The ABA code is invalid. | The value submitted in the x_bank_aba_code field did not pass validation or was not for a valid financial institution. | |
| 3 | 10 | The account number is invalid. | The value submitted in the x_bank_acct_num field did not pass validation. | |
| 3 | 11 | A duplicate transaction has been submitted. | A transaction with identical amount and credit card information was submitted two minutes prior. | |
| 3 | 12 | An authorization code is required but not present. | A transaction that required x_auth_code to be present was submitted without a value. | |
| 3 | 13 | The merchant API login ID is invalid or the account is inactive. | ||
| 3 | 14 | The Referrer or Relay Response URL is invalid. | The Relay Response or Referrer URL does not match the merchant’s configured value(s) or is absent. Applicable only to SIM and WebLink APIs. | |
| 3 | 15 | The transaction ID is invalid. | The transaction ID value is non-numeric or was not present for a transaction that requires it (i.e., VOID, PRIOR_AUTH_CAPTURE, and CREDIT). | |
| 3 | 16 | The transaction was not found. | The transaction ID sent in was properly formatted but the gateway had no record of the transaction. | |
| 3 | 17 | The merchant does not accept this type of credit card. | The merchant was not configured to accept the credit card submitted in the transaction. | |
| 3 | 18 | ACH transactions are not accepted by this merchant. | The merchant does not accept electronic checks. | |
| 3 | 19 | An error occurred during processing. Please try again in 5 minutes. | ||
| 3 | 20 | An error occurred during processing. Please try again in 5 minutes. | ||
| 3 | 21 | An error occurred during processing. Please try again in 5 minutes. | ||
| 3 | 22 | An error occurred during processing. Please try again in 5 minutes. | ||
| 3 | 23 | An error occurred during processing. Please try again in 5 minutes. | ||
| 3 | 24 | The Nova Bank Number or Terminal ID is incorrect. Call Merchant Service Provider. | ||
| 3 | 25 | An error occurred during processing. Please try again in 5 minutes. | ||
| 3 | 26 | An error occurred during processing. Please try again in 5 minutes. | ||
| 2 | 27 | The transaction resulted in an AVS mismatch. The address provided does not match billing address of cardholder. | ||
| 3 | 28 | The merchant does not accept this type of credit card. The Merchant ID at the processor was not configured to accept this card type. | ||
| 3 | 29 | The PaymentTech identification numbers are incorrect. Call Merchant Service Provider. | ||
| 3 | 30 | The configuration with the processor is invalid. Call Merchant Service Provider. | ||
| 3 | 31 | The FDC Merchant ID or Terminal ID is incorrect. Call Merchant Service Provider. | The merchant was incorrectly set up at the processor. | |
| 3 | 32 | This reason code is reserved or not applicable to this API. | ||
| 3 | 33 | FIELD cannot be left blank. | The word FIELD will be replaced by an actual field name. This error indicates that a field the merchant specified as required was not filled in. | |
| 3 | 34 | The VITAL identification numbers are incorrect. Call Merchant Service Provider. | The merchant was incorrectly set up at the processor. | |
| 3 | 35 | An error occurred during processing. Call Merchant Service Provider. | The merchant was incorrectly set up at the processor. | |
| 3 | 36 | The authorization was approved, but settlement failed. | ||
| 3 | 37 | The credit card number is invalid. | ||
| 3 | 38 | The Global Payment System identification numbers are incorrect. Call Merchant Service Provider. | The merchant was incorrectly set up at the processor. | |
| 3 | 39 | The supplied currency code is either invalid, not supported, not allowed for this merchant or doesn’t have an exchange rate. | ||
| 3 | 40 | This transaction must be encrypted. | ||
| 2 | 41 | This transaction has been declined. | Only merchants set up for the FraudScreen service would receive this decline. This code will be returned if a given transaction’s fraud score is higher than the threshold set by the merchant. | |
| 3 | 42 | There is missing or invalid information in a required field. | This is applicable only to merchants processing through the Wells Fargo SecureSource product who have requirements for transaction submission that are different from merchants not processing through Wells Fargo. | |
| 3 | 43 | The merchant was incorrectly set up at the processor. Call your Merchant Service Provider. | The merchant was incorrectly set up at the processor. | |
| 2 | 44 | This transaction has been declined. | The merchant would receive this error if the Card Code filter has been set in the Merchant Interface and the transaction received an error code from the processor that matched the rejection criteria set by the merchant. | |
| 2 | 45 | This transaction has been declined. | This error would be returned if the transaction received a code from the processor that matched the rejection criteria set by the merchant for both the AVS and Card Code filters. | |
| 3 | 46 | Your session has expired or does not exist. You must log in to continue working. | ||
| 3 | 47 | The amount requested for settlement may not be greater than the original amount authorized. | This occurs if the merchant tries to capture funds greater than the amount of the original authorization-only transaction. | |
| 3 | 48 | This processor does not accept partial reversals. | The merchant attempted to settle for less than the originally authorized amount. | |
| 3 | 49 | A transaction amount greater than $[amount] will not be accepted. | The transaction amount submitted was greater than the maximum amount allowed. | |
| 3 | 50 | This transaction is awaiting settlement and cannot be refunded. | Credits or refunds may only be performed against settled transactions. The transaction against which the credit/refund was submitted has not been settled, so a credit cannot be issued. | |
| 3 | 51 | The sum of all credits against this transaction is greater than the original transaction amount. | ||
| 3 | 52 | The transaction was authorized, but the client could not be notified; the transaction will not be settled. | ||
| 3 | 53 | The transaction type was invalid for ACH transactions. | If x_method = ECHECK, x_type cannot be set to CAPTURE_ONLY. | |
| 3 | 54 | The referenced transaction does not meet the criteria for issuing a credit. | ||
| 3 | 55 | The sum of credits against the referenced transaction would exceed the original debit amount. | The transaction is rejected if the sum of this credit and prior credits exceeds the original debit amount. | |
| 3 | 56 | This merchant accepts ACH transactions only; no credit card transactions are accepted. | The merchant processes eCheck transactions only and does not accept credit cards. | |
| 3 | 57 | An error occurred in processing. Please try again in 5 minutes. | ||
| 3 | 58 | An error occurred in processing. Please try again in 5 minutes. | ||
| 3 | 59 | An error occurred in processing. Please try again in 5 minutes. | ||
| 3 | 60 | An error occurred in processing. Please try again in 5 minutes. | ||
| 3 | 61 | An error occurred in processing. Please try again in 5 minutes. | ||
| 3 | 62 | An error occurred in processing. Please try again in 5 minutes. | ||
| 3 | 63 | An error occurred in processing. Please try again in 5 minutes. | ||
| 3 | 64 | The referenced transaction was not approved. | This error is applicable to Wells Fargo SecureSource merchants only. Credits or refunds cannot be issued against transactions that were not authorized. | |
| 2 | 65 | This transaction has been declined. | The transaction was declined because the merchant configured their account through the Merchant Interface to reject transactions with certain values for a Card Code mismatch. | |
| 3 | 66 | This transaction cannot be accepted for processing. | The transaction did not meet gateway security guidelines. | |
| 3 | 67 | The given transaction type is not supported for this merchant. | This error code is applicable to merchants using the Wells Fargo SecureSource product only. This product does not allow transactions of type CAPTURE_ONLY. | |
| 3 | 68 | The version parameter is invalid. | The value submitted in x_version was invalid. | |
| 3 | 69 | The transaction type is invalid. | The value submitted in x_type was invalid. | |
| 3 | 70 | The transaction method is invalid. | The value submitted in x_method was invalid. | |
| 3 | 71 | The bank account type is invalid. | The value submitted in x_bank_acct_type was invalid. | |
| 3 | 72 | The authorization code is invalid. | The value submitted in x_auth_code was more than six characters in length. | |
| 3 | 73 | The driver’s license date of birth is invalid. | The format of the value submitted in x_drivers_license_num was invalid. | |
| 3 | 74 | The duty amount is invalid. | The value submitted in x_duty failed format validation. | |
| 3 | 75 | The freight amount is invalid. | The value submitted in x_freight failed format validation. | |
| 3 | 76 | The tax amount is invalid. | The value submitted in x_tax failed format validation. | |
| 3 | 77 | The SSN or tax ID is invalid. | The value submitted in x_customer_tax_id failed validation. | |
| 3 | 78 | The Card Code (CVV2/CVC2/CID) is invalid. | The value submitted in x_card_code failed format validation. | |
| 3 | 79 | The driver’s license number is invalid. | The value submitted in x_drivers_license_num failed format validation. | |
| 3 | 80 | The driver’s license state is invalid. | The value submitted in x_drivers_license_state failed format validation. | |
| 3 | 81 | The requested form type is invalid. | The merchant requested an integration method not compatible with the AIM API. | |
| 3 | 82 | Scripts are only supported in version 2.5. | The system no longer supports version 2.5; requests cannot be posted to scripts. | |
| 3 | 83 | The requested script is either invalid or no longer supported. | The system no longer supports version 2.5; requests cannot be posted to scripts. | |
| 3 | 84 | This reason code is reserved or not applicable to this API. | ||
| 3 | 85 | This reason code is reserved or not applicable to this API. | ||
| 3 | 86 | This reason code is reserved or not applicable to this API. | ||
| 3 | 87 | This reason code is reserved or not applicable to this API. | ||
| 3 | 88 | This reason code is reserved or not applicable to this API. | ||
| 3 | 89 | This reason code is reserved or not applicable to this API. | ||
| 3 | 90 | This reason code is reserved or not applicable to this API. | ||
| 3 | 91 | Version 2.5 is no longer supported. | ||
| 3 | 92 | The gateway no longer supports the requested method of integration. | ||
| 3 | 93 | A valid country is required. | This code is applicable to Wells Fargo SecureSource merchants only. Country is a required field and must contain the value of a supported country. | |
| 3 | 94 | The shipping state or country is invalid. | This code is applicable to Wells Fargo SecureSource merchants only. | |
| 3 | 95 | A valid state is required. | This code is applicable to Wells Fargo SecureSource merchants only. | |
| 3 | 96 | This country is not authorized for buyers. | This code is applicable to Wells Fargo SecureSource merchants only. Country is a required field and must contain the value of a supported country. | |
| 3 | 97 | This transaction cannot be accepted. | Applicable only to SIM API. Fingerprints are only valid for a short period of time. This code indicates that the transaction fingerprint has expired. | |
| 3 | 98 | This transaction cannot be accepted. | Applicable only to SIM API. The transaction fingerprint has already been used. | |
| 3 | 99 | This transaction cannot be accepted. | Applicable only to SIM API. The server- generated fingerprint does not match the merchant-specified fingerprint in the x_fp_hash field. | |
| 3 | 100 | The eCheck type is invalid. | Applicable only to eCheck. The value specified in the x_echeck_type field is invalid. | |
| 3 | 101 | The given name on the account and/or the account type does not match the actual account. | Applicable only to eCheck. The specified name on the account and/or the account type do not match the NOC record for this account. | |
| 3 | 102 | This request cannot be accepted. | A password or transaction key was submitted with this WebLink request. This is a high security risk. | |
| 3 | 103 | This transaction cannot be accepted. | A valid fingerprint, transaction key, or password is required for this transaction. | |
| 3 | 104 | This transaction is currently under review. | Applicable only to eCheck. The value submitted for country failed validation. | |
| 3 | 105 | This transaction is currently under review. | Applicable only to eCheck. The values submitted for city and country failed validation. | |
| 3 | 106 | This transaction is currently under review. | Applicable only to eCheck. The value submitted for company failed validation. | |
| 3 | 107 | This transaction is currently under review. | Applicable only to eCheck. The value submitted for bank account name failed validation. | |
| 3 | 108 | This transaction is currently under review. | Applicable only to eCheck. The values submitted for first name and last name failed validation. | |
| 3 | 109 | This transaction is currently under review. | Applicable only to eCheck. The values submitted for first name and last name failed validation. | |
| 3 | 110 | This transaction is currently | Applicable only to eCheck. The value submitted under review. Reason: bank account name does not contain valid characters. | |
| 3 | 111 | A valid billing country is required. | This code is applicable to Wells Fargo SecureSource merchants only. | |
| 3 | 112 | A valid billing state/province is required. | This code is applicable to Wells Fargo SecureSource merchants only. | |
| 3 | 116 | The authentication indicator is invalid. | This code is applicable only to merchants that include the x_authentication_indicator in the transaction request. The ECI value for a Visa transaction; or the UCAF indicator for a MasterCard transaction submitted in the x_authentication_indicator field is invalid. | |
| 3 | 117 | The cardholder authentication value is invalid. | This code is applicable only to merchants that include the x_cardholder_authentication_value in the transaction request. The CAVV for a Visa transaction; or the AVV/UCAF for a MasterCard transaction is invalid. | |
| 3 | 118 | The combination of authentication indicator and cardholder authentication value is invalid. | This code is applicable only to merchants that include the x_authentication_indicator and x_authentication_value in the transaction request. The combination of authentication indicator and cardholder authentication value for a Visa or MasterCard transaction is invalid. | |
| 3 | 119 | Transactions having cardholder authentication values cannot be marked as recurring. | This code is applicable only to merchants that include the x_authentication_indicator and x_recurring_billing in the transaction request. Transactions submitted with a value in x_authentication_indicator AND x_recurring_billing =YES will be rejected. | |
| 3 | 120 | An error occurred during processing. Please try again. | The system-generated void for the original timed-out transaction failed. (The original transaction timed out while waiting for a response from the authorizer.) | |
| 3 | 121 | An error occurred during processing. Please try again. | The system-generated void for the original errored transaction failed. (The original transaction experienced a database error.) | |
| 3 | 122 | An error occurred during processing. Please try again. | The system-generated void for the original errored transaction failed. (The original transaction experienced a processing error.) | |
| 3 | 123 | This account has not been given the permission(s) required for this request. | The transaction request must include the API login ID associated with the payment gateway account. | |
| 2 | 127 | The transaction resulted in an AVS mismatch. The address provided does not match billing address of cardholder. | The system-generated void for the original AVS- rejected transaction failed. | |
| 3 | 128 | This transaction cannot be processed. | The customer's financial institution does not currently allow transactions for this account. | |
| 3 | 130 | This payment gateway account has been closed. | IFT: The payment gateway account status is Blacklisted. | |
| 3 | 131 | This transaction cannot be accepted at this time. | IFT: The payment gateway account status is Suspended-STA. | |
| 3 | 132 | This transaction cannot be accepted at this time. | IFT: The payment gateway account status is Suspended-Blacklist. | |
| 2 | 141 | This transaction has been declined. | The system-generated void for the original FraudScreen-rejected transaction failed. | |
| 2 | 145 | This transaction has been declined. | The system-generated void for the original card code-rejected and AVS-rejected transaction failed. | |
| 2 | 152 | The transaction was authorized, but the client could not be notified; the transaction will not be settled. | The system-generated void for the original transaction failed. The response for the original transaction could not be communicated to the client. | |
| 2 | 165 | This transaction has been declined. | The system-generated void for the original card code-rejected transaction failed. | |
| 3 | 170 | An error occurred during processing. Please contact the merchant. | Concord EFS – Provisioning at the processor has not been completed. | |
| 3 | 171 | An error occurred during processing. Please contact the merchant. | Concord EFS – This request is invalid. | |
| 3 | 172 | An error occurred during processing. Please contact the merchant. | Concord EFS – The store ID is invalid. | |
| 3 | 173 | An error occurred during processing. Please contact the merchant. | Concord EFS – The store key is invalid. | |
| 3 | 174 | The transaction type is invalid. Please contact the merchant. | Concord EFS – This transaction type is not accepted by the processor. | |
| 3 | 175 | The processor does not allow voiding of credits. | Concord EFS – This transaction is not allowed. The Concord EFS processing platform does not support voiding credit transactions. Please debit the credit card instead of voiding the credit. | |
| 3 | 180 | An error occurred during processing. Please try again. | The processor response format is invalid. | |
| 3 | 181 | An error occurred during processing. Please try again. | The system-generated void for the original invalid transaction failed. (The original transaction included an invalid processor response format.) | |
| 3 | 185 | This reason code is reserved or not applicable to this API. | ||
| 4 | 193 | The transaction is currently under review. | The transaction was placed under review by the risk management system. | |
| 2 | 200 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The credit card number is invalid. | |
| 2 | 201 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The expiration date is invalid. | |
| 2 | 202 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The transaction type is invalid. | |
| 2 | 203 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The value submitted in the amount field is invalid. | |
| 2 | 204 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The department code is invalid. | |
| 2 | 205 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The value submitted in the merchant number field is invalid. | |
| 2 | 206 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The merchant is not on file. | |
| 2 | 207 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The merchant account is closed. | |
| 2 | 208 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The merchant is not on file. | |
| 2 | 209 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. Communication with the processor could not be established. | |
| 2 | 210 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The merchant type is incorrect. | |
| 2 | 211 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The cardholder is not on file. | |
| 2 | 212 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The bank configuration is not on file | |
| 2 | 213 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The merchant assessment code is incorrect. | |
| 2 | 214 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. This function is currently unavailable. | |
| 2 | 215 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The encrypted PIN field format is invalid. | |
| 2 | 216 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The ATM term ID is invalid. | |
| 2 | 217 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. This transaction experienced a general message format problem. | |
| 2 | 218 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The PIN block format or PIN availability value is invalid. | |
| 2 | 219 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The ETC void is unmatched. | |
| 2 | 220 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The primary CPU is not available. | |
| 2 | 221 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. The SE number is invalid. | |
| 2 | 222 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. Duplicate auth request (from INAS). | |
| 2 | 223 | This transaction has been declined. | This error code applies only to merchants onFDC Omaha. This transaction experienced an unspecified error. | |
| 2 | 224 | This transaction has been declined. | This error code applies only to merchants on FDC Omaha. Please re-enter the transaction. | |
| 3 | 243 | Recurring billing is not allowed for this eCheck type. | The combination of values submitted for x_recurring_billing and x_echeck_type is not allowed. | |
| 3 | 244 | This eCheck type is not allowed for this Bank Account Type. | The combination of values submitted for x_bank_acct_type and x_echeck_type is not allowed. | |
| 3 | 245 | This eCheck type is not allowed when using the payment gateway hosted payment form. | The value submitted for x_echeck_type is not allowed when using the payment gateway hosted payment form. | |
| 3 | 246 | This eCheck type is not allowed. | The merchant’s payment gateway account is not enabled to submit the eCheck type. | |
| 3 | 247 | This eCheck type is not allowed. | The combination of values submitted for x_type and x_echeck_type is not allowed. | |
| 3 | 248 | The check number is invalid. | Invalid check number. Check number can only consist of letters and numbers and not more than 15 characters. | |
| 2 | 250 | This transaction has been declined. | This transaction was submitted from a blocked IP address. | |
| 2 | 251 | This transaction has been declined. | The transaction was declined as a result of triggering a Fraud Detection Suite filter. | |
| 4 | 252 | Your order has been received. | Thank you for your business! The transaction was accepted, but is being held for merchant review. The merchant may customize the customer response in the Merchant Interface. | |
| 4 | 253 | Your order has been received. | Thank you for your business! The transaction was accepted and was authorized, but is being held for merchant review. The merchant may customize the customer response in the Merchant Interface. | |
| 2 | 254 | Your transaction has been declined. | The transaction was declined after manual review. | |
| 3 | 261 | An error occurred during processing. Please try again. | The transaction experienced an error during sensitive data encryption and was not processed. Please try again. | |
| 3 | 270 | The line item [item number] is invalid. | A value submitted in x_line_item for the item referenced is invalid. | |
| 3 | 271 | The number of line items submitted is not allowed. A maximum of 30 line items can be submitted. | The number of line items submitted in x_line_item exceeds the allowed maximum of 30. |
Note: Response code reasons that are not included in numerical order are reserved, or may not be applicable to this API.
HTTP Error Codes & Reason Text
| HTTP CODE | RESPONSE REASON TEXT | NOTES |
|---|---|---|
| 503 | Our servers are currently too busy to handle your request. Please wait a minute and resubmit. Thank you. | The payment gateway has momentarily reached transaction queuing capacity. |
MD5 Hash Feature
The MD5 Hash feature enables you to authenticate that a transaction response is securely received from GoToBilling. The payment gateway creates the MD5 hash using the following pieces of account and transaction information as input:
- MD5 Hash value
- API Login ID (x_login)
- Transaction ID (x_trans_id)
- Amount (x_amount)
The MD5 Hash value is a random value configured by the merchant in the Merchant Interface. It should be stored securely separately from the merchant's Web server. To configure the MD5 Hash value: access the GoToBilling system (https://secure.gotobilling.com), go to Profile > Settings > Preferences Tab. For example, if the MD5 Hash value configured by the merchant is "myhashvalue," the API Login ID is "123456", the Transaction ID is 987654321, and the amount is $1.00, then the field order used by the payment gateway to generate the MD5 Hash would be as follows.
Sample of MD5 Hash input field order
myhashvalue1234569876543211.00
Note: The value passed back for x_amount is formatted with the correct number of decimal places used in the transaction. For transaction types that do not include a transaction amount, mainly Voids, the amount used by the payment gateway to calculate the MD5 Hash is 0.00. To authenticate the MD5 Hash returned by the payment gateway in the transaction response, you need to create a script that can receive and parse the transaction response, call the merchant's MD5 Hash value, and run the MD5 algorithm on the same fields listed above. If the result matches the MD5 hash returned by the payment gateway, the transaction response is successfully authenticated. Note: The MD5 Hash will be passed in transaction responses even if you do not set an MD5 Hash Value.
Card Present Submission & Response
For Card Present transactions, the merchant and shopper are in the same physical location. The merchant will have a card reader (or “swipe terminal”) and receipt printer at the point of purchase. The card reader device reads the magnetic stripe on the back of the card and transmits the encoded information to the gateway. Once a transaction is approved, the merchant can print a receipt for obtaining the cardholder’s signature.
Minimum Requirements
| Field | Value | Description |
|---|---|---|
| x_cpversion | 1.0 | |
| x_login | Your login ID | See: Merchant Account Information |
| x_tran_key | Your transaction key | See: Merchant Account Information |
| x_market_type | Your market type | |
| x_device_type | Your device type | |
| x_amount | Amount of purchase inclusive of tax | |
| x_track1 OR | Track 1 data from credit card | Must be supplied if neither x_track2 nor x_card_num and x_exp_date data is submitted. |
| x_track2 OR | Track 2 data from credit card | Must be supplied if neither x_track1 nor x_card_num and x_exp_date data is submitted. |
| x_card_num AND | Customer's card number | Must be supplied if neither x_track1 nor x_track2 data is submitted. |
| x_exp_date | Customer's card expiration date | Must be supplied if neither x_track1 nor x_track2 data is submitted. |
Gateway Response API
This section describes the response returned by the gateway when a merchant server submits a transaction for processing. The response is a set of fields that give merchants information about the status of a transaction. The fields will be bar (‘|’) delimited by default or delimited by the character specified by the merchant. The merchant server can parse this data and determine the message to display to the customer.
Fields in the Gateway Response
The following table indicates the order of the fields returned in the AIM response from the gateway to the merchant server.
The following table indicates the order of the fields returned in the AIM response from the gateway to the merchant server.
| POSITION IN RESPONSE | FIELD NAME OF VALUE IN RESPONSE | DESCRIPTION |
|---|---|---|
| 1 | Version | System version used to process the transaction |
| 2 | Response Code | Indicates the result of the transaction:
|
| 3 | Reason Code | A code representing more details about the result of the transaction. |
| 4 | Reason Text | Brief description of a result, which corresponds with the Reason Code. |
| 5 | Authorization Code | Contains the six-digit alphanumeric approval code. |
| 6 | AVS Code | Indicates the result of Address Verification System (AVS) checks |
| 7 | Card Code Response | Indicates the results of Card Code verification |
| 8 | Transaction ID | This number identifies the transaction in the system and can be used to submit a modification of this transaction at a later time, such as voiding, crediting or capturing the transaction. |
| 9 | MD5 Hash | System-generated hash that may be validated by the merchant to authenticate a transaction response received from the gateway. |
| 10 | User Reference | Echoed by the system from the form input field x_user_ref. |