GIDX Platform

Preparing for a Merchant Integration

Preparing for your merchant integration will include the following prerequisite items be implemented within your merchant environment. Regardless of your implementation type, services, or integration plan these items will be critical to the success of your integration with the GIDX Platform.

Merchant: Data Storage

The merchants system needs to have a solution for data management (Database, Tables, Stored Procedures, Views, etc.) so that you can store, track, and manage the information and interaction between the merchants environment and the GIDX Platform.

We have a "best practice" schema designed for this data store environment which can viewed below. This design model can be modified based on any existing data store design that may already be in place within your environment.

Merchant: Environment & Server Side Set-Up

Please review the information below regarding the set-up and configuration of your server environment as well as your account within the GIDX Portal.

Access to the most common code base for integration can be found within the GitHub and NuGet repositories following the links below.

• GitHub: https://github.com/TSEVOLLC
• NuGet: https://www.nuget.org/packages/GIDX.SDK/

GIDX / Merchant Environment Set-Up & Configuration

The following steps will help you with accessing your system credentials and setting up your account for use of the GIDX Environment.

1. Request a login to the GIDX Portal
   Account access to the GIDX Portal cannot be shared across multiple devices or people at the same time. Doing so will void the account and continuous attempts to violate this policy will result of suspension of the entire account for all users within that company. Meaning: Do not share your account with someone else.
2. Login and Update your Password
   Once you login to the GIDX Portal you will need to update your password to something only you will know; then you will need to login again to the account in order to access the different systems within the Portal.
3. Integration Set-Up
   On the left side of the portal menu is a section labeled "Integration" / "Platform Sandbox", within this section you will need to do the following PRIOR to beginning your API integation.
4. Collect your API Access Integration Credentials
   You will need your Sandbox API Key, Merchant ID, Product (Type) ID, Activity (Type) ID, and Device (Type) ID.
5. Manage your IP Address Restrictions
   You will need to add your OUTWARD FACING Static IP Address for your development environment to our listing service. You can do this within the portal under the IP Addr. Restrictions section of the system.

   If your development environment (or later your production environment) is not hosted behind a static IP address, like in the case of load-balancers etc. you can use the following instructions to set your system up securly for restricted IP access.

   AWS: Amazon Web Services Hosting
   • Basic: Assign an Elastic IP to an EC2 instance https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html
   • Advanced: Scaling with either AWS Lambda or dynamically scaling EC2 instances, you should create a NAT Gateway and assign an Elastic IP address https://dev.to/alexanderdamiani/aws-lambda-with-a-static-ip-2g3l

   Microsoft Azure: Cloud Web Services / Hosting

   • Network Outbound for Azure — Ways to Get Static Outbound IP Address https://medium.com/marcus-tee-anytime/network-outbound-for-azure-ways-to-get-static-outbound-ip-address-304cec44d910

   Google: Cloud Web Services / Hosting

   • Connecting a Static outbound IP address via VPC egress to route all outbound traffic through a VPC network / Cloud NAT gateway https://cloud.google.com/run/docs/configuring/static-outbound-ip

Merchant: Client Side Code

The merchants client side interface has several HTML, META TAG, and JavaScript related requirements that must be in place in order for the GIDX Service to operate properly.

To view a completed sample HTML file click the button below. This example has all of the HTML, META TAG, and JavaScript items within a single file format to use as a guide when building your own client side interface.

JavaScript Client Side Code Details

In order to properly integrate GIDX services you will need to collect data from the customers device. The two primary pieces of data that need to be collected from the customer for each visit that they make to your site/app are their current IP Address and their Device GPS data.

The first thing you must do is get approval from the customer that you may access data from their device. You can do this by calling the getCurrentPosition() method using javascript and the browsers embeded Geo-Location API. Learn more about this process by going to this page https://www.w3schools.com/html/html5_geolocation.asp.

The customers' device IP Address should be collected using server side code and accessing the information found in the browsers hearder-request to your server. The header value you should be accessing is the "X-Forwarded-For" value.

The customers' Device GPS data should be collected using client side JavaScript Geo-Location API, you can learn more about this by going to https://w3c.github.io/geolocation-api/.

The function gidxServiceStatus(service, action, json) provides real-time updates to the client interface regarding the customers activity during a Web Session. An example of this function is in the HTML Code Example and the values passed into the function variables are listed below.

window.gidxServiceStatus = function (service, action, json) { 
    if (json && json.length) { 
        for (var i = 0; i < json.length; i++) { 
            for (var key in json[i]) { 
                if (json[i].hasOwnProperty(key)) { 
                    //Here you can look at the key and value to make decisions on what you would 
                    //like to do with the client side interface. 
                    var sItem = key; 
                    var sValue = json[i][key];
                    //Example 
                    if(sItem == "TransactionAmount"){ 
                        document.getElementById("DepositAmountDisplay").innerText(sValue);
                    } 
                } 
            } 
        } 
    } 
};

The variables to work with in this function are the "service", "action", and "json" values.

• The service value tells you which "step" in the process that a customer is currently within.
• The action value tells you what the activity is for this notification.
• The json value provides you details about the action. In many cases the json value is empty/null.

Below is a list of the service, action, and corresponding json values that you could encounter during the Payment process of the WebCashier Service.

