Smart Screens/Direct Method Variable Table

This table includes the name/value pairs required for the ‘Smart Screens v1’ or ‘Direct Method’ of integration.

Please use only those Variables marked with a “x” in the column for the type of method you wish to use.

‘SS’ = For Smart Screen Services
‘DM’ = For Direct Method Services
Variable Required Notes SS DM
publisher-name Mandatory Username Issued by us to you at time of sign up. x x
lang Optional 2 letter abbreviation of the language in which to present the page in.Allowed Values:- ’en’ is English- ’es’ is Spanish- ‘fr’ is French- ’nl’ is DutchAdditional languages available upon request. x
card-amount Mandatory No ‘$’ - Total amount to be chargedNOTE: may be omitted if the number and cost of each product ordered is submitted as explained in note 2 below. The system will then calculate the total amount due. x x
authtype Optional Allowed value: ‘authpostauth’ - Automatically marks transaction for settlement. Defaults to ‘authonly’ if absent. x x
convert Optional When value is set to ‘underscores’, it converts underscores to hyphens. Used to support client software, which is not able to use hyphens within variable names. x x
shipinfo Optional Causes payment screens to prompt for separate shipping address. Set value to ‘1’ to enable: x x
keyswipe - see note 4 Optional If set to ‘yes’, will provide option to use a keyboard emulated credit card reader to read/insert the credit card’s magstripe info into the billing page. x n/a
plan Optional/Mandatory PlanID of the selected subscription plan. Required to support Membership Management features if applicable. x x
easycart Optional If set to 1 will display contents of order on payment page and in email to customer and merchant. x x
item# - see note 2 Optional Model of item x x
cost# - see note 2 Optional Cost of item x x
quantity# - see note 2 Optional Quantity of item x x
description# - see note 2 Optional Description of item x x
taxable - see note 7 Optional Used to distinguish between products that may not be subject to sales tax. Valid values for the ’taxable’ field are ‘Y’ or ‘N’. Item is assumed taxable, when field not supplied. x x
receipt_type - see note 3 Optional Creates an online receipt (after a successful authorization) when no ‘success-link’ URL has been defined.Possible values include ‘simple’, ‘itemized’, ‘pos_simple’ & ‘pos_itemized’- ‘simple’ creates a simple non-itemized receipt.- ‘itemized’ creates an itemized receipt.- ‘pos_simple’ creates a simple non-itemized receipt for POS receipt printers.- ‘pos_itemized’ creates an itemized receipt for POS receipt printers.Ex. x x
print_receipt Optional Automatically invoke printing of the receipt when the receipt is shown to screen. (Requires ‘receipt_type’ field to be set) x x
taxrate Optional Sales tax rate.Multiple Rates to be delimited with a ‘pipe’ i.e. ‘|’ .Ex. This will set 2 tax rates. x n/a
taxstate Optional Sales tax states.Multiple States to be delimited with a ‘comma’ i.e. ‘,’.Value equal to 2 letter state abbreviation.Ex. This sets 2 tax states. New York and California.Please see note 8 below x n/a
shipping Optional Sets shipping charge for entire order.Ex. x x
handling Optional Applies a flat handling fee to an order.Ex. x x
currency Optional 3 characters. Should only be used for currencies for which your merchant account is set up.Allowed values (case-sensitive):‘aud’,‘cad’,’eur’,‘gbp’,‘jpy’,‘usd’,‘frf’,‘chf’,‘jmd’. x
card-allowed Optional Controls which credit card types are presented to the customer as payment options.Valid values are:Visa,Mastercard,Amex,Discover,Diners,JCB,EasyLink,Bermuda,IslandCard,Butterfield,KeyCard, MilStar,Solo,SwitchEx. x n/a
currency_symbol Optional Used to set the symbol used for currency in payment forms.This only sets the symbol for the pages it does not do any calculation of exchange rates and does not actually set the currency for the transaction.For example, to show Euro:<input type=“hidden” name=“currency_symbol” value=""€">Please refer to the Online FAQ, QA20050713163906, for other examples. x x
app-level Optional AVS (Address Verification System)Please refer to the AVS Code Specification section for valid values. x x
order-id Optional Alphanumeric value generated by you.This can be an invoice or customers username/ID or what ever you wish to use to track the payment with the order. x x
acct_code Optional The value for ‘acct_code’ can be up to 20 alphanumeric characters. Include this field with your orders/transactions so its value can be stored to our databases with your orders. You can later use this field to filter/select only those orders which match the value passed when using many of the administrative functions.NOTE: If you are using our Affiliate Management service, you should use ‘acct_code2’ field instead; since the ‘acct_code’ field would be used by the Affiliate Management service to store the affiliate who is credited with the sale. x x
acct_code2 Optional The value for ‘acct_code2’ can be up to 20 alphanumeric characters. Include this field with your orders/transactions so its value can be stored to our databases with your orders. You can later use this field to filter/select only those orders which match the value passed when using many of the administrative functions. x x
acct_code3 Optional The value for ‘acct_code3’ can be up to 20 alphanumeric characters. Include this field with your orders/transactions so its value can be stored to our databases with your orders. You can later use this field to filter/select only those orders which match the value passed when using many of the administrative functions. x x
paymethod Used to set script for special types of payments.Allowed Values:- ‘credit’ or blank for normal credit card payments,- ‘swipe’ for POS/swipe [minimum data] credit card payments,- ‘onlinecheck’ for ACH/eCheck payments (ACH/eCheck merchant account required),- ‘mpgiftcard’ for Mercury Giftcard Split Payments (Mercury Giftcard ability required),- ‘invoice’ for Invoice only payments (invoice ability required),- ‘prepaid’ for prepaid stored value card payments (prepaid stored value ability required),- ‘mocapay’ for MocaPay card payments (MocaPay ability required) x x
transitiontype - see note 1 Optional Supersedes the Transition Page settings within Account Settings.Allowed Values:- ‘get’ forces Transaction Page w/GET form method,- ‘post’ forces Transaction Page w/POST form method,- ‘hidden’ uses our server’s hidden POST method w/o showing a Transition Page. x x
success-link - see note 1 Optional Fully qualified URL to call after a successful authorization of the credit card is received from the credit card processor.If URL is a script, method will be via a POST. If the URL is a web page, method will be by a GET.Ex. http://www.yourdomain.com/thankyou.html x x
badcard-link - see note 1 Optional Fully qualified URL to call after a failed card response is received from the credit card processor.If URL is a script, method will be via a POST.If the URL is a web page, method will be by a GET.Ex. http://www.yourdomain.com/badcard.html x x
problem-link - see note 1 Optional Fully qualified URL to call after either no response or an error message is received from the credit card processor.If URL is a script, method will be via a POST. If the URL is a web page, method will be by a GET.Ex. http://www.yourdomain.com/problem.html x x
card-name Mandatory Customers name as it appears on Credit Card x
card-company Optional Billing company name x
card-address1 Mandatory Billing Street Address Line 1 x
card-address2 Optional Billing Street Address Line 2 x
card-city Mandatory Billing City Address x
card-state Mandatory Billing State Address x
card-prov Optional Billing International Province. For international provinces outside of US & Canada, set the ‘card-state’ field’s value to ‘ZZ’ & include the province name here. x
card-zip Mandatory Billing Zip Address x
card-country Mandatory Billing 2 Character Country Code - see Appendix for country code listing. x
card-number Mandatory Credit Card Number (Example: ****************) x
card-exp Mandatory Credit Card Expiration Date, Format: MM/YY x
card-cvv Optional/Fraud Credit Card CVV Number. Mandatory for fraud protection. x
phone Optional Customer contact number x
fax Optional Customer Fax number x
email Optional person@place.com - Email address the customer’s order confirmation is sent to. x
ipaddress Optional IP Address of originating client. Used for some fraud screening options. x
routingnum Optional/Mandatory ABA bank routing number. Required for electronic check payments. x
accountnum Optional/Mandatory Bank account number. Required for electronic check payments. x
checknum Optional/Mandatory Bank account check number. Optional for electronic check payments. x
checktype Optional/Mandatory SEC code for checks. Possible values are ‘PPD’, ‘CCD’, ‘WEB’, and ‘TEL’. Required for electronic check payments. x x
accttype Optional/Mandatory Allowed Values: ‘checking’, ‘savings’. Required for Electronic Check Payments. x
acctclass Optional/Mandatory Allowed Values: ‘personal’, ‘business’. Required for Electronic Check Payments. x
orderID Optional Must be a unique number. [Alpha characters not permitted.] If not submitted one will be generated using a date/time string. This number will be required to perform any future activity for an order, including but not limited to, voids and returns. x
shipname Optional Shipping name x
address1 Optional Shipping address - Line 1 x
address2 Optional Shipping address - Line 2 x
city Optional Shipping city x
state Optional Shipping State x
province Optional Shipping International Province. For international provinces outside of US & Canada, set the ‘state’ field’s value to ‘ZZ’ & include the province name here. x
zip Optional Shipping zip x
country Optional Shipping country x
shipcompany Optional Shipping company name x
shipphone Optional Shipping phone number x
comments Optional Optional Used to add comments to confirmation email x
tax Optional Sales tax charge (for level 2 processing - 00.00 will be submitted if no tax value is passed) x
uname Optional/Mandatory Customer’s username (required when doing Membership Management subscription sign-ups) x
passwrd1 Optional/Mandatory Customer’s password (required when doing Membership Management subscription sign-ups) x
passwrd2 Customer’s password [for verification] (required when doing Membership Management subscription sign-ups) x
suppress_unpw Optional When set to ‘yes’, will suppress the selection of username & password on the payment billing & summary pages. A unique username/password will be automatically created for the customer instead. [Note: if you want the customer to see the password, be sure to add the username/password fields to your customer conformation email template.] x n/a
receipt-company Optional Company name to show on POS receipts x x
receipt-address1 Optional Company address [line 1] to show on POS receipts x x
receipt-address2 Optional Company address [line 2] to show on POS receipts x x
receipt-city Optional Company city [line 1] to show on POS receipts x x
receipt-state Optional Company state to show on POS receipts x x
receipt-zip Optional Company zip code to show on POS receipts x x
receipt-country Optional Company country to show on POS receipts x x
receipt-phone Optional Company phone number to show on POS receipts x x
receipt-fax Optional Company fax number to show on POS receipts x x
receipt-email Optional Company email address to show on POS receipts x x
receipt-url Optional Company site URL to show on POS receipts x x
receipt-link Optional Fully qualified URL for a continue shopping link at bottom of POS receipts. Used to link POS receipt back to the merchant’s web site.Ex. http://www.yourdomain.com/continue.html x x
ponumber Optional Used for level 2 purchase cards. The value should be the purchase order number. If no ponumber is passed with a level 2 purchase card transaction, orderID will be used instead. x x
commcardtype Optional Used for level 2 purchase cards. Value should be ‘business’ for level 2 purchase cards and null for normal cards. x x
showcompany Optional If passed with a value of ‘yes’, this will invoke a field on the payment page asking for the customer’s company name. x x
showtitle Optional If passed with a value of ‘yes’, this will invoke a field on the payment page asking for the customer’s title. (Mr., Mrs., etc.) x x
showssnum Optional If passed with a value of ‘yes’, this will invoke a field on the payment page asking for the customer’s social security number. x x
showssnum4 Optional If passed with a value of ‘yes’, this will invoke a field on the payment page asking for the last four digits of the customer’s social security number. x n/a
cardissuenum - see note 5 Optional/Mandatory Card Issue Number, which is required for Maestro/Solo/Switch credit cards only. x
cardstartdate - see note 5 Optional/Mandatory Card Start Date, which is required for Maestro/Solo/Switch credit cards only. x
privacy_url Optional Fully qualified URL for your site’s privacy/security policy. Updates ‘Privacy & Security Policy’ link on the billing page, to point to your site’s policy. Defaults to our general privacy/security policy when omitted.Ex. http://www.yourdomain.com/privacy.html x n/a
return_url Optional Fully qualified URL for your site’s return/credit policy. Adds a ‘Returns & Credit Policy’ link to the billing page, which points to your site’s policy.Ex. http://www.yourdomain.com/returns.html x n/a
shipping_url Optional Fully qualified URL for your site’s privacy/security policy. Adds a ‘Shipping Policy’ link to the billing page, which points to your site’s shipping policy.Ex. http://www.yourdomain.com/shipping.html x n/a
privacy_statement - see note 6 Optional Used to replace the default privacy statement with your own custom privacy statement. Defaults to our general privacy statement when omitted. x n/a
mpgiftcard Optional Mercury Giftcard Card Number. x x
mpcvv Optional Mercury Giftcard CVV Number. Mandatory when specifying ‘mpgiftcard’. x x
sessionid Optional Used to pass a session ID with the transaction; so you can pre-store data on your system before the authorization, and then retrieve that data from your system after the authorization has been processed. x x
customname - see note 9 Optional Used to send name of your own custom field x x
customvalue - see note 9 Optional Used to send value of your own custom field x x

