Applications

Hi there! Welcome to Dex, Forte's latest and greatest payments application. With Dex, you can view, create, and manage all your transaction data—including customers, payment methods, addresses, and schedules—in one convenient place. You can also view and maintain your merchant account, keep track of your funding entries, resolve disputed transactions, and generate API credentials to connect Dex with your third-party applications.

Overview

Forte's Merchant Application Portal provides Partners with a streamlined solution for quickly onboarding merchants to your payments platform. Whether you need a simple payments gateway to connect your merchant to a credit card processor or a full-service, multichannel payment processing solution—we've got you covered. Partners can capture merchant applications via two different integration channels:

  • Connecting your platform to Forte via the applications resource in our REST API
  • Sending branded applications to merchants via email through the Dex Merchant Application Portal

With either integration method, you have the ability pick and choose from Forte's value-added services (e.g., Forte Verify or Account Updater) and enjoy faster decisioning with Forte's proprietary, automated underwriting checks.

Using Forte's Underwriting Services

Underwriting can be an expensive, risky, time-consuming hassle. We've eliminated that headache with our expedited underwriting protocol. We run each application you submit to Forte through a sequenced series of automated checks with a combination of services to validate a merchant's criminal, business, and credit histories. Any result that falls outside the threshold of acceptable risk is sent to our Credit Team for manual decisioning. Merchant applications that pass each check are automatically approved and immediately sent to our Enrollment Team for onboarding. This streamlined process creates a faster, more consistent onboarding process so that merchants can be up and running within days instead of weeks.

Partners that prefer to conduct their own underwriting or already have an underwriting solution in place can opt out of these checks. For these types of partner accounts, all applications submitted to Forte are automatically forwarded directly to our Enrollment Team for onboarding. While this provides an even faster onboarding solution, the partner assumes all legal and financial liability for merchants that use Forte's services. For questions or more information on these options, consult your Account Manager.

REST API Integration Overview

With the REST API integration option, partners can use their own online form templates and the parameters of Forte's REST API to securely capture merchant information. Submitting merchant data this way provides both you and the merchant an almost immediate application response and expedites the merchant onboarding process.

With the REST API integration option, partners can use their own online form templates and the parameters of Forte’s REST API to securely capture merchant information. Submitting merchant data this way provides both you and the merchant an almost immediate application response and expedites the merchant onboarding process.

Getting Started with REST

Before you can begin accepting applications, you'll need to create your API credentials and Authentication Headers and send a few test calls to make sure your form template is capturing the required parameters of the applications object. Before you begin, we recommend downloading Postman. Postman is a free, intuitive API development tool you can use to test Forte's REST API. We've created a collection of all the request calls detailed in Forte's REST API specification, which you can easily import into your Postman app for testing.

Step 1: Create Your API Credentials

To begin integration with Forte's REST API, you first have to create your API authentication credentials. These include an Access ID, which acts as your username, and an Secure Key, which acts as a password. We'll use these values to create your encoded Authorization header, which is required for every request you make via our API. Complete the following steps to create your API credentials:

  1. Log into your Dex account.
  2. Navigate to Developer > API Credentials. The API Credentials Datagrid displays. NOTE: If you do not see the Developer menu option, contact Forte Technical Support (888-235-4635 option 3) and request that they adjust your permissions so that you can create, update, and delete API credentials.
  3. Click the Create button. The Create API Credentials Screen displays.
  4. Enter a name for this API credential set in the Name field. For our purposes, we'll name our credential set Applications.
  5. Click the Create New API Key button. Dex displays the Access ID and Secure Key values in their respective fields.
  6. Use the Copy links to copy the Access ID and Secure Key values and store them in a secure location. NOTE: Once you copy and save your Secure Key value, you will not be able to see the value again. If you forget your Secure Key or it becomes compromised, you will have to regenerate the value in Dex.
  7. Click the Back link to return to the API Credentials Datagrid. You should see your credentials displayed at the top of the list.
  8. Repeat steps 3–7 to create additional credential sets.

