OpenTransact Javascript SDK

Current Version: alpha-1

This repository contains a demo of the OpenTransact Javascript SDK and documentation for using the SDK to connect web based applications with the OpenTransact API. You can find more details on the OpenTransact API on the documentation for the REST API. The release is currently in an alpha state and the APIs may change. We will make every effort to communicate changes to anyone using the SDK and/or issue a new version when breaking changes occur.

While support for all objects and interactions in our API as well as installation via npm are planned, the javascript SDK is currently limited to specific use cases.

Include the Javascript in your web application

Currently only support via script tags is supported:

<!doctype html>
<html lang="en">

<head></head>
<body>
    <!-- Your application markup here... -->


    <!-- Import OpenTransact Javascript SDK -->
    <script src="https://js.opentransact.com/alpha-1/core.js"> </script>

    <script>
        // Application code and interacting with the SDK here.
    </script>
</body>

Initialize the Client

The client is initialized with a ClientToken obtained by your server from the OpenTransact API. See docs here.

let client = OpenTransact.init(token)

Fetch Resources from the API for Use in your Application

let profileResponse = await client.get('profiles', profileId)

Use form helpers to extract data from forms in your application (*optional)

The client comes with form helpers to help extract data from forms in your application.

You can add an attribute to form fields in the format data-opentransact-{resource}="{value}" where resource is the lowercase name of a resource in the OpenTransact API.

Related values like owner-id can be set as well.

Example Form:

<form id="credit-card-form">
    <input type="hidden" name="account-account-type" id="account-account-type"
        data-opentransact-account="account-type" value="credit-cards">

    <input type="hidden" name="account-owner-id" id="account-owner-id"
        data-opentransact-account="owner-id">

    <input type="hidden" name="account-billing-address-id" id="account-billing-address-id"
        data-opentransact-account="billing-address-id">

    <div>
        <label for="account-nickname">Account Nickname</label>

        <input type="text" name="account-nickname" data-opentransact-account="nickname">
    </div>

    <div>
        <label for="account-cardholder">Cardholder Name</label>

        <input type="text" name="account-cardholder"
            data-opentransact-account="cardholder-name">
    </div>

    <div>
        <label for="creditCard">Card Number</label>
        <input type="text" name="account-card-number" id="account-card-number"
            data-opentransact-account="card-number">
    </div>

    <div>
        <label for="cvv">Security Code</label>
        <input type="text" name="cvv" id="cvv" data-opentransact-account="cvv">
    </div>
</form>

Example extraction:

let form = document.getElementById("credit-card-form");
let account = OpenTransact.extractAccount(form);

Create or update resources in the API

Calls to client.create and client.update take ojbects which match the structure from the REST API documentation. All keys should be provided as documented. Ie (use ‘billing-address-id’ as the key and not ‘billingAddressId’ like you may with normal JS conventions).

let accountResponse = await client.create(account); // Takes CreateAccountRequest object
// do something with the response
if (accountResponse.success) { doStuff(accountResponse.resource) }
let accountUpdateResponse = await client.update(account); //Takes UpdateAccountRequest object

Trigger a 3DS2 Flow for your Gateway

Currently via the API we support a convention for triggering SCA via the account metadata.

When an account requires 3DS2 SCA to be triggered, the account will have status 'new' and metadata will have a threeDS2 key with a value like:

{
    required: true,
    ...
}

You will then pass this object to the call to loadThreeDS2 with success and error callbacks:

if (account.status === 'new' && account.metadata.threeDS2 && account.metadata.threeDS2.required) {
    threeDS2Config = account.metadata.threeDS2;
    // If the account has a threeDS2 requirement, and has not already been processed, then process it
    if (threeDS2Config && threeDS2Config.required && !threeDS2Config.response) {
        const threeDS2Response = await window.client.triggerThreeDS2(threeDS2Config);

        // update the account with the ThreeDS2 Response details;
        const updateAccountRequest = {
            type: "accounts",
            id: accountId,
            attributes: {
                metadata: {
                    threeDS2: {
                        response: threeDS2Response.threeDSecure
                    }
                }
            }
        }
        const updateAccountResponse = await window.client.update(updateAccountRequest);
        if (updateAccountResponse.success) {
            // Restart Polling the Account
            pollAccount(accountId);
        } else {
            // Show an error
            console.log("Error Updating Account with ThreeDS2 Info")
        }
}

Calling this function will load the appropriate 3DS2 flow for the configured gateway, and return the result when complete. You should update the account with the appropriate info before proceeding. Once complete, you can resume checking to see if the account has moved to ‘active’ status in this callback.

If you are processing a new transaction against an existing account, follow the same procedure, replacing the account object in the example with the transaction object. In this case you may create the transaction object via your server integration, so just pass the details to your front end or provide the ID so the front end can fetch the required info from the API.

See the 3DS2 Guide for more info on various use cases.


Table of contents