paytools-3ds/README.md

3D secure implementation with a single line of code

# Introduction 
This is a Typescript/javascript library that performs ThreeD Secure authentication. 

# Getting Started
1.	Installation process
Use: npm i paytools-3ds

2.	Software dependencies
None.

3.	Change log
3.0.0 - Typescript version.
Contains changes:
    Typescript implementation (includes .d.ts file).
    Support (MasterCard) SLI (Security level information).
    Use Promise pattern.
    Implemented as class.

3.0.1-beta.1
Support parameters customerEmail and customerPhone.

3.0.1-beta.2
Added constructor with default api base url.

3.0.1-beta.3
Fix packaging issue.

3.0.1-beta.4
Fix packaging issue.

3.0.1-beta.5
Fix packaging issue.

3.0.1-beta.6
Support eWallet operations.

3.1.0-beta.0
Support card-token based 3ds operation.
Fix challenge form display.
Added event for Gui interaction.

3.1.0-beta.1
Support Attempt without Authentication.

3.1.0-beta.2
Add options to constructor for supporting postMessage upon challenge loading.

3.1.0-beta.3
Add option to display the challenge form within the hosting page.

3.1.0-beta.4
Add scrolling and fix 'position' to display the challenge form within the hosting page.

3.2.0-beta.0
Add support for CyberSource.
Extend supported cards list in demo.

3.2.0-beta.1
Added validation of card brand.

3.2.1 - bad version

3.2.2
Avoid brand checking in case of card token and no card data.

3.2.3
Prefer brnd3ds checking over brnd.

4.	API references
The library contains a single api.

Call:

Classic pattern
    perform3ds(sessionToken, iFrameElementSelector, [cardData], [cardToken])
    .then(message => {...});

await pattern
    const message = await perform3ds(sessionToken, iFrameElementSelector, [cardData], [cardToken]);

Parameters
----------
sessionToken
Token obtained from the Orchestra service (see testing below)

iFrameElementSelector {string}
Selector of element in which a challenge iFrame is to be created

cardData {Object}
The card details to be authenticated in the following format:

    {
        cardType: "", // 'Visa', 'MasterCard', 'AMEX', 'Discover', ...
        cardNumber: "",
        expirationYear: number,
        expirationMonth: number,
        cardHolderName: "",
        customerEmail: string,
        customerPhone: string
    };

    Note that either customerEmail or customerPhone must be populated.
    
cardToken {string}
    A representation of the card object hosted on the server.


message
The authentication results object.
The results object has a member named 'messageType' and optional members, based on the MessageType.

result structure
{
    messageType: "",
    ... other members
}

Authenticated message
{
    messageType: "Authenticated",
    threeDs: {
        authenticationValue: "",
        eci: "",
        xid: "",
        version: "",
        sli: ""
    }
}

Rejected message
{
    messageType: "Rejected",
    reason: ""
}

CardNotEnrolled message
{
    messageType: "CardNotEnrolled"
}

TechnicalProblem message
{
    messageType: "TechnicalProblem",
    reason: "",
    reference: ""
}


onPresentingGui
---------------
This is an optional event that is triggered when the 3ds requires user interaction or after user interaction is completed.
Sample usage:
        var tds = new threeDs.Engine();
        // Set event handlers to show/hide throbber
        tds.onPresentingGui = (isOn) => toggleThrobber(!isOn);


# Build and Test
In order to use the library, you will need to have an account with Orchestra. Use https://www.bluetime.io


You may use the index.html as an example for using the library.