PSP Integration Guide

Guide for integrating Forter's PSP solution

Suggest Edits

PSP Integration Guide

Step 1: Provide Forter with an outline of your PSP portfolio.

This should include information about your merchant verticals, traffic, and payment methods accepted on your merchant sites. Forter will use this information to start training its models.

Step 2: Historical Data

As part of our initial phases, we'll request historical data (approximately last 12 months) of your first 50 sites.

Step 3: Phase 0 - Sandbox Phase

Go to your Parent site's sandbox environment to retrieve your API siteId and secret key. This sandbox site should correspond to your main test environment. Your sandbox credentials should be use to start testing the Validation API, Order Status, and Claims APIs.

Paste your JavaScript

Copy and paste your Forter sandbox JS script to your sandbox site. The minimum requirement is that the JavaScript is added to your checkout page so that the Forter token can be retrieved and included in the backend order data for each of your merchants' sites.

Integrate the Validation API

The Validation API provides a real-time approve/decline decision at the time a customer places an order on your merchant site. The Validation API should be called Pre-Auth prior to calling your payment processor to authorize the payment and should include all information about the order as well as payment data like credit card token, credit card expiration date, and name on card.

If you would like to call Forter's Validation API Post-Auth (after receiving an authorization response from your processor), please reach out to your Forter team to adjust your schema accordingly.

The Validation API will include a real-time approve/decline or "not reviewed" decision. You can customize how you want to handle decisions in your system (i.e. cancel the order, redirect customer, etc.)

Integrate the Order Status API

In the case of Pre-Auth integrations, the Order Status should be called asynchronously in real-time upon receipt of the authorization response from your payment processor. It should include the authorization response data like the authorization response, cvv response code, avs result code, and processor response text. It should also include the updated status mapped to a set of Forter enums, the event timestamp, and the order Id.

Integrate the Claims API

The Forter Claims API allows Forter's models to see the full lifecycle for every order and - in the case of Fraud chargebacks - provides an important data point to dynamically prevent future fraud attempts by the same fraudster or fraud ring.

Step 4: Test/QA in Sandbox

Forter has a variety of tools you can use to review and test your API request formatting and data sufficiency. In this Step, you'll be able to review and automatically test the data sufficiency of your test api requests.

Step 5: Pilot Phase

Once your Forter analyst and project manager team have reviewed your sandbox tests. you can start integrating your first batch of "Pilot" sites. Forter will generate the 20 sites you want to go live with initially. You'll use the merchant site id that was generated with the sub-sites and include it in the API request headers for each merchant site as well as within the JS script you add for each merchant site to designate each individual store and connect the orders TO each store. The pilot phase sites should each integrate:

  1. JavaScript snippet
  2. Validation API with a unique identifier for each merchant sub-site
  3. Order Status API with a unique identifier for each merchant sub-site
  4. Claims API with a unique identifier for each merchant sub-site

Step 6: Pilot Listen Mode

Once your Forter analyst team has ingested the historical data for your pilot set of sites, they'll instruct you to deploy the Forter integration to your Production environment. Forter's models will be "listening" to the production transactions being sent but only return a "not reviewed" decision.

This 2-week listen mode allows Forter's models to see live data and provides analysts time to ensure our systems are fine-tuned to be extremely accurate on the first day of go-live. Our analysts may reach out during this time if they have any questions or notice any discrepancies with the Production data during this period.

Step 7: Phase 2 (50 sites)

After Listen Mode is complete for the Pilot Phase, you'll move onto Phase 2 where you can start to leverage the Forter Merchant Creation API.

  1. Merchant Creation API
    All your merchant subsites will use the same API request format so that Forter's system recognize the unique merchant subsite that each request is originating from.

Example:

When you call the merchant creation API, you'll receive the following response from Forter's merchant creation API endpoint:

Merchant Creation API Response

{
  "merchantId": "eh629dK9", // internal ID in PSP system provided in request
  "defaultMerchantCategoryCode": "5655",
  "merchantAccountCreation": {
    "timestamp": 1415273179,
    "ip": "10.0.0.128"
  },
  "id": "abcde1234567", // forter id to be included in a dedicated header in API requests
  "name": "T-Shirts Express" 
}

In the example, id returned in the Merchant Creation API for one of your merchant subsites is "abcde1234567", the request headers in the Validation API should appear with your main, PARENT PSP credentials and api version (in this case the parent PSP credentials are, secret key:006270c125f1c6149183614ac9827da7c604f445, siteId:site7ah8c7539 and version:2.15) like the following curl example:

      curl -X POST "https://<parent-siteid>.endpoint.forter.com/v2/orders/[ID]"
      -u "006270c125f1c6149183614ac9827da7c604f445:"
      -H "api-version: 2.15"
      -H "x-forter-siteid: site7ah8c7539" 
      -H "x-forter-subid: abcde1234567"
      -H "Content-Type: application/json"
      -d @filepost.data
  1. JavaScript snippet (at minimum on the hosted checkout page) with each store's unique Merchant Subsite Id (id) included in the script body.
  2. Validation API with Merchant Subsite Id (id) included in the subsite id request header
  3. Order Status API with Merchant Subsite Id (id) included in the subsite id request header request header
  4. Claims API with Merchant Subsite Id (id) included in the subsite id request header request header

All subsites in Phase 2 will require JavaScript snippet integration as well as the Validation, Order Status and Claims APIs. However, no manual QA is required.

A 10-day listen mode will also be applied for Phase 2 where the Forter Analyst and Implementations team will monitor your Production data before enabling actionable fraud decisions.

Step 8: Phase 3 - General Availability

After completing your Phase 2 (50-site) Listen Mode, you can create all subsequent merchant sites using the Merchant Creation API and integrate these sites without the 10-day listen mode - meaning once the site has integrated the Forter JavaScript, Validation, Order Status, and Claims APIs with the appropriate Merchant Subsite Id (id) included in the JS snippet and API request headers. Forter allows up to 10K sites to be created via the API. Please reach out to your Forter team if you need to exceed the 10K default site limit.

Updated 6 months ago