Forte REST API v3
Forte’s REST API enables merchants and partners to perform a variety of powerful tasks such as creating and updating credit card, echeck, and scheduled transactions, securely managing customer and payment data, querying and tracking settlement information, and creating and submitting merchant applications for new Forte organizations and locations. Forte uses standard HTTP protocols within a PCI-compliant architecture that is simple to integrate.
Getting Started
To begin using Forte's REST web services, complete the following steps:
- Sign up for a Test Account.
- Create your API Credentials.
- Create your Authentication Headers.
- Craft a call.
- Test your calls.
Step 1: Sign Up for a Test Account
If you are a merchant, navigate to the Forte Developer's Test Account sign-up page and enter your First Name, Last Name, Company Name, and Email address in the applicable fields. Forte uses this email address for verification purposes and as your Username for registering and signing into Dex, Forte's newest payment processing portal.
If you are a partner, contact Forte's Sales Team and request a partner sandbox account. Partner accounts in Dex have different permissions and different menu options.
After you verify your email address, Forte sends you a Dex invitation email where you can register for a sandbox account. Dex registration requires a mobile phone number that can receive SMS messages for account verification.
After registering and verifying your mobile number, Dex logs you in with your Organization ID. Your Organization ID represents a legal entity that can own multiple sub-organizations (for partners) or multiple locations (for merchants) as well as the customers, payment methods, and transactions that belong to those locations. Every request call made to the Forte REST API must contain the organization_id
within the URI.
Every Dex sandbox account also comes with a Location ID. Your Location ID represents locations, which are processing endpoints that merchant organizations use to initiate transactions (in Forte legacy applications like Virtual Terminal, locations were known as MIDs). Locations own all the transaction data including sensitive payment method data and tokens. Tokens are random, alpha-numeric strings that represent stored, encrypted data. Tokenization is a common practice in the payment industry to protect sensitive data.
For questions or help with Dex registration or setup, contact Forte Technical Support at 888-235-4635 option 5.
Step 2: Create Your API Credentials
To begin integration with Forte's REST API, you first have to create your API authentication credentials. These include an API Access ID, which acts as your username, and an API Secure Key, which acts as a password. You will create and maintain these credentials in Dex.
Complete the following steps to generate your API Access ID and API Secure Key:
- From your Google Chrome browser, log into your Dex Account.
- Select Developer > API Credentials from the Dex Main Menu.
- Click the CREATE button. The Create API Credentials screen displays.
- Enter a name for this set of API credentials in the Name field.
- Click the CREATE NEW API KEY button. The API Access ID and API Secure Key values display in their corresponding fields.
- Click the COPY button 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 REST API requests.
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.
Step 3: Create Your Authentication Headers
Requests to Forte's REST API must be authenticated using the Authorization
header field and the custom header property, X-Forte-Auth-Organization-Id
.
The Authorization Header
Forte's REST web services rely on Basic access authentication over HTTPS using the API Access ID and an API Secure Key as the username and password values. These unique values are combined with a colon and then encoded using the RFC2045-MIME variant of Base64. The encoded string is then added to the HTTP Authorization
header. For example, if you created the following API credentials:
-
API Access ID =
315c7649520edde96c5cbad59a5b265f
-
API Secure Key =
c233f2958bd855d09d98397e74950640
The value of the Authorization
header field would look like the following:
Authorization=Basic MzE1Yzc2NDk1MjBlZGRlOTZjNWNiYWQ1OWE1YjI2NWY6YzIzM2YyOTU4YmQ4NTVkMDlkOTgzOTdlNzQ5NTA2NDA=
Several different online tools can help you create your `Authorization` header, such as Postman. You can also add Base64 encoding to HMAC requests to automatically convert the API Access ID and API Secure Key values into the encoded ASCII string. To do so, use the following code:
Convert.ToBase64String(Encoding.Default.GetBytes(APIAccessID + ":" + APISecureKey)).Trim()
The X-Forte-Auth-Organization-Id Header
The custom header property X-Forte-Auth-Organization-Id
specifies at which organization Forte should authenticate the request. A partner can authenticate his or her Organization ID in the X-Forte-Auth-Organization-Id
header property and then can access merchant sub-organizations by specifying the merchant Organization ID in the URI of the request.
The Accept Header
Forte’s REST service supports Content Negotiation through the Accept
header sent in the request call.
The default value for Accept
headers is application/json
which returns JSON responses. However, you can also use application/xml
which returns XML responses.
The Content-Type Header
The Content-Type
header is only required for POST and PUT calls. Like the Accept
header, the Content-Type
header supports both application/json
and application/xml
. The default value for Content-Type
headers is application/json
.
Putting it All Together
In summary, you must include the following headers for every POST and PUT request call made to the Forte REST API. For GET and DELETE request calls, the Content-Type
header is optional:
Content-Type – This header is only required for POST and PUT calls. This field defaults to application/json, but also supports application/xml.
Accept – Defaults to application/json, but also supports application/xml
X-Forte-Auth-Organiza