Parameter

Description

Type

Req

api_access_id

The organization-specific API Access ID value that you created in Dex. See the Merchant Configuration for information on creating this value.

string

R

method

Supported types include the following:

token To Save Payment Method and Generate a Token
sale To Process a Transaction

string

R

version_number

2.0

string

R

total_amount

A string that represents the total amount of the transaction. NOTE: If you use it solely to generate a token, it should be empty..

string

C

utc_time

A date-time value (since 01/01/0001 00:00:00) that marks the day and time the request was sent to Checkout in ticks. Checkout will only accept utc_time values that are 20 minutes before the current time or 10 minutes after the current time. Requests expire after 10 minutes to prevent malicious users from capturing requests and resubmitting them at a later time.

Checkout provides an API that returns the correct UTC time from Forte’s server. Using this server-side value prevents inadvertent expiration errors from client PCs that do not have the correct local time set.

Use the following get UTC API URLs in your code to retrieve UTC ticks from Forte's servers:

• https://checkout.forte.net/getUTC?callback=? //production
• https://sandbox.forte.net/checkout/getUTC?callback=? //sandbox
The following script returns the correct UTC time for the hash:

<script> var button = $('button[api_access_id]'); $.getJSON('https://sandbox.forte.net/checkout/getUTC?callback=?').done(function (utc) { button.attr('utc_time', utc); }); </script>

You can also use the following PHP/Curl code sample to fetch the UTC time from the getUTC API URL displayed above (e.g., ?(XXXXXXXXXXXX643793); where XXXXXXXXXXXX643793 is the UTC time value).

<?php
function utc() {
$curlUTC = curl_init();
curl_setopt($curlUTC, CURLOPT_URL, 'https://checkout.forte.net/getUTC?callback=?');
curl_setopt($curlUTC, CURLOPT_BINARYTRANSFER, true);
curl_setopt($curlUTC, CURLOPT_RETURNTRANSFER, true);

$curlData = (curl_exec($curlUTC));
$positionOfOpeningParenthesis = stripos($curlData,"(");
$positionOfClosingParenthesis = stripos($curlData,")");
$utc = substr($curlData,$positionOfOpeningParenthesis+1,$positionOfClosingParenthesis-2);
return $utc;
curl_close($curlUTC);
}

string

R

order_number

A string that represents the order number associated with a transaction.

string

O

customer_token

An alphanumeric ID used to reference a customer. Forte stores the token and its associated information.

string

O

paymethod_token

An alphanumeric ID used to reference stored payment information (card or eCheck) for a customer. Forte stores the token and its associated information.

string

O

R=Required

O=Optional

C=Conditional

Parameter

Description

Req

Type

iCG iFrame Equivalent

method

Supported types include the following:

token To Save Payment Method and Generate a Token
sale To Process a Transaction

R

string

iFrame Configuration

allowed_methods

• visa
• mast
• amex
• dine
• jcb
• disc
• echeck

O

string

iFrame Configuration. You can define to use ECheck or Credit Card or both options.

hash_method

R

string

N/A

version_number

R

string

N/A

location_id

R

string

SiteID

total_amount

O

string

amount

tax_amount

O

dec

salesTax

consumer_id

A merchant-defined string used to identify the customer.

[max length=15]

O

string

custId

save_token

1. true = If the transaction completes, Checkout will create and save both customer and payment method tokens.
2. false = Checkout will not create or save the customer and payment method tokens.*

3. 
   NOTE: For scheduled transactions, the merchant
   must pass predefined customer and/or payment method tokens or set save_token=true.

O

bool

saveTokenDisabled

customer_token

An alphanumeric ID used to reference a customer. Checkout accepts/returns a string for this parameter.

[max length=26]

O

string

N/A

paymethod_token

An alphanumeric ID used to reference stored payment information (card or echeck) for a customer. Checkout accepts/returns a string for this parameter.

[max length=26]

O

string

N/A

sec_code

Enables merchants to pass custom SEC codes for echeck sale transactions. If a SEC code is not passed or if the value of this field is blank/null, Forte Checkout uses the default WEB. The SEC codes you're allowed to send depend on your merchant setup.

[max length=3]

O

string

entryClassCode

entered_by

Name of the user entering the transaction.

[max length=25]

O

string

N/A

button_text

Enables the user to customize the text of the payment button. If the user does not pass a value in this parameter, Checkout reverts to the following default values according to the methodof the transaction:

sale= Authorize

token = Create Token

O

string

iFrame Configuration, default value "Continue"

expire_utc

Enables the merchant to define a UTC expiration date-time value for the transaction in ticks.

When expire_utc is not set, Forte Checkout handles the session timeout by warning the user every 20 mins and allowing them to extend the session, if required. As part of being ADA compliant and as a best practice, we strongly recommend that expire_utc is not used by the customer to set expiry time.

