gidx-js

v0.6.2

Published

a month ago

Client-side Javascript utilities for GambleID

0High
0Medium
0Low

nick.miller

library gambleid gidx

gidx-js

Client-side Javascript utilities for GambleID.

This library includes utilities for:

Install

As a script tag (added to window.GIDX):

<script src="https://cdn.jsdelivr.net/npm/gidx-js"></script>

<script>
    //Library is added to window.GIDX
    let threeDS = window.GIDX.get3DSDeviceData();
</script>

As a module:

import * as GIDX from 'https://cdn.jsdelivr.net/npm/gidx-js/+esm'

As a NPM package:

$ npm install gidx-js
import * as GIDX from 'gidx-js';

Initialization

First, call the init function with your GIDX Merchant ID and target environment.

GIDX.init({
    merchantId: "5OQAQWZbkkSdEmlfVxsNlA",
    environment: "sandbox" //or production
});

Tokenization

You must use this library to collect credit card information from your users to avoid PCI compliance issues.

Usage

See the commented code sample below.

//First, make sure to initialize the library with your GIDX Merchant ID and target environment
GIDX.init({
    merchantId: "5OQAQWZbkkSdEmlfVxsNlA",
    environment: "sandbox" //or production
})

//Get the Tokenizer configuration returned in the CreateSession response
let ccSettings = createSessionResponse.PaymentMethodSettings.find((s) => s.Type === "CC"); //Or look for Type === "ACH" for bank accounts.

//Call the function to render the form inside of your HTML element
GIDX.showPaymentMethodForm(
    'id-of-html-element', //The id of the HTML element. Must already exist on the page.
    {
        merchantSessionId: '1234', //Must be the same MerchantSessionID provided to the CreateSession API.
        paymentMethodTypes: ['CC'],
        tokenizer: ccSettings.Tokenizer,
        onSaved: function (paymentMethod) {
            //The full PaymentMethod object returned from our API is passed to this function.
            //Use it to populate your CompleteSession request and finalize the transaction.
            let completeSessionRequest = {
                MerchantSessionID: '1234',
                PaymentMethod: {
                    Type: paymentMethod.Type,
                    Token: paymentMethod.Token
                }
            };
        }
    });

Manually submit

To submit the payment method to be saved, you should call submit on the object returned from showPaymentMethodForm, as shown below.

let form = GIDX.showPaymentMethodForm(
    'id-of-html-element', //The id of the HTML element. Must already exist on the page.
    {
        merchantSessionId: '1234', //Must be the same MerchantSessionID provided to the CreateSession API.
        paymentMethodTypes: ['CC'],
        tokenizer: ccSettings.Tokenizer,
        onSaved: function (paymentMethod) {
            //The full PaymentMethod object returned from our API is passed to this function.
            //Use it to populate your CompleteSession request and finalize the transaction.
            let completeSessionRequest = {
                MerchantSessionID: '1234',
                PaymentMethod: {
                    Type: paymentMethod.Type,
                    Token: paymentMethod.Token
                }
            };
        }
    });

//When you are ready to submit, call this function.
form.submit();

Billing address

You must set the billing address of the payment method before we can save it. You can do this by providing the onSaving callback. This callback allows you to make any changes to the PaymentMethod API request before it is sent.

GIDX.showPaymentMethodForm('id-of-html-element', {
    merchantSessionId: '1234',
    paymentMethodTypes: ['CC'],
    tokenizer: ccSettings.Tokenizer,
    onSaved: function (paymentMethod) { },
    onSaving: function (request) {
        //Here you could get the address information from other inputs on the page that you control.
        request.paymentMethod.billingAddress = {
            addressLine1: '123 Main St.',
            city: 'Houston',
            stateCode: 'TX',
            postalCode: '77001'
        };
    }
})

CVV only

To allow the user to re-enter their CVV for an existing credit card, use the cvvOnly option. Only a single input for the CVV will be rendered. You can then call the getCvv function to collect the encrypted CVV and pass it to your backend for your CompleteSession API request.

let form = GIDX.showPaymentMethodForm('id-of-html-element', {
    merchantSessionId: '1234',
    paymentMethodTypes: ['CC'],
    tokenizer: ccSettings.Tokenizer,
    cvvOnly: true
});

//Then populate the CVV of your CompleteSession API request with getCvv
let completeSessionRequest = {
    MerchantSessionID: '1234',
    PaymentMethod: {
        Type: 'CC',
        Token: '707435d1-998c-4463-9367-c7ecf584e10d',
        CVV: form.getCvv()
    }
};

Customizing the tokenization form

Along with the options documented here, you can also provide any of the options that the Evervault JS library accepts.

