Transaction Data Requirements
The standard payment gateway application programming interface (API) consists of required information fields (introduced in the previous section) and additional optional fields that can be submitted to the payment gateway for real-time transaction processing.
Transaction Post Location
The merchant’s Web site should submit transaction requests to the following payment gateway URL:
https://gateway.merchantplus.com/cgi-bin/PAWebClient.cgi
Note: If you are using a developer test account, test transactions are posted to the same as the production environment. If you do not have a developer test account, you can sign up for one by emailing support@merchantplus.com.
Transaction Submission API
The following tables list the transaction data fields that can be submitted using the transaction request string. Several of these fields can also be configured in the Merchant Interface. For more information about configuring these settings in the Merchant Interface, see the Integration Wiki here.
Fields are name/value pairs with the syntax: x_name_of_field = value of the field&.
Merchant Information
| Field Name | Description |
|---|---|
| x_login | Required Value: The merchant’s unique Login ID Format: Up to 20 characters Notes: The merchant Login ID is provided in the Merchant Interface and must be stored securely. The API Login ID and Transaction Key together provide the merchant authentication required for access to the payment gateway. |
| x_tran_key | Required Value: The merchant’s unique Transaction Key Format: 16 characters Notes: The merchant Transaction Key is provided in the Merchant Interface and must be stored securely. The API Login ID and Transaction Key together provide the merchant authentication required for access to the payment gateway. |
Transaction Information
| Field Name | Description |
|---|---|
| x_method | Required Value: The payment method Format: CC or SVP Notes: If this field is not submitted or the value is blank, the payment gateway will generate an error "x_Method cannot be left blank". |
| x_type | Required Value: The type of credit card transaction Format: AUTH_CAPTURE , AUTH_ONLY, CREDIT, PRIOR_AUTH_CAPTURE, VOID ( for FirstData and Tsys ) Notes: If the value submitted does not match a supported value, the transaction is rejected. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_type cannot be left blank". |
| x_amount | Required Value: The amount of the transaction Format; Up to 15 digits (no dollar symbol). For example, 102 Notes: This is the total amount and must include tax, shipping, and any other charges. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_amount cannot be left blank". |
| x_card_num | Required Value: The customer’s credit card number Format; Between 13 and 16 digits without spaces. Notes: This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_card_num cannot be left blank". |
| x_exp_date | Required Value: The customer’s credit card expiration date. Format; MMYY. Notes: This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_exp_date cannot be left blank". |
| x_card_code | Optional Value: The customer’s card code Format: Numeric Notes: The three- or four-digit number on the back of a credit card (on the front for American Express). This field is required if the merchant would like to use the Card Code Verification (CCV) security feature. For more information, see the Merchant Integration Guide at http://www.merchantplus.com/support/merchant. |
| x_trans_id | Conditional Required only for CREDIT, PRIOR_ AUTH_ CAPTURE, and VOID transactions Value: The payment gateway assigned transaction ID of an original transaction Notes: For more information about transaction types, see the "Credit Card Transaction Types," section of this document. |
| x_test_request | Optional Value: The request to process test transactions Format: TRUE, FALSE. Notes: Indicates if the transaction should be processed as a test transaction. "Test Transactions," section for more information. |
Order Information
| Field Name | Description |
|---|---|
| x_invoice_num | Optional Value: The merchant-assigned invoice number for the transaction Format: Up to 20 characters (no symbols) Notes: 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. |
| x_description | Optional Value: The transaction description Format: Up to 255 characters (no symbols) Notes: 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. |
Customer Information
| Field Name | Description |
|---|---|
| x_first_name | Optional Value: The first name associated with the customer’s billing address Format: Up to 50 characters (no symbols) |
| x_last_name | Optional Value: The last name associated with the customer’s billing address Format: Up to 50 characters (no symbols) |
| x_company | Optional Value: The company associated with the customer’s billing address Format: Up to 50 characters (no symbols) |
| x_address | Optional Value: The customer’s billing address Format: Up to 60 characters (no symbols) Notes: Required if the merchant would like to use the Address Verification Service security feature. |
| x_city | Optional Value: The city of the customer’s billing address Format: Up to 40 characters (no symbols) |
| x_state | Optional Value: The state of the customer’s billing address Format: Up to 40 characters (no symbols) or a valid two-character state code |
| x_zip | Optional Value: The ZIP code of the customer’s billing address Format: Up to 20 characters (no symbols) Notes: Required if the merchant would like to use the Address Verification Service security feature. |
| x_country | Optional Value: The country of the customer’s billing address Format: Up to 60 characters (no symbols) For example, (123)123-1234 |
| x_phone | Optional Value: The phone number associated with the customer’s billing address Format: Up to 25 digits (no letters). |
| x_fax | Optional Value: The fax number associated with the customer’s billing address Format: Up to 25 digits (no letters). For example, (123)123-1234 |
| x_email | Optional Value: The customer’s valid email address Format: Up to 255 characters. For example, zac@merchantplus.com Notes: 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. |
| x_cust_id | Optional Value: The merchant assigned customer ID Format: Up to 20 characters (no symbols) Notes: 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. |
| x_customer_ip | Optional Value: The customer’s IP address Format: Up to 15 characters (no letters). For example, 255.255.255.255 Notes: IP address of the customer initiating the transaction. If this value is not passed, it will default to 255.255.255.255. |
Shipping Information
| Field Name | Description |
|---|---|
| x_ship_to_first_name | Optional Value: The first name associated with the customer’s shipping address Format: Up to 50 characters (no symbols) |
| x_ship_to_last_name | Optional Value: The last name associated with the customer’s shipping address Format: Up to 50 characters (no symbols) |
| x_ship_to_company | Optional Value: The company associated with the customer’s shipping address Format: Up to 50 characters (no symbols) |
| x_ship_to_address | Optional Value: The customer’s shipping address Format: Up to 60 characters (no symbols) |
| x_ship_to_city | Optional Value: The city of the customer’s shipping address Format: Up to 40 characters (no symbols) |
| x_ship_to_state | Optional Value: The state of the customer’s shipping address Format: Up to 40 characters (no symbols) or a valid two-character state code |
| x_ship_to_zip | Optional Value: The ZIP code of the customer’s shipping address Format: Up to 20 characters (no symbols) |
| x_ship_to_country | Optional Value: The country of the customer’s shipping address Format: Up to 60 characters (no symbols) |