Checkout v2 Auth

Simple & Secure

Workbench
Sample Code

Overview

Offload the burden of hosting your own payment form and reduce your PCI scope with Forte's third-generation Checkout. Checkout's advanced features enable you to make quick and painless payments on your own site with just a few lines of code.

With Checkout you get:

  • A simple integration
    Start using Checkout today with customizable JavaScript that sits on top of your existing site.
  • Wallet storage functionality
    Save customer and payment method data to make checking out fast and easy.
  • Up-to-date customer data
    Enable customers to edit their own address and payment data to ensure you always have the correct information.
  • Advanced form field settings
    Default Checkout’s form fields to a value, empty, or hidden for full control over the data collected.
  • Granular amount settings
    Specify a non-editable amount to pay or a range of amounts for the customer.
  • Reduced cart abandonment
    Ensure your customer’s trust by running the entire checkout process from your site.

User Experience

Checkout’s Pay Now button uses an HTML form POST action with a signature to create the modal window. When the customer clicks the button with coded parameters on the client side, Forte servers read the parameters and populate the modal window. The JavaScript, https://checkout.forte.net/v2/js, includes a Forte name-spaced version of jQuery so as not to conflict with other client-side jQuery code.

Browser Compatibility

Checkout supports the three previous versions of the following browsers on a rolling basis:

Each time a new version of one of these browsers is released, Checkout begins supporting it and continues to support the previous two versions (and only the previous two). For example, if Checkout is currently supported on versions 9, 10, and 11 of a particular browser, when there is version 12 of this browser released, Checkout will support versions 10, 11, and 12 and will no longer support version 9.

This compatibility standard enables Checkout to use the latest and greatest security and performance features of the newest, most up-to-date browsers.

Merchant Configuration

Before coding the Pay Now button, you must set up a test account and perform the following tasks:

  1. Generate an API Access ID
  2. Generate an API Secure Key

Only these values are required for Checkout. The Secure Web Pay configuration options do not affect Checkout.

Generating Keys

Requests to Checkout require a hashed signature for authentication. This signature is created using your unique credentials, including a private key that you'll use when hashing signed elements. To integrate with Forte Checkout v2, use Forte’s Dex application to create your API credentials. For more information on creating a hash signature, see the Authentication section.

Complete the following steps to generate your API Access ID and API Secure Key:

  1. Log into your Dex Account.
  2. Search for and select the Home Organization for which you want to create the credential set. If your Home Organization is the same as your Logged-In Organization, skip this step.
  3. Select Developer > API Credentials from the Dex Main Menu.
  4. Click . The Create API Credentials screen displays.
  5. Enter a name for this set of API credentials in the Name Field. This field is required.
  6. Click . The API Access ID and API Secure Key values display in their corresponding fields.
  7. Click  next to the API Access ID and API Secure Key fields to record both of these newly generated values in a secure location to use in authenticating your requests.

NOTE: Once you save your API Secure Key, you will not be able to see the value again. If you forget your API Secure Key or it becomes compromised, you will have to regenerate the value in Dex.

Authentication

Checkout uses hash signatures for authentication.

Creating a Signature

The example below displays what information your signature should contain:

HMACSHA256("api_access_id|method|version_number|total_amount|utc_time|order_number|customer_token|paymethod_token",
"API Secure Key")

Use the following parameters when creating your hash signature:

Parameter

Description

Type

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

method

Supported types include the following:

sale
schedule
token
auth

string

version_number

2.0

string

total_amount

A string that represents the total amount of the transaction. NOTE: The total amount must be sent as a string as the button parameter. A possible side effect of total_amount being sent as a number is seemingly random, intermittent authentication failures.

string

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

order_number

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

string

customer_token

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

string

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

Send the hashed values in signature parameter, a character string of varying length (depending on the hash method) that is used to represent a specific transaction for a specific merchant in Forte Checkout.

Sample String

The following sections displays sample strings that will be hashed and their button attributes.

Single Amount

				
					"8dcd03dc50d5aeed2f221e7e88ee4d23|sale|2.0|10.00|636397036957980000|A1234||","eedce6b47748968641a6af8bcd4756fe"
				
			
				
					<button api_access_id="8dcd03dc50d5aeed2f221e7e88ee4d23"
			method="sale"
			version_number="2.0"
			location_id="115161"
			utc_time="636397036957980000" 
			hash_method="sha256"
			signature="44575464e3b99f8638858ac627eb9f03"
			callback="oncallback"
			total_amount="10.00"
			order_number="A1234">
				Pay Now</button>

Scheduled, Ranged Amount

				
					"8dcd03dc50d5aeed2f221e7e88ee4d23|schedule|2.0|1-9.5;5|636397071841460000|A1234|10047592|14554198","eedce6b47748968641a6af8bcd4756fe"
				
			
				
					<button api_access_id="8dcd03dc50d5aeed2f221e7e88ee4d23"
			method="schedule"
			customer_token="10047592"
			paymethod_token="14554198"
			version_number="2.0"
			location_id="115161"
			utc_time="636397071841460000"
			hash_method="sha256"
			signature="1df5eb88210898c04e5f48da5086dadb"
			callback="oncallback"
			total_amount="1-9.5;5"
			schedule_start_date="1/1/2018"
			schedule_frequency="weekly"
			schedule_quantity="12"
			schedule_continuous="false"
			order number="A1234">
				Subscribe</button>