Step 2: Get Your Fee ID

The fee_id parameter in the applications object identifies the rate plan that Forte created for you when you enrolled as a Partner. Rate plans correspond to the services or combination of services you want to offer to your merchants via the Forte platform. Rate plans can include pricing for the following combination of services:

  • eCheck Only
  • Credit Card Only
  • Gateway Only
  • Verification Only
  • eCheck + Credit Card
  • eCheck + Gateway
  • eCheck + Credit Card + Verification
  • Credit Card + Verification

You must include the fee_id parameter for every POST request made to the applications endpoint. Different rate plans correspond to different pricing arrangements and underwriting requirements for each merchant that applies. You should have receive your rate plan fee_id values from your Forte Account Manager; however, you can also look up the rate plans in Dex to ensure your merchant application template is referencing the correct fee_id.

To look up your rate plans, access your home organization and complete the following steps:

  1. Navigate to the Rate Plans Datagrid (Merchant Application > Rate Plans). Search for the rate plan by Name or Fee ID and/or use the Status, Services, and/or Sales Rep filters to find the desired rate plan. The Rate Plans Datagrid displays the fee_id value in the ID column.
  2. To view the details of a rate plan and ensure the pricing and Merchant Services Agreement(s) are correct, click the row on which the rate plan is displayed on the Rate Plans Datagrid. That Rate Plan's Details Screen displays. From this screen you can view the detailed pricing configured for this rate plan, track which of your merchants have completed their applications, and monitor the progress of each submitted application. You can also confirm the fee_id value, which displays in the "General Information" card on the Rate Plan's Detail Screen.

Step 3: Create Your Authentication Headers

At a minimum, 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, given that we created the following credentials set in Step 1,

  • API Access ID = 315c7649520edde96c5cbad59a5b265f
  • API Secure Key = c233f2958bd855d09d98397e74950640

the Authorization header we would submit with each API request would look like the following:

Authorization=Basic MzE1Yzc2NDk1MjBlZGRlOTZjNWNiYWQ1OWE1YjI2NWY6YzIzM2YyOTU4YmQ4NTVkMDlkOTgzOTdlNzQ5NTA2NDA=

You can quickly generate this value in Postman by completing the following steps:

  1. In a new tab, enter a test URI for the request. We'll use https://sandbox.forte.net/api/v3/organizations/org_300005/locations/loc_155161/customers/cst_SoGUG6mcLUS1nVzYBIbk3g/transactions/.
  2. Click the Authorization tab and select Basic Auth from the Type dropdown menu.
  1. In the Username and Password field, enter the API Access ID and API Secure Key you created earlier in Dex. For our example, we’ll use the following values:
    • API Access ID = 315c7649520edde96c5cbad59a5b265f
    • API Secure Key = c233f2958bd855d09d98397e74950640
  2. Click the Preview Request button.

5. Postman automatically creates the Authorization header and displays it on the Headers tab.

This method works great if you’re using Postman to test your calls; however, if you’d rather test using another program or method you can also add Base64 encoding to HMAC requests to automatically convert the API Access ID and API Secure Key values into an encoded ASCII string. To do so, use the following code:

 
				
					Convert.ToBase64String(Encoding.Default.GetBytes(APIAccessID + ":" + APISecureKey)).Trim()

If you’re including the authentication request directly into the URI, you must encode the plus sign character (+) using %2B; and the forward slash character (/) using %2F;.

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. The value of this header is also known as the home_organization_id.

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-Organization-Id - A custom header property that specifies at which organization Forte should authenticate the request (i.e., the home_organization_id)
  • Authorization - The API Access ID and API Secure Key encoded using the RFC2045-MIME variant of Base64.

The following code sample displays these headers within a GET call to the applications resource in the Sandbox environment.

				
					curl -X GET
   --H "Authorization: Basic MzE1Yzc2NDk1MjBlZGRlOTZjNWNiYWQ1OWE1YjI2NWY6YzIzM2YyOTU4YmQ4NTVkMDlkOTgzOTdlNzQ5NTA2NDA="
   --H "X-Forte-Auth-Organization-Id: org_300005"
   --H "Accept: application/json"

