OpenTransact

This site uses Just the Docs, a documentation theme for Jekyll.

Search

OpenTransact Javascript SDK

Current Version: alpha-9

Please check out the demo application repository for an example application which implements the OpenTransact Javascript SDK.

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 certain 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-9/core.js"></script>

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

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 a 3DS2 SCA is required to be triggered, the object metadata will have a threeDS2 key with a value like:

{
    required: true,
    ...
}

When implementing browser based 3DSecure Authentication, you should poll the resource for updates and trigger the threeDSecure workflow.

window.client.poll("accounts", accountId, {
  update: async (updatedAccount, next, complete) => {
    console.log("Received updated account");
    console.log(updatedAccount);

    if (updatedAccount.status == "active") {
      complete();
    } else if (updatedAccount.status == "invalid") {
      complete();
      console.log("Authentication Failed");
    } else if (
      updatedAccount.metadata.threeDSecure &&
      updatedAccount.metadata.threeDSecure.required
    ) {
      console.log("Triggering 3DS2");
      let result = await window.client.triggerThreeDSecure(
        updatedAccount,
        threeDS2Options
      );
      next(0);
    } else {
      next();
    }
  },
  error: (error) => console.log(error),
  timeout: () => console.log("Account polling timed out."),
});

Calling this function will load the appropriate 3DS2 flow, and return the result when complete. If successful, the account will move to ‘active’ status in this callback, or the transaction will continue processing.

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

Table of contents