A-C | D-G | H-K | L-O | P-R | S-T | U-Z
| FIELD NAME |
REQUIRED |
VALUE |
FORMAT |
NOTES |
| Optional |
The customer's billing address |
Up to 60 characters (no symbols) |
Required if the merchant would like to use the Address Verification Service security feature. For more information on AVS, see the Merchant Integration Guide. Required for Zero Dollar Authorizations for Visa verification transactions. |
|
| x_amount |
Required if x_type = AUTH_CAPTURE, AUTH_ONLY, CREDIT |
The amount of the transaction |
Up to 15 digits with a decimal point (no dollar symbol) Ex. 8.95 |
The total amount to be charged or credited including tax, shipping and any other charges. The amount can either be hard coded or posted to a script. |
| x_background_url |
Optional |
The URL of the merchant's background image |
|
The image referenced by this URL is displayed as the background on the hosted payment form or receipt page. Background images must be uploaded to the payment gateway server. See Logos and Background Images for the Payment Form for more information on how to upload images. |
| x_card_num |
Required only if x_type = CREDIT |
The customer's partial credit card number |
The last four digits of the credit card number only |
As a hosted solution, SIM does not support the submission of full cardholder data. Ideally, CREDIT transactions should be submitted exclusively in the Merchant Interface. However, a partial credit card number is allowed for SIM when submitting a CREDIT using the API. This field should not be passed for a SIM transaction under any other circumstance. |
| x_city |
Optional |
The city of the customers billing address |
Up to 40 characters (no symbols) |
|
| x_color_background |
Optional |
The hosted payment form or receipt page background color |
Any valid HTML color name or color hex code |
This field is common to the hosted payment form and receipt page. The value in this field sets the background color for both. |
| x_color_link |
Optional |
The hosted payment form and receipt page hyperlink color |
Any valid HTML color name or color hex code |
This field is common to the hosted payment form and receipt page. The value in this field sets the color of the HTML links for both. |
| x_color_text |
Optional |
The hosted payment form and receipt page text color |
Any valid HTML color name or color hex code |
This field is common to the hosted payment form and receipt page. The value in this field sets the color of the text for both. |
| x_company |
Optional |
The company associated with the customers billing address |
Up to 50 characters (no symbols) |
|
| x_country |
Optional |
The country of the customer's billing address |
Up to 60 characters (no symbols) |
|
| x_cust_id |
Optional |
The merchant assigned customer ID |
Up to 20 characters (no symbols) |
The unique identifier to represent the customer associated with the transaction. The customer ID must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function. Also, in order to be displayed, the attribute View must be configured for this field in the Merchant Interface payment form settings. |
| x_customer_ip |
Optional |
The customer's IP address |
Up to 15 characters (no letters) Ex., 255.255.255.255 |
The IP address of the customer initiating the transaction. If this value is not passed, it will default to 255.255.255.255. This field is required when using the Fraud Detection Suite (FDS) IP Address Blocking tool. For more information about FDS, see the Merchant Integration Guide. |
| FIELD NAME |
REQUIRED |
VALUE |
FORMAT |
NOTES |
| Optional |
The transaction description |
Up to 255 (no symbols) |
The description must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function. Also, in order to be displayed, the attribute View must be configured for this field in the Merchant Interface payment form settings. |
|
| x_duplicate_window |
Optional |
The window of time after the submission of a transaction that a duplicate transaction can not be submitted |
Any value between 0 and 28800 (no commas) |
The window of time in seconds after a transaction is submitted during which the payment gateway will check for a duplicate transaction. The maximum time allowed is 8 hours (28800 seconds). If a value less than 0 is sent, the payment gateway defaults to 0 seconds. If a value greater than 28800 is sent, the payment gateway will default to 28800. If no value is sent, the payment gateway defaults to 2 minutes (120 seconds). If this field is present in the request with or without a value, an enhanced duplicate transaction response is sent. See Response for Duplicate Transactions for more information. |
| x_duty |
Optional |
The valid duty amount OR delimited duty information |
When submitting delimited duty information, values must be delimited by a bracketed pipe <|> |
The duty amount charged. When submitting this information via the HTML Form POST, delimited duty information including the duty name, description, and amount is also allowed. The total amount of the transaction in x_amount must include this amount. |
| duty item name<|> |
|
The duty item name. |
||
| duty description<|> |
|
The duty item description. |
||
| duty amount |
The dollar sign ($) is not allowed when submitting delimited information. |
The duty amount. The total amount of the transaction in x_amount must include this amount. |
||
| Example: |
<INPUT TYPE="HIDDEN" name="x_duty" VALUE="Duty1<|>export<|>15.00> |
|||
| x_email |
Optional |
The customer's valid email address |
Up to 255 characters Ex. janedoe@customer.com |
The email address to which the customer's copy of the email receipt is sent when Email Receipts is configured in the Merchant Interface. The email is sent to the customer only if the email address format is valid. For more information about Email Receipts, please see the Merchant Integration Guide. |
| x_email_customer |
Optional |
The customer email receipt status |
TRUE, FALSE, |
Indicates whether an email receipt should be sent to the customer. If set to TRUE, the payment gateway will send an email to the customer after the transaction is processed using the customer email address submitted with the transaction. If FALSE, no email is sent to the customer. If no value is submitted, the payment gateway will look up the configuration in the Merchant Interface and send an email only if the merchant has enabled the setting. If this field is not submitted and the setting is disabled in the Merchant Interface, no email is sent. For more information about configuring Email Receipts in the Merchant Interface, see the Merchant Integration Guide. |
| x_fax |
Optional |
The fax number associated with the customers billing address |
Up to 25 digits (no letters) Ex. (123)123-1234 |
|
| x_first_name |
Optional |
The first name associated with the customers billing address |
Up to 50 characters (no symbols) |
|
| x_footer_email_receipt |
Optional |
The email receipt footer |
Plain text |
This text will appear as the footer on the email receipt sent to the customer. |
| x_footer_html_payment_form |
Optional |
The hosted payment form footer |
Plain text or HTML. Avoid using double quotes. |
The text or HTML submitted in this field is displayed as the footer on the hosted payment form. When using HTML styles or referencing a cascading style sheet (.css), it is recommended that you submit this field with the HTML Form POST. With this method there is no character limit. |
| x_footer_html_receipt |
Optional |
The hosted receipt page footer |
Plain text or HTML. Avoid using double quotes |
The text or HTML submitted in this field is displayed at the bottom of the hosted receipt page. When using HTML styles or referencing a cascading style sheet (.css), it is recommended that you submit this field with the HTML Form POST. With this method there is no character limit. |
| x_fp_hash |
Required |
The transaction unique fingerprint |
N/A |
The fingerprint is generated using the HMAC-MD5 hashing algorithm on the following field values:
Field values are concatenated and separated by the ^ character. |
| x_fp_sequence |
Required |
The merchant assigned sequence number for the transaction |
Numeric |
The sequence number can be a merchant assigned value, such as an invoice number or any randomly generated number. |
| x_fp_timestamp |
Required |
The timestamp at the time of fingerprint generation |
UTC time in seconds since January 1, 1970 |
Coordinated Universal Time (UTC) is an international atomic standard of time (sometimes referred to as GMT). Using a local time zone timestamp will cause fingerprint authentication to fail. |
| x_freight |
Optional |
The valid freight amount OR delimited freight information |
When submitting delimited freight information, values must be delimited by a bracketed pipe <|> |
The freight amount charged. When submitting this information via the HTML Form POST, delimited freight information including the freight name, description, and amount is also allowed. The total amount of the transaction in x_amount must include this amount. |
| freight item name<|> |
|
The freight item name. |
||
| freight description<|> |
|
The freight item description. |
||
| freight amount |
|
The freight item amount. The total amount of the transaction in x_amount must include this amount. |
||
| Example: |
<INPUT TYPE="HIDDEN" name="x_freight" VALUE="Freight1<|> ground overnight<|>12.95> |
| FIELD NAME |
REQUIRED |
VALUE |
FORMAT |
NOTES |
| Optional |
The email receipt header |
Plain text |
This text will appear as the header of the email receipt sent to the customer. |
|
| x_header_html_payment_form |
Optional |
The hosted payment form header |
Plain text or HTML. Avoid using double quotes |
The text or HTML submitted in this field is displayed as the header on the hosted payment form. When using HTML styles or referencing a cascading style sheet (.css), it is recommended that you submit this field using the HTML Form POST. With this method there is no character limit. |
| x_header_html_receipt |
Optional |
The hosted receipt page header |
Plain text or HTML. Avoid using double quotes |
The text or HTML submitted in this field is displayed at the top of the hosted receipt page. When using HTML styles or referencing a cascading style sheet (.css), it is recommended that you submit this field using the HTML Form POST. With this method there is no character limit. |
| x_invoice_num |
Optional |
The merchant assigned invoice number for the transaction |
Up to 20 characters (no symbols) |
The invoice number must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function. Also, in order to be included on the hosted payment form, the attribute View must be configured for this field in the Merchant Interface payment form settings. |
| FIELD NAME |
REQUIRED |
VALUE |
FORMAT |
NOTES |
| Optional |
The last name associated with the customers billing address |
Up to 50 characters (no symbols) |
|
|
| x_line_item |
Optional All line item values are required when this field is submitted |
Any string |
Line item values must be delimited by a bracketed pipe <|> |
Itemized order information. |
| Item ID<|> |
Up to 31 characters |
The ID assigned to an item. |
||
| <|>item name<|> |
Up to 31 characters |
A short description of an item. |
||
| <|>item description<|> |
Up to 255 characters |
A detailed description of an item. |
||
| <|>itemX quantity<|> |
Up to two decimal places. Must be a positive number |
The quantity of an item. |
||
| <|>item price (unit cost)<|> |
Up to two decimal places. Must be a positive number |
Cost of an item per unit, excluding tax, freight, and duty. The dollar sign ($) is not allowed when submitting delimited information. |
||
| <|>itemX taxable |
TRUE, FALSE, |
Indicates whether the item is subject to tax. |
||
| x_login |
Required |
The merchant's unique API Login ID |
Up to 20 characters |
The merchant API Login ID is provided in the Merchant Interface and must be stored securely. The API Login ID and transaction fingerprint together provide the merchant authentication required for access to the payment gateway. See the Merchant Integration Guide for more information. |
| x_logo_url |
Optional |
The URL of the merchant's logo |
|
The image referenced by this URL is displayed in the header or footer of the hosted payment form and receipt page. Logo images must be uploaded to the payment gateway server. See Logos and Background Images for the Payment Form" for more information on how to upload images. |
| x_method |
Optional |
The payment method |
CC or ECHECK |
The method of payment for the transaction, CC (credit card) or ECHECK (electronic check). If left blank, this value will default to CC. For more information about eCheck.Net transaction requirements, see the eCheck.Net Developer Guide. |
| FIELD NAME |
REQUIRED |
VALUE |
FORMAT |
NOTES |
| Optional |
The phone number associated with the customers billing address |
Up to 25 digits (no letters) Ex.: (123)123-1234 |
|
|
| x_po_num |
Optional |
The merchant assigned purchase order number |
Up to 25 characters (no symbols) |
The purchase order number must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function. Also, in order to be displayed, the attribute View must be configured for this field in the Merchant Interface payment form settings. |
| x_receipt_link_method |
Optional |
The type of link back to the merchant's Web site from the hosted receipt page |
LINK, POST, or GET |
|
| x_receipt_link_text |
Optional |
The text of the link or button that directs the customer back to the merchants Web site |
Up to 50 characters |
If the x_receipt_link_method is LINK, the value in this field will become a hyperlinked text on the hosted receipt page If the x_receipt_link_method is GET or POST the value in this field becomes the text of a submit button. An HTML form is created in the receipt page that has hidden fields containing the results of the transaction processed. |
| x_receipt_link_url |
Optional |
The URL of the link or button that directs the customer back to the merchants Web site |
|
To be accepted as valid by the payment gateway, the URL must be configured in the Merchant Interface. If the x_receipt_link_method is LINK, the URL specified becomes the href value of the hyperlinked text. If the x_receipt_link_method is GET or POST, the URL will become the action of the HTML form. |
| x_recurring_billing |
Optional |
The recurring billing status |
TRUE, FALSE, |
Indicating marker used by merchant account providers to identify transactions that originate from merchant-hosted recurring billing applications. This value is not affiliated with Automated Recurring Billing. |
| x_relay_response |
Optional |
The request for a relay response |
TRUE, FALSE, |
This field instructs the payment gateway to return transaction results to the merchant using an HTML form POST to the merchant's Web server for a relay response. |
| x_relay_URL |
Optional |
The URL on the merchant's Web site to which the payment gateway should post transaction results for a relay response |
Any valid URL Including name/value pairs in the URL(anything after a ?) is not recommended |
If this field is submitted, the payment gateway will validate the URL value against the Relay Response URL configured in the Merchant Interface. If the URL submitted does not match the URL configured in the Merchant Interface, the transaction will be rejected. If no value is submitted in the HTML Form POST, the payment gateway will post the transaction results to the URL configured in the Merchant Interface. |
| FIELD NAME |
REQUIRED |
VALUE |
FORMAT |
NOTES |
| Optional |
The customer's shipping address |
Up to 60 characters (no symbols) |
|
|
| x_ship_to_company |
Optional |
The company associated with the customer's shipping address |
Up to 50 characters (no symbols) |
|
| x_ship_to_country |
Optional |
The country of the customer's shipping address |
Up to 60 characters (no symbols) |
|
| x_ship_to_city |
Optional |
The city of the customers shipping address |
Up to 40 characters (no symbols) |
|
x_ship_to_first_name |
Optional |
The first name associated with the customers shipping address |
Up to 50 characters (no symbols) |
|
| x_ship_to_last_name |
Optional |
The last name associated with the customers shipping address |
Up to 50 characters (no symbols) |
|
| x_ship_to_state |
Optional |
The state of the customer's shipping address |
Up to 40 characters (no symbols) or a valid two-character state code |
|
| x_ship_to_zip |
Optional |
The ZIP code of the customers shipping address |
Up to 20 characters (no symbols) |
|
| x_show_form |
Required |
The payment form request |
PAYMENT_FORM |
The show form field indicates that the merchant wishes to use the payment gateway hosted payment form to collect payment data. |
| x_state |
Optional |
The state of the customer's billing address |
Up to 40 characters (no symbols) or a valid two-character state code |
|
| x_tax |
Optional |
The valid tax amount OR the delimited tax information |
When submitting delimited tax information, values must be delimited by a bracketed pipe <|> |
The tax amount charged. When submitting this information using the HTML Form POST, delimited tax information including the sales tax name, description, and amount is also allowed. The total amount of the transaction in x_amount must include this amount. |
| tax item name<|> |
|
The tax item name. |
||
| tax description<|> |
|
The tax item description. |
||
| tax amount |
The dollar sign ($) is not allowed when submitting delimited information. |
The tax item amount. The total amount of the transaction in x_amount must include this amount. |
||
| Example: |
<INPUT TYPE="HIDDEN" name="x_tax" VALUE="Tax1<|>state tax<|>0.0625"> |
|||
| x_tax_exempt |
Optional |
The tax exempt status |
TRUE, FALSE, |
Indicates whether the transaction is tax exempt. The total amount of the transaction in x_amount must include this amount. |
| x_test_request |
Optional |
The request to process test transactions |
TRUE, FALSE, |
Indicates whether or not the transaction should be processed as a test transaction. See Test Transactions" for more information. |
| x_trans_id |
Required when x_type = CREDIT, PRIOR_AUTH_CAPTURE, VOID |
The payment gateway assigned transaction ID of an original transaction |
Numeric |
Required only for CREDIT, PRIOR_AUTH_CAPTURE, and VOID transactions. For more information about transaction types, see Credit Card Transaction Types. |
| x_type |
Optional |
The type of credit card transaction |
AUTH_CAPTURE (default), AUTH_ONLY, CREDIT, PRIOR_AUTH_CAPTURE, VOID |
If the value submitted does not match a supported value, the transaction is rejected. If no value is submitted in this field, the payment gateway will process the transaction as an AUTH_CAPTURE. |
| FIELD NAME |
REQUIRED |
VALUE |
FORMAT |
NOTES |
| Optional, but highly recommended |
The merchant's transaction version |
3.0, 3.1 |
The transaction version represents the set of fields that is included with the transaction response. 3.0 is the default version. 3.1 allows the merchant to utilize the Card Code feature, and is the current standard version. It is highly recommended that you submit this field on a per-transaction basis to be sure that the formats of transaction requests and the responses you receive are consistent, particularly if you are using Relay Response. For more information, see Relay Response and Appendix A Fields by Transaction Type. |
|
| x_zip |
Optional |
The ZIP code of the customers billing address |
Up to 20 characters (no symbols) |
Required if the merchant would like to use the Address Verification Service security feature. For more information on AVS, see the Merchant Integration Guide. Required for Zero Dollar Authorizations for Visa verification transactions. |