Below is a list of the service, action, and corresponding json values that you could encounter during the Payment process of the WebReg Service.

The function gidxServiceSettings() is required so that you can control parts of the UX/UI of the WebSession service. An example of this function is in the HTML Code Example and the variables set in this function are listed below.

window.gidxServiceSettings = function () {
    window.gidxContainer = "#GIDX_Service_Container";
    window.gidxBuildTimer = false;
    window.gidxBuildSteps = false;
};

The variables to work with in this function are "gidxContainer", "gidxBuildTimer", and "gidxBuildSteps".

• The gidxContainer variable allows you to set the identifier of the DOM HTML element that the WebSession service will render. This should be the value of an ID and contain "#" at the beginning. Technically a "class" value will work but doing so may lead to errors if there is more than one element using that class name.
• The gidxBuildTimer variable can be set to true or false, setting the value to true will add a timer to the UI that counts down from 20 minutes. This is the length of time that the customer has to complete the session service.
• The gidxBuildSteps this has been deprecated. To accomplish this same functionality you should use the gidxServiceStatus function if you would like to display a heading for the customers current "step" in the session.

The function gidxErrorReport() alerts you to any Errors/Issues stemming from UX/UI of the WebSession service. An example of this function is in the HTML Code Example and the variables set in this function are listed below.

window.gidxErrorReport = function (error, errorMsg) {
    //error is the ID of the Error that is being fired.
    //errorMsg is the text description of the Error.
};

The variables to work with in this function are "error" and "errorMsg". Below is the library of ErrorID and ErrorMsg you will receive from the service for both the WebCashier service and the WebReg (Customer Identity Verification) service. NOTE: On non-verified customers you may experience both of these services within the WebCashier CreateSession API call.

Service Case:

Registration/IDInitiate

Error ID error:

0

Error Msg Text errorMsg:

Initiate registration process failed.

Service Case:

Registration/IDValidation

Error ID error:

1

Error Msg Text errorMsg:

ID Validation process failed.

Service Case:

Registration/IDLocation

Error ID error:

2

Error Msg Text errorMsg:

ID Location Process failed.

Service Case:

Registration/IDLocationVerify

Error ID error:

2

Error Msg Text errorMsg:

ID Location Process failed.

Service Case:

Registration/IDQuestion

Error ID error:

3

Error Msg Text errorMsg:

ID Questions Process failed.

Service Case:

Registration/IDDocumentVerify

Error ID error:

4

Error Msg Text errorMsg:

ID Document Verify Process failed.

Service Case:

Registration/Timeout

Error ID error:

598-A

Error Msg Text errorMsg:

The Registration Session timed out.

Service Case:

Default / Generic

Error ID error:

-1

Error Msg Text errorMsg:

Unknown Registration Error

Service Case:

Cashier/Initiate

Error ID error:

0

Error Msg Text errorMsg:

Initiate cashier process failed.

Service Case:

Cashier/PaymentAmount

Error ID error:

1

Error Msg Text errorMsg:

Loading cashier options for the merchant failed.

Service Case:

Cashier/PaymentMethodOptions

Error ID error:

2

Error Msg Text errorMsg:

Loading cashier payment method options for this Profile failed.

Service Case:

Cashier/AddPaymentMethod

Error ID error:

3

Error Msg Text errorMsg:

Adding a cashier payment method failed.

Service Case:

Cashier/ModifyPaymentMethod

Error ID error:

4

Error Msg Text errorMsg:

Modifying a cashier payment method failed.

Service Case:

Cashier/VerifyPayment

Error ID error:

5

Error Msg Text errorMsg:

Verifying the payment failed.

Service Case:

Cashier/Timeout

Error ID error:

598-A

Error Msg Text errorMsg:

The Cashier Session timed out.

Service Case:

Default / Generic

Error ID error:

-1

Error Msg Text errorMsg:

Unknown Cashier Error

Merchant: System Rules

When using GIDX Platform Services the merchant will need to make decisions on how to assess Customers, Transactions, and Operations based on the Response, Callback, and Notification data provided; we refer to these decisions/actions as the "Merchant Rules".

An example of one of these Merchant Rules would be as follows...

The ReasonCode value of the Response contains the following items ID-VERIFIED, LL-GEO-US-AL, ID-UA-19, DFP-HR, ID-EX

These ReasonCodes indicate that the customer...

• Has passed the Identity Verification Service. ID-VERIFIED
• Is currently located in the state of Alabama within the United States. LL-GEO-US-AL
• Their age is under the age of 19. ID-UA-19
• The device (PC, Mobile Phone, Tablet) has been flagged as being associated with High Risk activity. DFP-HR
• The Identity Profile matches a previously verified customer for this merchants account. ID-EX

Based on these ReasonCodes the merchant will now need to decide how they would like proceed with this customer...

The customer's identity is Verified ID-VERIFIED, but their age indicates that they are under the age of 19 ID-UA-19, when the customer is considered "under age" based on their current location then the appropriate action needs to be taken during this Session. Other indicators such as ID-EX will tell you that this customer account already exist, you can get a list of the other Customers that match this customer account by doing another API call using this current customer's ID. The DFP-HR ReasonCode should also be noted on the customers account within the merchant's system, this means that the device that the customer is currently using has been involved in some high-risk behavior.