GIDX.showPaymentMethodForm('id-of-html-element', {
    merchantSessionId: '1234',
    paymentMethodTypes: ['CC'],
    tokenizer: ccSettings.Tokenizer,
    onSaved: function (paymentMethod) { },

    theme: 'material'
});

Apple Pay and Google Pay

We support Apple Pay and Google Pay using the same tokenization framework outlined above through the showAppleBayButton and showGooglePayButton methods.

Usage

See the commented code sample below.

//Get the Tokenizer configuration returned in the CreateSession response
let applePaySettings = createSessionResponse.PaymentMethodSettings.find((s) => s.Type === "ApplePay"); //Or look for Type === "GooglePay".

//Call the function to render the form inside of your HTML element
GIDX.showApplePayButton(
    'id-of-html-element', //The id of the HTML element to insert the button into. Must already exist on the page.
    {
        merchantSessionId: '1234', //Must be the same MerchantSessionID provided to the CreateSession API.
        tokenizer: applePaySettings.Tokenizer,

        //Apple and Google require some information on the transaction
        transaction: {
            amount: 1000 //The amount in cents (ex $10 = 1000)
        },
        onSaving: function (request) {
            //Here you could get the address information from other inputs on the page that you control.
            request.paymentMethod.billingAddress = {
                addressLine1: '123 Main St.',
                city: 'Houston',
                stateCode: 'TX',
                postalCode: '77001'
            };
        },
        onSaved: function (paymentMethod) {
            //The full PaymentMethod object returned from our API is passed to this function.
            //Use it to populate your CompleteSession request and finalize the transaction.
            let completeSessionRequest = {
                MerchantSessionID: '1234',
                PaymentMethod: {
                    Type: paymentMethod.Type,
                    Token: paymentMethod.Token
                }
            };
        }
    });

Customizing the buttons

Along with the options documented here, you can also provide any of the options that the Evervault JS library accepts. See their docs on Apple Pay and Google Pay customizations.

//Call the function to render the form inside of your HTML element
GIDX.showApplePayButton('id-of-html-element', {
    merchantSessionId: '1234',
    tokenizer: applePaySettings.Tokenizer,
    transaction: { amount: 1000 },
    onSaved: function (paymentMethod) { },

    style: 'black',
    size: {
        width: '200px',
        height: '40px'
    }
});

3DS

3D Secure (3DS, ThreeDS) can be used to protect a credit card deposit from chargebacks. Some processors, like Approvely Rapid, require you use their 3DS implementation, but we also offer standalone 3DS through Evervault. This library provides functions to help you populate the PaymentMethod.ThreeDS object of your CompleteSession API requests, and handle 3DS challenges returned in the CompleteSession API response.

Populating the ThreeDS object

Populate the PaymentMethod.ThreeDS object of your CompleteSession API requests using the get3DSDeviceData function.

let completeSessionRequest = {
    PaymentMethod: {
        Type: "CC",
        Token: "{insert token here}",
        CVV: "123",
        ThreeDS: GIDX.get3DSDeviceData()
    }
};

Handling the 3DSChallenge Action

Handle the 3DSChallenge Action that can be returned from the CompleteSession API by calling the show3DSChallenge function.

let completeSessionResponse = {
    Action: {
        Type: "3DSChallenge",

        //Evervault 3DS challenges have these properties
        Provider: "Evervault",
        TransactionID: "tds_visa_b0237020561f",
        EvervaultTeamID: "team_1234",
        EvervaultAppID: "app_1234",

        //ApprovelyRapid 3DS challenges have these properties
        Provider: "ApprovelyRapid",
        TransactionID: "707435d1-998c-4463-9367-c7ecf584e10d",
        URL: "https://acs-public.tp.mastercard.com/api/v1/browser_challenges",
        CReq: "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI..."
    }
};

if (completeSessionResponse.Action?.Type == "3DSChallenge") {
    GIDX.show3DSChallenge(completeSessionResponse.Action, {
        onComplete: function (transactionId) {
            //Send another CompleteSession request after challenge is completed.
            let completeSessionRequest = {
                PaymentMethod: {
                    Type: "CC",
                    Token: "{insert token here}",
                    ThreeDS: {
                        TransactionID: transactionId,

                        //Optional. Only required if using Approvely Rapid's chargeback protection
                        DeviceID: window.nSureSDK?.getDeviceId()
                    }
                }
            };

            //Call CompleteSession API here
        }
    });
}

A 3DS challenge is a URL that gets loaded in a modal iframe that let's the user verify themselves with their bank. For more info on 3DS, see the Approvely Rapid docs or the Evervault docs.

Customizing the Approvely Rapid 3DS Challenge HTML

By default, the Approvely Rapid 3DS challenge is an HTML5 dialog element inserted into the body of your page. The HTML looks like this:

<dialog class="challenge-container">
    <iframe></iframe>
</dialog>

The default CSS is included in the library, but feel free to add your own CSS to your page.

For more advanced customization, you can provide insertElement and removeElement functions in your options object.

Processor Session ID

Some processors, like Finix, require you to use their own JS SDK's for monitoring risk and fraud. To do this, you must call GIDX.init on every page of your application. Then, you must pass the ProcessorSessionID in your CreateSession or CompleteSession API requests.

Initialization

Call this on every page. You will get the required processor's credentials when you go live.

GIDX.init({
    merchantId: "5OQAQWZbkkSdEmlfVxsNlA",
    environment: "sandbox" //or production,
    processorSessionId: {
        type: "Finix",
        merchantId: "You will get this from Finix. In sandbox you can leave it empty."
    }
})

Getting the Processor Session ID

Pass the ProcessorSessionID in either you CreateSession or CompleteSession API requests.

{
    "ProcessorSessionID": GIDX.getProcessorSessionId()
}

API Reference

gidx-js
- 3ds callbacks
  - .onComplete : function
  - .onShown : function
  - .insertElement ⇒ Element
  - .removeElement : function
- 3ds functions
  - .get3DSDeviceData() ⇒ DeviceData
  - .show3DSChallenge(action, options)
- 3ds objects
  - .Action : Object
  - .DeviceData : Object
  - .3DSChallengeOptions : Object
- tokenizer callbacks
  - .onLoad : function
  - .onUpdate : function
  - .onSaving : function
  - .onSaved : function
  - .onError : function
  - .onCancel : function
- tokenizer functions
  - .showPaymentMethodForm() ⇒ PaymentMethodForm
  - .showApplePayButton()
  - .showGooglePayButton()
- tokenizer objects
  - .PaymentMethodForm : Object
  - .TokenizationOptions : Object

GIDX.onComplete : function

Kind: static typedef of gidx-js
Category: 3ds callbacks

| Param | Type | Description | | --- | --- | --- | | transactionId | string | The transactionID to pass in the ThreeDS object of your second CompleteSession API request. |

GIDX.onShown : function

Kind: static typedef of gidx-js
Category: 3ds callbacks

| Param | Type | Description | | --- | --- | --- | | e | Element | The Element containing the challenge iframe. |

GIDX.insertElement ⇒ Element

Kind: static typedef of gidx-js
Returns: Element - The Element that was inserted into the page.
Category: 3ds callbacks

| Param | Type | Description | | --- | --- | --- | | e | Element | The Element to insert into the page. |

GIDX.removeElement : function

Kind: static typedef of gidx-js
Category: 3ds callbacks

| Param | Type | Description | | --- | --- | --- | | e | Element | The Element that was inserted into the page. |

GIDX.get3DSDeviceData() ⇒ DeviceData

Get the data required for the PaymentMethod.ThreeDS object passed to the CompleteSession API.

Kind: static method of gidx-js
Category: 3ds functions

GIDX.show3DSChallenge(action, options)

Show the 3DS challenge to the user.

Kind: static method of gidx-js
Category: 3ds functions

| Param | Type | Description | | --- | --- | --- | | action | Action | The Action (Type = "3DSChallenge") object returned from the CompleteSession API. Properties are case insensitive. | | options | 3DSChallengeOptions | Options for how to handle the challenge. At least onComplete is required. |

GIDX.Action : Object

Action object that is returned from the CompleteSession API when a 3DS challenge is required.

Kind: static typedef of gidx-js
Category: 3ds objects
Properties

| Name | Type | Description | | --- | --- | --- | | provider | string | The 3DS provider (ex "ApprovelyRapid" or "Evervault") | | url | string | | | creq | string | | | transactionId | string | Either the 3DS transaction ID, or for Evervault, their session ID |

GIDX.DeviceData : Object

Device data that is used to process 3DS.

Kind: static typedef of gidx-js
Category: 3ds objects
Properties

| Name | Type | Description | | --- | --- | --- | | colorDepth | number | | | screenHeight | number | | | screenWidth | number | | | timeZone | number | | | deviceId | string | The nSure deviceId to forward to Rapid/Coinflow. |

GIDX.3DSChallengeOptions : Object

Options used by show3DSChallenge.

Kind: static typedef of gidx-js
Category: 3ds objects
Properties

| Name | Type | Description | | --- | --- | --- | | onComplete | onComplete | Function called after challenge has been completed by the user. | | onShown | onShown | Function called after Element is inserted into the page. | | insertElement | insertElement | Insert the Element containing the challenge iframe into the page. Only for Rapid. | | removeElement | removeElement | Remove the Element containing the challenge iframe from the page. Only for Rapid. |