Notes:

  1. If the success/badcard/problem-link URL is a program/cgi/script, all value/name pairs passed to the Payment URL, along with those listed below, will be sent back to the URL upon completion of the authorization process. This will also be included at the bottom of the confirmation email sent to the merchant. When using a Transition Page, the IP address you’ll see at your URL will be the user’s browser IP address. When a Transition Page is not used, the IP doing the POST to your URL will be our payment server. (If you intend to authenticate the POST request from our server, please ensure you support the full ranges noted IPs within QA# ‘QA20011210174730’ in the Online FAQ, as the specific IP might change at any time - it will always be within one of those noted ranges). Your script is required to generate a web page as part of its execution. This web page will be displayed to the user’s browser.

  2. To include a list of the items purchased in the confirmation emails sent to both the customer and the merchant, four name/value pairs are required for EACH item purchased, in the following format. This information will also be stored in our database and can be accessed for report generation from the payment administrative interface.

  3. To include a list of the items purchased in the online receipt, four name/value pairs are required for EACH item purchased; see the ‘item#’, ‘cost#’, ‘quantity#’ & ‘description#’ fields. In addition, the ’easycart’ field must be set to ‘1’ & the ‘success-link’ field must not be defined.

    For POS receipt printers, you may need to adjust your print margins with your browser to make the POS receipts to print correctly. Adjusting the margin to 0.1" for all sides (left, right, top & bottom) has found to work best. You may also want to disable/remove all header/footer options in your browser’s print settings for cleaner looking POS receipts.

  4. When used with the online receipt, will add a signature line to the bottom of the online receipt.

  5. These variables are required if you are processing Maestro, Solo or Switch credit card authorizations. For other credit card types, these variables do not apply.

  6. You must also pass the variable ‘privacy’ with a value of ‘1’ for the custom privacy statement to display. Ex. <input type=“hidden” name=“privacy” value=“1”>

  7. This field must be used in conjunction with the product order itemization, which is stated in notes #2 & #3.

  8. “taxstate” - due to payment card industry (PCI) standards/regulations, the value delimiter format has changed from pipes ("|") to commas (",").

  9. To pass your own own custom fields, you will need to include both a customname# & customvalue# field. The “#” characters in the those fields is a number starting at 1 & increments with each custom name/value pair passed.

    For example, if you wanted to send custom variable ‘xyz’ with a value of ‘12345’ & another custom variable ‘abc’ with a value of ‘98765’, you would specify the following fields.

    customname1 = xyz
    customvalue1 = 12345
    customname2 = abc
    customvalue2 = 98765

    In the transaction response, you will receive the individual customname# & customvalue# fields provided, as well the combined values of those fields (for example: xyz=12345 and abc=98765)
Name Value
item# Model number of item# purchased.
cost# Cost of item#
quantity# Quantity of item#s purchased.
description# Description of item#

Repeat the above 4 name/value pairs for each item purchased incrementing the value of “#” for each additional item.
I.E. If 2 items were sold, then 8 name/value pairs would be submitted with the following names.
First Item Second Item
item1,cost1,desciption1,quantity1 item2,cost2,description2,quantity2

Response Fields

The response string will consist of all name value pairs submitted along with the name value pairs delineated below.
Variable Value
FinalStatus success/badcard/problem
avs-code See Table AVS-1 in Appendix A
auth-code Authorization Code
MErrMsg Response Message
orderID Unique numeric order id used to identify transaction for any future activity including voids and returns.
user-agent Browser or identifier of posting system.
ipaddress IP address of posting system