"https://api.forte.net/v3/organizations/org_300005/applications/

The following figure shows what the Headers tab in Postman should display for every POST or PUT request you send (GET and DELETE requests do not require the Content-Type header). NOTE: Some request calls, like POSTs to the documents resource requires additional headers. See the full REST API v3 reference for more details.

Step 4: Craft your Calls

ID Formatting

All resources in Forte’s REST API require object prefixing to identify the specific resource and aid in troubleshooting in the event of errors. The resource ID is a combination of the object prefix with the unique ID number or token that Forte assigns to the resource when a user creates it. The following table displays the prefixing standards used by Forte for resources applicable to applications. For a full list of resource prefixing standards, see the full REST API v3 reference:

Supported Actions

Currently, partners can only create and search for the applications resource using the following HTTP verbs:

Base URI

When crafting a call, append the resource endpoint to the following base URIs for the specified environments:

Endpoints

Use the following endpoint URLs in the specified environments to create or search for merchant applications. NOTE: The organization_id referneced in the URL must be the home_organization_id of the partner.

General Request Filters

In addition to the filters listed above in the GET call that returns all applications submitted for an organization, you can also use the following general request filters to control the order and page size of your results set.

The Applications Object

The applications object is where the magic happens. Use these parameters when building your template to capture your merchant's data and automatically submit it to Forte's Underwriting and decisioning queues (or Forte's Enrollment team if you're a Direct-to-Enrollment partner). If required, you can upload supporting documentation for applications using the documents object. The table below uses the following abbreviations and symbols to denote whether or not a parameter is required, optional, conditional, or return-only:

  • R = Required parameter for all applications
  • O = Optional parameter
  • C = Conditional parameter for applications with specific ownership percentages and/or legal structures. See the notes within the table.
  • — = A return-only parameter that does not need to be included in the request.

Generating the Risk Session ID

The risk_session_id parameter offers partners a method of device identification/profiling and malware detection for merchant applications. As part of Forte's underwriting services, this parameter helps to identify client devices that may have been used for fraud in the past or that have inconsistent characteristics—such as a US-based IP address with Russian language settings. This parameter is required for partners using Forte's underwriting services but optional for Direct-to-Enrollment partners.

The script that generates the value for the risk_session_id parameter must be embedded on the page where the merchant applicant will be for five or more seconds. Profiling can only properly occur when the session runs on the applicant's browser for a minimum of five seconds. Additionally, the applicant's browser or the front-end software you're using to collect merchant applications must have JavaScript enabled.

To add the risk_session_id parameter to the applications object, complete the following steps:

  1. Generate a unique risk_session_id code that fulfills the formatting requirements described in the applications resource reference table above by using the following PHP code sample:
				
					<html><body>