Selection Amount

				
					"8dcd03dc50d5aeed2f221e7e88ee4d23|sale|2.0|{20,40,60,80,100,0};20|636397073365110000|||","eedce6b47748968641a6af8bcd4756fe"
				
			
				
					<button api_access_id="8dcd03dc50d5aeed2f221e7e88ee4d23"
			method="sale"
			version_number="2.0"
			utc_time="636397073365110000"
			location_id="115161"
			hash_method="sha256"
			signature="216760998032e94aa16ddb2293d4cf05"
			callback="oncallback"
			total_amount="{20,40,60,80,100,0};20">
				Select Amount</button>

Ranged Selection Amount with Labels

				
					"8dcd03dc50d5aeed2f221e7e88ee4d23|sale|2.0|{1375.23,1573.66,56.99,0|Total outstanding,Last statement balance,Minimum balance,Specify different amount}|636397074849820000|||","eedce6b47748968641a6af8bcd4756fe"
				
			
				
					<button api_access_id="8dcd03dc50d5aeed2f221e7e88ee4d23"
		method="sale"
		version_number="2.0"
		location_id="115161"
		utc_time="636397074849820000"
		hash_method="sha256"
		signature="fec0347215626c217b03190960fa5744"
		callback="oncallback"
		total_amount="{1375.23,1573.66,56.99,0|Total Outstanding,Last Statement,Minimum Balance,Specify Different Amount}">
				Select Amount with Labels</button>

Coding the Button

To create the Pay Now button for your site, you will first need to generate your API Access ID and API Secure Key in Dex (see Merchant Configuration).

Endpoints

The following scripts invoke Checkout and should be placed in the <head> section of your website:

  1. https://sandbox.forte.net/checkout/v2/js for sandbox testing
  2. https://checkout.forte.net/v2/js for production

Customizing the Button

The code below represents the minimal html code required to generate a payment button. If you want Checkout to capture additional information, such as a customer's shipping address, you must include the additional parameters listed below.

				
					<!DOCTYPE html>
	<script type="text/javascript" src="https://sandbox.forte.net/checkout/v2/js" data-rocket-defer defer></script>
	<button api_access_id="apiaccessid"
		method="sale"
		version_number="2.0"
		location_id="115161"
		utc_time="UTCtime"
		order_number="ASX458956"
		signature="sha256signature">
		Pay Now</button>

Parameters

Parameter

Description

Attributes

Req

Type

Dex Transaction Reference

method



Supported types for this required parameter include the following:


sale - creates an ad-hoc transaction*


schedule - used to schedule a single, future-dated transaction or create a schedule

of recurring transactions.

NOTE: When creating a schedule, client and payment method tokens are automatically returned.


token - creates both customer and payment method tokens or generates a new payment method token for an existing customer. No transaction is generated.


auth - authorizes the payment method


[max length=8]

N

R

string

Action

allowed_methods

Pass all allowable payment methods as a comma-delimited string (e.g., allowed_methods=visa,mast,disc,amex,echeck). The first payment method in the list will be the default payment method that the Checkout modal displays. For example, if the button code includes allowed_methods=echeck,visa,mast,disc, then the echeck payment fields will display by default.
NOTE: eCheck can only be the first entry in allowed_methods when swipe=false. Supported payment methods include the following:


• visa

• mast

• amex

• dine

• jcb

• disc

• echeck


[max length=6]

N

O

string

--

hash_method

Supported values include the following:


• sha256*

• sha1

• sha256


[max length=6]

N

R

string

--

version_number

2.0*

[max length=4]

N

R

string

--

location_id


The location (Merchant ID) under which the transaction should be processed (e.g., 115161).


[max length=9]

N

R

string

Location ID

total_amount

See Configuring Amounts for information on coding these

values.


Amount Configurations can include the following options:


• Single amounts

• Range of amounts

• Choice of amounts

• Amount choices with a default amount displayed

• Amount selections with a ranged amount displayed

• Amount selections with descriptive text next to each displayed amount

• Amount selections with descriptive text and a ranged amount



NOTE:


The value of the total_amount parameter must be greater than zero.


NOTE: The total amount must be sent as a string as the button parameter. A possible side effect of total_amount being sent as a number is seemingly random, intermittent authentication failures.

Y

O

string

Authorization Amount

tax_amount


The sales tax amount of the transaction. To make this field editable, use the edit attribute when passing your button code (i.e., tax_amount_attr="edit").


For EMV procurement card transactions, this field becomes required and automatically displays on the Checkout modal once the customer selects the This is a Procurement Card checkbox.

Y

O

dec

Tax Amount

consumer_id

A merchant-defined string used to identify the customer.


[max length=15]

N

O

string

Customer ID

order_number

A string that represents the order number associated with a

transaction.
NOTE: order_number is unique for each PayPal transaction and is identified as invoice number in PayPal.

N

O

string

Order ID

save_token

Use one of the following values for this parameter:


a. true = If the transaction completes, Checkout will create and save both customer and payment method tokens.


b. false = Checkout will not create or save the customer and payment method tokens.*


NOTE: For scheduled transactions, the merchant

must pass predefined customer and/or payment method tokens or set save_token=true.

N

O

bool

--

customer_token

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


[max length=26]

N

O

string

--

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]

N

O

string

--

sec_code


Enables merchants to pass custom SEC codes for echeck sale, auth, and schedule 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]

N

O

string

SEC Codes

collect_shipping_address

Use one of the following values for this parameter:


a. true = Checkout collects the shipping address from the customer


b. false = No shipping entry is allowed*

N

O

bool

--

entered_by

Name of the user entering the transaction.


[max length=25]

N

O

string

Entered By

swipe

Use one of the following values for this parameter:


true = Indicates that Forte Checkout should accept input from a MagTek card reader to capture cardholder data.


false = Indicates that the merchant or customer must manually ent