GIDX Platform

An Introduction

Welcome to the GIDX Platform integration guide; please read through this document and familiarize yourself with the services, requirements, suggestions, and preparation steps provided before beginning your integration.

The GIDX Platform provides direct access to the following services...

Timeline & Expectations

Below is an overview and timeline expectations for a typical GIDX Platform Implementation / Integration. The steps marked GIDX are steps approved, executed, implemented by the internal GIDX team. This is merely a guide and each timeline may be adjusted based on the individual merchants integration resources and requirements.

Prerequisite Steps

This document is a guide to getting started on the right foot - it provides you with an overview of the requirements, suggestions, and best-practice processes for your successful integration with the GIDX Platform.

The items below should be a part of your implementation plan. Any additional compliance related factors based on industry and services needed should also be taken into account when preparing your internal implementation map.

1. Review Merchant Preparation items
   • Build Data Storage Environment
   • Development of Server Side Code Elements (C# SDK is available)
   • Development of Client Side Interface Elements
   • Review Merchant System Settings
   • Implement System Rules and determine testing scenarios
   
   Go to the Merchant Preparation guide...


2. Map out your service workflow.
   • Compliance Only: Customer Identity, Location, and Regulatory
   • Payments & Compliance: Customer Identity, Location, Regulatory, and Payments


3. Target Integration Environment - how will customer access your service?
   • Web-based browser access: Desktop, Tablet, Mobile Phone
   • Native App. via iOS and/or Android on a mobile device


4. Familiarize yourself with the GIDX Platform environment.
   • How to use the ReasonCodes and Session/Data Scoring that is provided within the service response/updates.
   • Review the testing tools and data that is provided as part of the integration.
   • How Merchant Settings effect the customer experience and service implementation.
   • How to customize the Client Side Interface of WebSession based services.


5. Execute the items in the Merchant Preparation list.


6. Review the GIDX Service API Reference documents.

Important things to know regarding the GIDX Platform

The following is a list of items we wanted to highlight before a merchant begins planning their integration with the GIDX Platform. From time to time we may add additional items to this list based on the experiences of merchants using the GIDX Platform.

• The GIDX Platform has a C# SDK (GIDX.SDK NuGet) that should be used if possible - it makes things a lot easier.
• Some of the GIDX Platform Services are provided in two different service formats...
  • Direct Session: which provides a traditional Request/Response process and does not require customer interaction.
  • Web Session: which provides a managed/embedded solution where the service being performed communicates directly with the customer and their device. You will learn more about these two Session types within these implementation documents.
• The merchant should only implement a Web Session based service within a secure environment once the customer has logged into their specific account. Web Session based services provide secure customer information unique to the Customer ID indicated by the merchant within the API Method Call.
• When using a WebSession Service, such as the Customer Identity WebReg Service or Payment Management WebCashier Service, the "CreateSession" method will require that the IP address of the customers' device for this WebSession is provided in the API call. This process is required so that the GIDX Platform can ensure that the device the original WebSession was requested from is the same device that is loading the secure ScriptTag that is provided in the WebSession response.
• All customer accounts within the Merchants environment should have a Unique ID that is never shared / used by another customer account of the merchant.
• The GIDX Platform requires that all Customer IDs, Session IDs, Transaction IDs, or other unique Identifiers be a minimum of four (4) characters in length.

Service Workflow Example

The following service workflow example provides the typical process that occurs between the Merchant, Customer, and GIDX Platform during the course of several scenarios and can be tailored to met the specific requirements of the merchant.

To view a more customized workflow please select the options that best describe the merchants implementation strategy.

1. Identity Match
   

   Session Type:

   Direct Session

   API Path(s):

   /api/CustomerIdentity/CustomerRegistration

    

   /api/CustomerIdentity/CustomerProfile

2. Customer creates an account at the merchants app/website.
3. Merchant sends customer information to the CustomerRegistration method, accessible within the CustomerIdentity Service, for verification.
   • The response from an Identity Match attempt will return the results of the match, location details, watch list information, and scoring based on the confidence of the identity data & the confidence against fraud on the customer.
   • If the verification is Not Successful then... +/-
     • Set customer as Not Verified.
     • Option: Close customers account and do not allow them to participate. (Not recommended)
     • Recommended: Go to the Identity Verification process.
   • If the verification is Successful then the merchant ... +/-
     • Assigns the "Verified" status to that customer's internal account.
     • Reviews the other ReasonCode values to determine if any additional action may need to be taken based on the customers Age, Location, Fraud/Risk, Etc.
     • Next: Get the complete profile of the customer using the CustomerProfile Method.
     • The process for verifying the customer's identity is now complete.
4. Once the Identity Match service is complete AND IF the customers account/profile is Successfully Verified then the merchant should now make an API call to the CustomerProfile Method. This method will return all of the important customer profile information that is needed to generate an account within the TOTE service.
5. Identity Verification
   

   Session Type:

   Web Session

   API Path(s):

   /api/WebReg/CreateSession

    

   /api/CustomerIdentity/CustomerProfile

6. Using the Web Session service for Customer Identity Verification provides you with a hosted / managed process for identity match and verification.

   This allows a merchant to control the functionality of the identity verification through settings on the account rather than needing to write additional code for multiple use case scenarios.

7. The CreateSession method, located in the WebReg Service, will return several values that are needed for initiating the Web Session process.
   • ReasonCodes containing Customer Identity, Customer Device, and Location information - if available.
   • An encrypted, one time use, script-tag.
   • The expiration time of the Web Session.
8. Merchant embeds the encrypted one time use script-tag into the webpage displayed to the customer on their device.
9. This script-tag will connect to the GIDX Service directly from customers device; this direct connection will initiate the following process...
   • The customers device is authenticated using the encrypted token of the script-tag.
   • The GIDX Service detects and interprets the customers device attributes and analyzes the connection.
   • Based on these attributes and connection status the appropriate service interface is rendered as Bootstrap Formatted HTML and sent back to the customers device where it is then rendered into the interface and displayed based on the merchants settings.
   • The HTML interface, that is rendered and embedded by the script-tag into the merchants page on the customers device, is completely customizable by the merchant using standard CSS, jQuery/JavaScript, or other client side scripting languages.

   Based on the Merchant WebReg Customer Verification Service settings the embedded interface will present the customer the following screens/process.

   • Confirm/Provide their Name & Email Address.
   • Confirm/Provide their Date of Birth & Citizenship.
   • A series of KBA Questions / Multiple Choice Answers will be presented to the customer. (If activated in the Merchant settings)
   • Confirm the SSN by providing the last 4 digits. (If activated in the Merchant settings)
   • Verification Complete - Notification is sent to merchant.

   ---

   Note: The embedded WebReg Service can be controlled and monitored by the merchant in real time using a set of pre-defined JavaScript functions and the WebReg API Method called RegistrationStatus.

   For more information on these functions and how to use them please see the GIDX Client Side Library section within the Merchant Preparation Docs.

10. Once the customer has completed the Identity Verification process the GIDX Service will notify the merchant via a client side JavaScript function and server side CallBack service.

    For more information on these functions and how to use them please see the GIDX Client Side Library section within the API Reference Docs.

    The response / callback from an Identity Verification attempt will return the results of the verification, location details, watch list information, and scoring based on the confidence of the identity data & the confidence against fraud on the customer within the ReasonCode value.

    • If the verification is Not Successful then... +/-
      • Set customer as Not Verified.
      • Option: Close customers account and do not allow them to participate. (Not recommended)
      • Recommended: Go to the Document Library process.
    • If the verification is Successful then the merchant ... +/-
      • Assigns the "Verified" status to that customer's internal account.
      • Reviews the other ReasonCode values to determine if any additional action may need to be taken based on the customers Age, Location, Fraud/Risk, Etc.
      • Next: Get the complete profile of the customer using the CustomerProfile Method.
11. For customer accounts with a Successfully Verified profile the merchant can now access additional customer information by calling the CustomerProfile Method. This method will return all of the primary customer identity information and can be used to update the customers local account with the merchant or to create additional accounts associated with the merchant outside of the GIDX Platform.
12. The information returned on the customer from the CustomerProfile method can be used to generate an account within the TOTE service.
13. Document Library
    

    Session Type:

    Direct Session

    API Path:

    /api/DocumentLibrary/DocumentRegistration

14. The merchant presents a page to the customer that allows them to upload an "ID Document", which should be an image of the customer Drivers License, Passport, other official Identification.
15. This ID Document is send to the GIDX Platform Document Library service using the DocumentRegistration method within the DocumentLibrary service.
16. Within the GIDX Administrative Dashboard the customers document is reviewed by a certified ID Document manager and the appropriate status is assigned to the customers document and Identity Profile.
17. The GIDX Platform Notification service generates a JSON formated message, similar to a Callback, that is sent to a pre-defined endpoint associated with the Merchants environment. This Notification will contain the updated status of the customer and any other information pertinent to the customers profile.
18. Upon receiving the notification the Merchant should update the local account of the customer based on the ReasonCode value within notification message.
19. Cashier Service (Payment / Deposit)
    

    Session Type:

    Web Session

    API Path(s):

    /api/WebCashier/CreateSession

     

    /api/WebCashier/WebCashierStatus

20. Using the Web Session Cashier Service provides you with a hosted managed process for customer deposits, payouts, and payment method management.

    This allows a merchant to control the functionality of the cashier and payment functionality through settings on the account rather than needing to write additional code for multiple use case scenarios.

21. The CreateSession, located in the WebCashier Service, will return several values that are needed for initiating the Web Session process.
    • ReasonCodes: System codes containing Customer Identity, Device, and Location information - if available.
    • SessionURL: An encrypted, one time use, script-tag.
    • And other values including the sessions expiration time and echoed MerchantSessionID for security purposes.
22. The merchant decrypts and embeds the SessionURL (one time use script-tag) into the HTML webpage displayed to the customer on their device.

    NOTE: This HTML webpage should contain the required metatags and javascript outlined in the example located under the Merchant Preparation section.

23. Once embeded and viewed by the customer the script-tag will connect to the GIDX Service directly from the customers device; this direct connection will initiate the following process...
    • The customers device is authenticated using the encrypted token of the script-tag.
    • The GIDX Service detects and interprets the customers device attributes and analyzes the connection.
    • Based on these attributes and connection status the appropriate service interface is rendered as Bootstrap Formatted HTML and sent back to the customers device where it is then rendered into the interface and displayed based on the merchants settings.
    • The HTML interface, that is rendered and embedded by the script-tag into the merchants page on the customers device, is completely customizable by the merchant using standard CSS, jQuery/JavaScript, or other client side scripting languages.

    Based on the Merchant Cashier Service settings the embedded interface will present the customer the following screens/process.

    • Select/provide the deposit amount.
    • Select the payment method type - Credit Card, eCheck/ACH, PayPal, PayNearMe, etc.
    • Register the Payment Method (if this is the customer first time to make a deposit, or they are making a deposit with a new payment method)
    • Confirm the deposit amount and click finalize.
    • • If the customer HAS successfully verified their identity already then the transaction is processed and completed.
      • If the customer HAS NOT successfully verified their identity then this deposit is held in a pending state and the customer is dynamically prompted to verify their identity using the WebReg Customer Verification service.
24. Once the customer has completed the Cashier Payment process the GIDX Service will notify the merchant via a client side JavaScript function and server side CallBack service.

    Note: The embedded WebCashier Service can be controlled and monitored by the merchant in real time using a set of pre-defined JavaScript functions and the WebCashier API Method called WebCashierStatus.

    For more information on these functions and how to use them please see the GIDX Client Side Library section within the API Reference Docs.

    Important to note...
    If the customers identity was not previously set as verified and the customer is required to complete the Identity Verification process within the Web Cashier service then the merchant will receive two (2) Callbacks to their server environment; one for the deposit, and one for the identity verification.

    For more information on how to process these Callbacks please see the API Reference Docs.

25. Updating the customers Account Balance: When the Cashier "deposit" process is completed by the customer then the merchant is notified in several ways:
    
    Client Side...
    • Non ID Verified Customer: listen for the gidxNextStep JavaScript function to be executed.
    • ID Verified Customer: listen for the gidxServiceStatus JavaScript function where the "service" equals "cashierComplete-plate". This means that your customer is now viewing receipt portion after a transaction has been completed.
    Server Side...
    • The merchant will receive a Callback notification...
26. Upon receiving these notifications the merchant can then call the WebCashierStatus Method and PaymentDetails Methods.

Based on the results returned from the WebCashierStatus and PaymentDetails methods the merchant will need to update the customers local account balance based on the successfully processed amount of the deposit.

Note: Multiple Cashier "deposit" Callbacks may be sent to the merchants all associated with the same transaction. This would be in the event that the transaction moves from a pending state to a processed state in the even that the processor does not provide a real-time status notification to the transaction. This happens occasionally with payment services such as eCheck/ACH, PayPal, PayNearMe, or in the event that the transaction is set to processed AFTER the customer has completed their Identity Verification.

Target Environment: Desktop, Mobile, Native iOS / Android

If your Target Environment is browser based Desktop, Tablet, Mobile Phone then all of the instructions needed for integration are already in place within this document. All of the user interface contained in the Web Session service are designed for a responsive environment and will dynamically adjust based on the customer device.

If your Target Environment is a native iOS / Android app then there are a few extra items that need to be reviewed when mapping out your implementation.

• Your application will need to generate a screen containing an active WebView.
• This WebView will need to point to a page on the merchants server/environment that executes a call to the appropriate GIDX Service
• At this point, the process is similar to a standard browser based implementation where the Web Session services will render itself into the embedded HTML page.
• If needed, the merchants app can communicate with the executed JavaScript on the HTML page loaded within the WebView using native code. These links below provide some context on how to do this...
  • Communication: iOS to JavaScript and Back by Grego on the site One Big Function
  • Sending Data from a UIWebView back to an iOS Application... is a good example of how someone is accomplishing this as well. You can find this article and others on StackOverflow
  • How to communicate with iframes inside WebView is another good article with code samples etc. You can find this article and other information on Medium
  • Android Communication with WebView using JavaScript this is a good "answer" to a question posted on StackOverflow
• Remember, only allow access to the GIDX Platform Web Session services once the customer has authenticated their account.

Get Familiar with the GIDX Platform

If your Target Environment is browser based Desktop, Tablet, Mobile Phone then all of the instructions needed for integration are already in place within this document. All of the user interface contained in the Web Session service are designed for a responsive environment and will dynamically adjust based on the customer device.

The following ReasonCodes act as "flags" or a short-hand language so that the merchants environment can quickly and easily understand the GIDX Service results.

• Identity
• Device Fingerprint
• Location Service
• Payment / Cashier

Testing Tools & Data

Below is a sample of the interface you will receive when utilizing "integration" mode when connecting to a GIDX Platform Web Session service. In order to leverage the Sandbox Integration Mode environment you will need to prefix your "MerchantSessionID" with the characters "GIDXSB_".

This tool should be used to test the Response and CallBack results based on different pre-defined scenarios.

You will need to adjust the callback URL to match your own server address and directory structure.

The prefix of "MSID_" within the MerchantSessionID field is reserved for internal use only and any MerchantSessionID that is presented in that format will automatically be marked as an internal TEST MODE session. Do not use this pre-fix on your MerchantSessionID’s.

The prefix of "MCID_" within the MerchantCustomerID field is reserved for internal use only and any MerchantCustomerID that is presented in that format will automatically be marked as an internal TEST MODE customer. Do not use this pre-fix on your MerchantCustomerID’s.

Additional testing tools and materials can be accessed below for Customer Identity, Payments, Location, etc.

• Customer Identity Testing Scenario
• Location Test Data
• Sample Payment Credit Cards and other Account information

Merchant Settings

GIDX Platform Services are partially controlled by the associated settings applied to the merchant account. These settings allow the merchant to apply standardization to processes and methodologies applied to these services by the customer for identity, location, payments, watch list services and much more.

Please review the settings below so that you are familiar with the control you will have over the integrated services.

• SSN Requirement: The requirement for a customer to verify last 4 digits of SSN. (US Customers Only)
  If "SSN Required" is ON then your customers will be required to verify the last 4 digits of their Social Security Number as part of the verification process.
• KBA Requirement: The requirement for a customer to pass the KBA process during the WebReg Service.
  If the KBA Service (Knowledge Based Authentication) is required your customers will be asked to correctly answer a series of questions that represent information within their identity profile that only they should have the answers.
• Allowed Identity Verification Attempts: The number of times that a customer may attempt ID verification within a single session.
  If a customer is not found based on their initial verification attempt they are allowed to re-try to verify themselves using additional or modified personal information. Example: Update their address, provide their real name instead of a nickname, etc.
• Citizenship Location Dependent ID Verification: Requirement for Payment
  The countries that require a successfully verified customer registration to process a transaction. Registration will still be attempted for other countries. If setting is empty, all countries are required. The default countries that require the customer be ID-VERIFIED before a payment will be processed are: CA, GB, US

• Identity Requirement for Payments: If and when should the customer identity verification process take place in regards to a payment.
  When a customer initiates the payment service you have the option to require that their identity is successfully VERIFIED before a payment will be processed. If the requirement is set to active then you can choose for this identity verification process to happen before OR after the first payment is completed. If the requirement is active the payment may be completed before identity verification but will be placed in a pending state until their identity verification has been successfully complete.
• Citizenship Location Dependent ID Verification: Requirement for Payment
  The countries that require a successfully verified customer registration to process a transaction. Registration will still be attempted for other countries. If setting is empty, all countries are required. The default countries that require the customer be ID-VERIFIED before a payment will be processed are: CA, GB, US
• Deposit Amount Range & Bonus Management: Manage the default/base amount options available to a customer.
  If activated the Dynamic Bonus Management service can manage the amount that is available to your customer during the Cashier Service. The bonus amount is based on calculations that you provide and can be customized according to the amount of the selected deposit.
• Deposit & Payout Amount Minimum, Maximum, and Rules: Control the minimum and maximum deposit & payout amounts for a customer.
  The Cashier Service will automatically calculate the available deposit amounts to display to a customer based on these settings and the customer's deposit history with your account.

• Report on all Locations: Log and Report the location on every session.
  Activating this session will allow you to get the session location of the customer within the response of the API method call and/or callback. You can manage the locations that are returned within the ReasonCodes by clicking on the "GEO-LOCATION" tab above and turning the switch on or off next the country or US State of your choice.
• Report on all Blocked Locations: Set specific Locations to be Blocked / Reported.
  Activating this session will allow you to get the session location of the customer when they are within one of the locations that is set to be reporting as "BLOCKED" within the response of the API method call and/or callback. You can manage the locations that are returned within the ReasonCodes by clicking on the "Locations to Block" tab above and turning the switch on or off next the country or US State of your choice.