<?php $a=uniqid();
echo $a;
?>
<script data-minify="1" type="text/javascript" src="https://developers.forte.net/wp-content/cache/min/1/fp/tags.js?ver=1730215204" data-rocket-defer defer>
</script>
<noscript>
<iframe style="width: 100px; height: 100px; border: 0;position: absolute; top: -5000px;" src="https://img3.forte.net/tags?org_id=xdzpgyj7&session_id=<?php echo $a;?>&pageid=1">
</iframe>
</noscript>
<script>var rocket_beacon_data = {"ajax_url":"https:\/\/developers.forte.net\/wp-admin\/admin-ajax.php","nonce":"a5d3cc70bf","url":"https:\/\/developers.forte.net\/applications-partner","is_mobile":false,"width_threshold":1600,"height_threshold":700,"delay":500,"debug":null,"status":{"atf":true,"lrc":true},"elements":"img, video, picture, p, main, div, li, svg, section, header, span","lrc_threshold":1800}</script><script data-name="wpr-wpr-beacon" src='https://developers.forte.net/wp-content/plugins/wp-rocket/assets/js/wpr-beacon.min.js' async></script><script>class RocketElementorAnimation{constructor(){this.deviceMode=document.createElement("span"),this.deviceMode.id="elementor-device-mode-wpr",this.deviceMode.setAttribute("class","elementor-screen-only"),document.body.appendChild(this.deviceMode)}_detectAnimations(){let t=getComputedStyle(this.deviceMode,":after").content.replace(/"/g,"");this.animationSettingKeys=this._listAnimationSettingsKeys(t),document.querySelectorAll(".elementor-invisible[data-settings]").forEach(t=>{const e=t.getBoundingClientRect();if(e.bottom>=0&&e.top<=window.innerHeight)try{this._animateElement(t)}catch(t){}})}_animateElement(t){const e=JSON.parse(t.dataset.settings),i=e._animation_delay||e.animation_delay||0,n=e[this.animationSettingKeys.find(t=>e[t])];if("none"===n)return void t.classList.remove("elementor-invisible");t.classList.remove(n),this.currentAnimation&&t.classList.remove(this.currentAnimation),this.currentAnimation=n;let s=setTimeout(()=>{t.classList.remove("elementor-invisible"),t.classList.add("animated",n),this._removeAnimationSettings(t,e)},i);window.addEventListener("rocket-startLoading",function(){clearTimeout(s)})}_listAnimationSettingsKeys(t="mobile"){const e=[""];switch(t){case"mobile":e.unshift("_mobile");case"tablet":e.unshift("_tablet");case"desktop":e.unshift("_desktop")}const i=[];return["animation","_animation"].forEach(t=>{e.forEach(e=>{i.push(t+e)})}),i}_removeAnimationSettings(t,e){this._listAnimationSettingsKeys().forEach(t=>delete e[t]),t.dataset.settings=JSON.stringify(e)}static run(){const t=new RocketElementorAnimation;requestAnimationFrame(t._detectAnimations.bind(t))}}document.addEventListener("DOMContentLoaded",RocketElementorAnimation.run);</script></body>
</html>

2. Add the generated value to the following script (i.e., in place of UNIQUE_SESSION_ID). This script can be executed only once by the applicant’s browser.

				
					<script data-minify="1" type="text/javascript" src="https://developers.forte.net/wp-content/cache/min/1/fp/tags.js?ver=1730215204" data-rocket-defer defer>
</script>
<noscript>
<iframe style="width: 100px; height: 100px; border: 0;position: absolute; top: -5000px;" src="https://img3.forte.net/tags?org_id=xdzpgyj7&session_id=UNIQUE_SESSION_ID&pageid=1">
</iframe>
</noscript>
  1. When generating the applications POST request, assign the unique code value created in step 1 to the risk_session_id parameter.
  2. Submit the application.

Creating Applications - Code Sample

Example Request

				
					curl --request POST \
   --url 'https://api.forte.net/v3/organizations/org_300005/applications/' \
   --header 'Accept: application/json' \
   --header 'Authorization: {{Authorization}}' \
   --header 'Content-Type: application/json' |
   --header 'X-Forte-Auth-Organization-Id: org_300005' \
   --data '{
        "fee_id": 1648,
        "source_ip":"55.5.55.555",
        "annual_volume":"100000", 
        "average_transaction_amount": "10000",
        "maximum_transaction_amount":"5000",
        "average_payable_amount":"2500",
        "maximum_payable_amount":"10000",
        "monthly_payable_volume":"1000",
        "market_type":"internet",
        "t_and_c_version" : "Tc1",
        "t_and_c_time_stamp": "4/3/2016",
        "risk_session_id":"s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
        "applicant_organization": {
           "legal_name":"George McFly Enterprises",
           "tax_id_number":"123456789",
           "legal_structure":"sole_proprietorship",
           "dba_name":"GMF Enterprises",
           "street_address1":"503 DeLorean Way",
           "locality":"Hill Valley",
           "region":"CA",
           "postal_code":"95420-4344",
           "customer_service_phone":"5555236987",
           "website":"www.GMFEnterprises.com",
           "business_type":"A10100",
           "bank_routing_number":"211170101",
           "bank_account_number":"121245611",
           "bank_account_type":"checking"
        },
        "owner": {
           "first_name":"George",
           "last_name":"McFly",
           "street_address1":"49 Great Scott! Drive",
           "locality":"Hill Valley", 
           "region":"CA",
           "postal_code":"95420-4345",
           "country": "USA",
           "citizenship": "USA",
           "email_address":"george.mcfly@GMFEnterprises.com",
           "mobile_phone":"214-448-5393",
           "last4_ssn":"6789",
           "date_of_birth":"3/3/1938",
           "percentage":"40"
        },
        "owner_2": {
           "first_name":"Marty",
           "last_name":"McFly",
           "street_address1":"52 Great Scott! Drive",
           "locality":"Hill Valley", 
           "region":"CA",
           "postal_code":"95420-4345",
           "country": "USA",
           "citizenship": "USA",
           "email_address":"martin.mcfly@GMFEnterprises.com",
           "mobile_phone":"972-712-3019",
           "last4_ssn":"5896",
           "date_of_birth":"11/3/1969",
           "percentage":"30"
        },
        "owner_3": {
           "first_name":"Jennifer",
           "last_name":"McFly",
           "street_address1":"54 Great Scott! Drive",
           "locality":"Hill Valley", 
           "region":"CA",
           "postal_code":"95420-4345",
           "country": "USA",
           "citizenship": "USA",
           "email_address":"j.mcfly@GMFEnterprises.com",
           "mobile_phone":"469-222-0608",
           "last4_ssn":"4455",
           "date_of_birth":"8/31/1969",
           "percentage":"30"
        }
}   '

Example Response – 201 Created

				
					{
    "fee_id": "1648",
    "annual_volume": 100000,
    "average_transaction_amount": 10000,
    "maximum_transaction_amount": 5000,
    "monthly_payable_volume": 1000,
    "average_payable_amount": 2500,
    "maximum_payable_amount": 10000,
    "source_ip": "55.5.55.555",
    "t_and_c_version": "Tc1",
    "t_and_c_time_stamp": "2016-04-03T00:00:00",
    "market_type": "internet",
    "risk_session_id": "s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
    "applicant_organization": {
       "dba_name": "GMF Enterprises",
       "legal_name": "George McFly Enterprises",
       "street_address1": "503 DeLorean Way",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4344",
       "country": "USA",
       "website": "www.GMFEnterprises.com",
       "customer_service_phone": "555-523-6987",
       "legal_structure": "sole_proprietorship",
       "business_type": "A10100",
       "bank_routing_number": "211170101",
       "bank_account_type": "checking"
    },
    "owner": {
       "first_name": "George",
       "last_name": "McFly",
       "last4_ssn": "6789",
       "date_of_birth": "1938-03-03T00:00:00",
       "email_address": "george.mcfly@GMFEnterprises.com",
       "mobile_phone": "214-448-5393",
       "street_address1": "49 Great Scott! Drive",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4345",
       "country": "USA",
       "citizenship": "USA",
       "percentage": 40
    },
    "owner_2": {
       "first_name": "Marty",
       "last_name": "McFly",
       "last4_ssn": "5896",
       "date_of_birth": "1969-11-03T00:00:00",
       "email_address": "martin.mcfly@GMFEnterprises.com",
       "mobile_phone": "972-712-3019",
       "street_address1": "52 Great Scott! Drive",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4345",
       "country": "USA",
       "citizenship": "USA",
       "percentage": 30
    },
    "owner_3": {
       "first_name": "Jennifer",
       "last_name": "McFly",
       "last4_ssn": "4455",
       "date_of_birth": "1969-08-31T00:00:00",
       "email_address": "j.mcfly@GMFEnterprises.com",
       "mobile_phone": "469-222-0608",
       "street_address1": "54 Great Scott! Drive",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4345",
       "country": "USA",
       "citizenship": "USA",
       "percentage": 30
    },
    "response": {
       "environment": "live",
       "response_desc": "Application submitted has been approved."
    }
}

Finding Applications - Code Sample

Example Request

				
					curl --request GET \
   --url 'https://api.forte.net/v3/organizations/org_300005/applications?filter=start_received_date+eq+%272017-01-01%27+and+end_received_date+eq+%272017-06-30%27' \
   --header 'Authorization: {{Authorization}}' \
   --header 'Accept: application/json' \
   --header 'X-Forte-Auth-Organization-Id: org_300005'

Example Response – 200 Created

				
					{
    "number_results": 2,
    "search_criteria": {
    "page_size": 50,
    "page_index": 0,
    "home_organization_id": "org_334316",
    "resource_specific": {
       "start_received_date": "2017-01-01T00:00:00",
       "end_received_date": "2017-06-30T00:00:00"
    }
  },
  "results": [
    {
       "application_id": "app_111234",
       "location_id": "loc_123000",
       "status": "declined",
       "decline_reason": "reputation",
       "fee_id": "8258",
       "source_ip": "55.5.55.555",
       "annual_volume": 100000,
       "average_transaction_amount": 10000,
       "average_payable_amount": 1000,
       "maximum_payable_amount": 6000,
       "monthly_payable_volume": 600,
       "market_type": "internet",
       "t_and_c_version": "Tc1",
       "t_and_c_time_stamp": "2/3/2017",
       "risk_session_id": "s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
       "applicant_organization": {
          "organization_id": "org_123456",
          "legal_name": "Biff Tannen Innovations",
          "legal_structure": "sole_proprietorship",
          "dba_name": "BTI",
          "street_address1": "503 DeLorean Way",
          "locality": "Hill Valley",
          "region": "CA",
          "postal_code": "95420-4344",
          "customer_service_phone": "5555236987",
          "website": "www.BTInnovations.com",
          "business_type": "A10100",
          "bank_routing_number": "211170101",
          "bank_account_type": "checking"
       },
       "received_date": "2017-02-03T09:22:34.63",
       "updated_date:": "2017-02-05T03:14:43.72",
       "sales_rep": "JohnnyBGoode",
       "fee_plan": "gold",
       "owner": {
          "first_name": "Biff",
          "last_name": "Tannen",
          "street_address1": "49 Great Scott! Drive",
          "locality": "Hill Valley",
          "region": "CA",
          "postal_code": "95420-4345",
          "country": "USA",
          "citizenship": "USA",
          "email_address": "b.tannen@BTInnovations.com",
          "mobile_phone": "5555698965",
          "date_of_birth": "3/3/1968",
          "percentage": 100
       },
       "links": {
          "documents": "https://api.forte.net/v3/applications/app_111234/documents",
          "self": "https://api.forte.net/v3/applications/app_111234"
       }
    },
    {
       "application_id": "app_998877",
       "location_id": "loc_456789",
       "status": "approved",
       "fee_id": "14081",
       "source_ip": "55.5.55.555",
       "annual_volume": 100000,
       "average_transaction_amount": 10000,
       "average_payable_amount": 2500,
       "maximum_payable_amount": 10000,
       "monthly_payable_volume": 1000,
       "market_type": "internet",
       "t_and_c_version": "Tc1",
       "t_and_c_time_stamp": "5/25/2017",
       "risk_session_id": "s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
       "applicant_organization": {
          "organization_id": "org_987654",
          "legal_name": "George McFly Enterprises",
          "legal_structure": "sole_proprietorship",
          "dba_name": "GMF Enterprises",
          "street_address1": "503 DeLorean Way",
          "locality": "Hill Valley",
          "region": "CA",
          "postal_code": "95420-4344",
          "customer_service_phone": "5555236987",
          "website": "www.GMFEnterprises.com",
          "business_type": "A10100",
          "bank_routing_number": "211170101",
          "bank_account_type": "checking"
       },
       "received_date": "2017-05-25T05:29:48.62",
       "updated_date:": "2017-05-27T03:22:14.31",
       "sales_rep": "JohnnyBGoode",
       "fee_plan": "gold",
       "owner": {
          "first_name": "George",
          "last_name": "McFly",
          "street_address1": "49 Great Scott! Drive",
          "locality": "Hill Valley",
          "region": "CA",
          "postal_code": "95420-4345",
          "country": "USA",
          "citizenship": "USA",
          "email_address": "george.mcfly@GMFEnterprises.com",
          "mobile_phone": "5555698965",
          "date_of_birth": "3/3/1938",
          "percentage": 100
       },
       "links": {
          "documents": "https://api.forte.net/v3/applications/app_998877/documents",
          "self": "https://api.forte.net/v3/applications/app_998877"
       }
    }
  ],
  "response": {
     "environment": "live",
     "response_desc": "Get Successful."
  },
  "links": {
     "self": "https://api.forte.net/v3/applications/?filter=start_received_date+eq+%272017-01-01%27+and+end_received_date+eq+%272017-06-30%27"
  }
}

Finding a Specific Application - Code Sample

Example Request

				
					curl --request GET \
   --url 'https://api.forte.net/v3/organizations/org_300005/applications/app_109630' \
   --header 'Authorization: {{Authorization}}' \
   --header 'Accept: application/json' \
   --header 'X-Forte-Auth-Organization-Id: org_300005'

Example Response – 200 Created

				
					{
    "application_id": "app_109630",
    "organization_id": "org_234791",
    "status": "approved",
    "fee_id": "14081",
    "source_ip": "55.5.55.555",
    "annual_volume": 100000,
    "average_transaction_amount": 10000,
    "average_payable_amount": 2500,
    "maximum_payable_amount": 10000,
    "monthly_payable_volume": 1000,
    "market_type": "internet",
    "t_and_c_version": "Tc1",
    "t_and_c_time_stamp": "4/3/2016",
    "risk_session_id": "s%3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZ.LjRrgNhYmuWApi%2FhdhB5wW4MgqknPHx1WR7s4RX1vWs",
    "applicant_organization": {
       "organization_id": "org_852963",
       "legal_name": "George McFly Enterprises",
       "legal_structure": "sole_proprietorship",
       "dba_name": "GMF Enterprises",
       "street_address1": "503 DeLorean Way",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4344",
       "customer_service_phone": "5555236987",
       "website": "www.GMFEnterprises.com",
       "business_type": "A10100",
       "bank_routing_number": "211170101",
       "bank_account_type": "checking"
    },
    "received_date": "2017-05-25T05:29:48.62",
    "updated_date:": "2017-05-27T03:22:14.31",
    "sales_rep": "JohnnyBGoode",
    "fee_plan": "bronze",
    "owner": {
       "first_name": "George",
       "last_name": "McFly",
       "street_address1": "49 Great Scott! Drive",
       "locality": "Hill Valley",
       "region": "CA",
       "postal_code": "95420-4345",
       "country": "USA",
       "citizenship": "USA",
       "email_address": "george.mcfly@GMFEnterprises.com",
       "mobile_phone": "5555698965",
       "date_of_birth": "3/3/1938",
       "percentage": 100
    },
    "response": {
       "environment": "live",
       "response_desc": "Application submitted has been approved."
    },
    "links": {
       "documents": "https://api.forte.net/v3/applications/app_109630/documents",
       "self": "https://api.forte.net/v3/applications/app_109630"
    }
}

Step 5: Test Your Calls

Understanding Responses

Barring a formatting or authentication error, you should receive a response message for every request you send via the REST API. These responses echo back all the parameters you passed in the request with sensitive data such as account numbers and/or Social Security Numbers redacted to the last four digits. Optional request parameters whose values were null in the request do not echo back in responses. In addition to the echoed resource parameters, the response message also includes a response object.

For requests to the applications endpoint, only the following parameters display in the response object:

Hypermedia

Forte’s REST API returns the following format for hypermedia responses. Result availability depends on the resource/action in the request. The following sample of hypermedia responses are merely formatting examples provided for reference.

				
					{
    "links": {
       "self":"https://api.forte.net/v3/applications?page_index=1",
       "prev":"https://api.forte.net/v3/applications?page_index=0",
       "next":"https://api.forte.net/v3/applications?page_index=2",
       "documents":"https://api.forte.net/v3/applications/app_998877/documents"
    }
}

Status Codes

Forte's web services use standard HTTP status codes along with messages where appropriate. The table below displays the most common codes:

For status codes in the 400s, ensure that you correctly formatted the JSON (or XML) in the original request, especially when the system returns a descriptive error message along with the status code such as the following example messages:

				
					{
    message: "Authentication Organization ID in header is missing or invalid."
}
				
			
				
					{
    message: "Payment Method's routing number length is invalid."
}

Testing in Postman

To help you gain a greater understanding of how Forte's REST API works, we've built a Postman collection of sample REST requests that you can use to test each resource, including applications.

Creating Environments

While we've included sample body parameters in this collection of request calls, you'll still need to add the URL endpoints and Authentication Headers described in Step 3 above. The easiest way to start testing these sample request calls is to create your own environment that includes global variables. All of the calls to the applications resource in our collection include the following variables:

To create an environment for our Postman collection, complete the following steps:

  1. Navigate to our REST API v3 Reference, and click . If the collection does not open in the native app, click either the Postman for Chrome or Postman for Windows option. The collection imports into Postman.

Click  > Manage Environments in the upper-right corner of the screen.

The Manage Environments modal displays.

Click . The Add Environment fields display.

  1. Give your environment a name in the Environment Name field. This name should be concise and indicate whether calls using this environment will be sent in Sandbox or Production.
  2. Add the baseURI, organizationID, apiaccessid, and apisecurekey variables in the Key column and the values for these parameters in the Value column. A completed Add Environment modal looks similar to the following.

6. Click . The Manage Environments modal displays your newly created environment.

Repeat steps 3–6 to additional environments (e.g., Live).

Testing Your First Call

After creating your global variables in an environment, you're ready to run your first call. To do so, complete the following steps:

  1. From the Forte REST API v3 collection menu, click Applications > POST Application. Postman loads the URL.

2. Click the dropdown menu in the Environment field and select the environment in which you want to send this request. Since we’re just testing POST requests, we’ll select “Sandbox” for the sake of this example. The variables in the URL should change from red to orange, indicating that Postman recognizes them as variables with a defined value.

3. Click the Headers tab and enter the Authorization, X-Forte-Auth-Organization-Id, Accept, and Content-Type headers in Key column and their values in the Value column. NOTE: To quickly add these headers to a call, create them in a .txt file and then copy and paste them using the Bulk Edit link on the Headers tab in Postman. Your headers tab should look similar to the following figure:

4. Click the Body tab. Ensure that the raw radio button is selected and the JSON (application/json) option displays. The POST and PUT requests in our REST collection include the required parameters for every resource; however, the applications resource includes body parameters that must be customized with your values for successful submission, specifically, the fee_id parameter and, depending on the environment, the risk_session_id parameter. You can obtain the value of the fee_id parameter by accessing the Rate Plans Datagrid in Dex (i.e., Merchant Applications > Rate Plans), or, if you don’t have permissions to access this menu option, from your Forte Account Manager.

5. After customizing the Header and Body tabs with your values, click . Barring any formatting errors in the request, Postman displays the response message from Forte and its status code.

  1. If you’d like to save this call with your header and body parameters, click  to add the call to your imported collection.

After creating a few test applications with varying scenarios and customer stories, you can test the GET calls using the same process you used when creating a POST (except for customizing the parameters of the Body tab). NOTE: Forte does not save the data for applications created in the Sandbox environment; therefore, when testing GET calls, you must use the Live environment. Once you’re comfortable with the parameters of the applications resource, you can begin building your merchant application template on your site.

Managing Supporting Documentation for Applications in REST
Dex Application Portal Overview
Viewing an Enrolled Merchant's Organization
On this page