When expire_utc is used by the customer, Forte Checkout will only warn the user when the session is about to expire. This is only partially ADA compliant and hence not recommended. If the customer attempts a transaction after this set time has expired, Checkout’s modal automatically closes, and he or she must generate a new Checkout form.

NOTE: This parameter only applies to the sale and schedule methods.

NOTE: DO NOT use this parameter to set expiry time and allow Forte Checkout to handle the session time out.

O

string

N/A

reference_id

A merchant-defined string that identifies the transaction.

[max length=15]

O

string

N/A

xdata_#

Up to nine fields (1–9) of extra data that you can associate with a schedule or a transaction. Each field can contain up to 80 characters. This data does not display on the Checkout modal window; however, the merchant can join this information to the webhook response to provide a more detailed description of the transaction. NOTE: Values within this field cannot contain double quotation characters (i.e., "text"); Forte Checkout supports single quotation characters (i.e., 'text'). If you require double quotation characters within this value, use HTML escape characters to ensure the information properly displays (e.g., xdata_1="Marco's “Place”").

[max length=255]

O

string

custom1, custom2, custom3

Billing Parameters

billing_name

The first and last name of the customer associated with this billing address.

[max length=50]

O

string

firstName, lastName

billing_company_name

The company name associated with the billing address.

[max length=50]

O

string

company

billing_street_line1

The first line of the customer's billing address.

[max length=35]

O

string

street1

billing_street_line2

If required, the second line of the customer's billing address (e.g., Suite or Apartment number).

[max length=35]

O

string

street2

billing_locality

The locality/city/town/village of the customer's billing address.

[max length=25]

O

string

city

billing_region

The region/state/province of the customer's billing address.

[max length=10]

O

string

state

billing_postal_code

The postal/zip code of the customer's billing address. NOTE: This field is not required for echeck payments unless you pass billing_postal_code_attr="required" in the request or address verification services (AVS) are enabled.

O

string

zip

billing_country

The Country code of the customer's billing address (includes military states) in ISO 3166-1 alpha-2 format.

[max-length=2]

O

string

N/A

billing_email_address

The email address associated with the customer's physical billing address.

[max length=50]

O

string

email

billing_phone_number

The phone number associated with the customer's physical billing address.

[max length=15]

O

string

phone

R=Required

O=Optional

C=Conditional

Attribute

Description

Example

edit

Makes the field editable for the customer

a. billing_name_attr="edit"
b. billing_name_attr="edit,required"

required

Makes the field required for the customer

a. billing_postal_code_attr="required"
b. billing_postal_code_attr="edit,required"

hide

Hides the field from the customer; however, Checkout passes the parameter with the transaction behind the scenes. This attribute cannot be combined with the edit or required attributes.

billing_name_attr="hide"

Error Message

"Routing number is invalid."

"The parameter version_number is required."

"Email address is invalid."

"State is not valid."

"Invalid authentication."

"No allowed_method is available."

"Invalid parameter api_access_id."

"The browser you are using is not supported. Please download the latest version of your browser to use Checkout."

"The parameter api_access_id is required."

"The browser you are using is not supported. Checkout supports the latest versions of the following browsers: Internet Explorer, Firefox, Chrome, and Safari."

"Please either disable compatibility view or upgrade your browser to proceed."

"Scheduled transactions are not allowed for service fee merchants."

"Invalid parameter schedule_quantity: "______."

"Invalid parameter schedule_continuous: "______", Use true/false."

"Invalid schedule_quantity for continuously scheduled transaction."

"Invalid parameter schedule_frequency: "______". Use weekly, bi-weekly, monthly, bi-monthly, quarterly, semi-annually, annually. Use 0 for single future transaction."

"Invalid schedule_quantity for one-time future scheduled transaction."

"Invalid schedule_continuous for one-time future scheduled transaction."

"The parameter schedule_start_date must be a future date."

"Invalid parameter schedule_start_date: "______."

"The total_amount passed cannot be used with a method of schedule."

"Invalid parameter total_amount for scheduled transaction: "______."

"The parameter utc_time is required."

"Scheduled transactions require either setting save_token=true or passing in customer/payment token."

"Invalid parameter save_token: "______." Use true/false."

"Invalid parameter swipe: "______." Use true false."

"Invalid parameter allowed_methods: "______." Use visa/mast/disc/amex/echeck."

"Invalid total_amount for scheduled transaction."

"No payment method is available for the scheduled transaction."

"No payment method is available."

"This paymethod_token is not allowed."

"Invalid parameter hash_method: "______." Use sha256."

"Invalid parameter method: "______." Use sale/schedule/token."

"Invalid parameter request_id: "______."

"The paymethod_token "______" does not exist."

"The customer_token "______" does not exist."

"The paymethod_token "______" is invalid: it does not belong to the customer."