Checkout v2 Auth
Simple & Secure
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:
- Firefox
- Chrome
- Safari
- Microsoft Edge
- Mobile – Chrome, Safari, and Firefox
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:
- Generate an API Access ID
- 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:
- Log into your Dex Account.
- 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.
- Select Developer > API Credentials from the Dex Main Menu.
- Click . The Create API Credentials screen displays.
- Enter a name for this set of API credentials in the Name Field. This field is required.
- Click . The API Access ID and API Secure Key values display in their corresponding fields.
- 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 | 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 <script> var button = $('button[api_access_id]'); $.getJSON('https://sandbox.forte.net/checkout/getUTC?callback=?').done(function (utc) { button.attr('utc_time', utc); }); </script>
<?php $curlData = (curl_exec($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"
Scheduled, Ranged Amount
"8dcd03dc50d5aeed2f221e7e88ee4d23|schedule|2.0|1-9.5;5|636397071841460000|A1234|10047592|14554198","eedce6b47748968641a6af8bcd4756fe"
Selection Amount
"8dcd03dc50d5aeed2f221e7e88ee4d23|sale|2.0|{20,40,60,80,100,0};20|636397073365110000|||","eedce6b47748968641a6af8bcd4756fe"
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"
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:
https://sandbox.forte.net/checkout/v2/js
for sandbox testinghttps://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.
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.
[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. • visa • mast • amex • dine • jcb • disc • echeck [max length=6] | N | O | string | -- |
hash_method | N | R | string | -- | |
version_number |
[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. | 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.
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
| 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.
|