Checkout Reference

iTransact Checkout is an embeddable payment form that securely processes sensitive payment data for use with the iTransact JSON API.

What does processing a transaction with Checkout using tokens look like?

With iTransact Checkout, a customer’s sensitive payment data never hits your server, reducing your PCI compliance burden. By integrating with Checkout and enabling HTTPS on your payment page, iTransact handles the heavy lifting of PCI compliance.

You payment flow should look something like:

  1. A customer visits your payment page, loaded over HTTPS, with the Checkout <script> tag in a form.
  2. The customer clicks the payment button (e.g., Pay with Card) opening the Checkout panel. They complete the form with their payment details and click the panel’s pay button (e.g., Pay $14.99), submitting the payment details directly to iTransact’s servers.
  3. iTransact returns a token to Checkout if successful, or an error message if the payment details error from the card’s network.
  4. Checkout inserts hidden fields containing the token (itransactToken) and customer’s email (itransactEmail) into your payment form. Checkout then submits the form to your server.
  5. In a separate request to iTransact’s API, the token can be used for creating a transaction.

Checkout securely handles payment data but does not attempt a transaction. A separate server-side request in your code to iTransact is required to create a transaction.


Integrating Checkout

Checkout is an embedded tool that renders an HTML form and securely handles your customer’s payment data.

With Checkout, the customer’s sensitive payment data is sent directly to iTransact’s servers, returning a token to your site. The token, which represents the customer’s payment data, can then be used to create a transaction.

Two options are available to integrate Checkout:

  • Simple: With a single line of client-side code, Checkout adds a payment button, opening a payment panel when clicked. Following a successful submission of the payment form, Checkout adds a hidden field containing the token to your form and submits it to your server for use.

  • Custom: Create a button or event to open Checkout and handle the token with a JavaScript callback. Your callback should send the token to your server for use.

Simple Checkout Integration

To get started, place the following <script> tag into a form on your page with an action attribute that submits to your own server-side code:

<form action="/your-server-side-code" method="POST">
  <script
    src="https://js.itransact.com/itransact.js" class="itransact-checkout-modal"
    data-api-username="YOUR_API_USERNAME"
    data-name="iTransact.com"
    data-description="Payment Guide"
    data-amount="1299">
  </script>
</form>

Replace the values from the example with your own. Checkout only requires your API Username with the simple integration.

Custom Checkout Integration

With the custom integration, you can use any HTML element or JavaScript event to open Checkout. This method requires strong JavaScript knowledge to produce the same steps the simple integration performs for you.

You should create a handler object with iTransact.Checkout.init() that executes when your page loads. Then in response to any event, you can call render() to open the payment panel. Any configuration options can be passed to either init() or render().

<script src="https://js.itransact.com/itransact.js"></script>

<button id="custom-button">Payment</button>

<script>
var options = {
  apiUsername: 'YOUR_API_USERNAME',
  name: 'My Checkout Name',
  description: 'My Checkout Description',
  onToken: (data) => {
    // The token is available with `data.token`.
    // Send the token to your server for use.
  }
}

var handler = iTransact.Checkout.init(options)

document.getElementById('custom-button').addEventListener('click', function (event) {
  // Open Checkout (may include additional options)
  handler.render({
    amount: 2000
  })
  event.preventDefault()
})
</script>

Replace the values from the example with your own. Checkout only requires your API Username and an onToken callback with the custom integration.

Checkout must be loaded directly from https://js.itransact.com/itransact.js. Loading Checkout from any other source is unsupported.

Configuration options

The following options are available for you to customize how iTransact Checkout looks and behaves.

Required

  • data-api-username - Your API Username (live or test)
  • onToken - The callback invoked when Checkout receives a token. For use with custom integration only.
    • function(data, args)
      • data.token can be used to create a transaction or attached to a customer
      • data.email is the email addressed entered by the user in the payment panel
      • args is an object containing the billing addresses, if enabled
  • data-name - Your company name, website, product or service.
  • data-description - A description of the product or service for purchase.
  • data-amount - The amount in cents to be displayed to the customer. You will need to explicitly include this amount in your server-side request.
  • data-image - An image of your brand or the product sold. Provide an absolute URL to a square image at least 128x128px.
  • data-billing-address - Specify as true for Checkout to collect a billing address. Default: false.

Optional

  • data-email - The value will prefill in checkout’s form.
  • data-theme - Personalize the background of Checkout’s modal button with a hexadecimal color (#000000). The button’s text color will be black or white based on a contrast calculation.
  • data-button-text - Customize the text of the button inserted into your page’s form code. Defaults to Pay with Card. You have full control over this button’s style. For use with simple integration only.
  • data-panel-button-text - Customize the text of the button in Checkout’s form.
  • data-ach - Specify as true for Checkout to show check as a payment option. Default: false.

Errors

Prop errors

Occurring only for custom integrations, prop errors appear in a browser console for developers when Checkout is misconfigured. The following errors may appear when passing props to init or render methods:

  • Prop is required: PROP_NAME - Missing required configuration option.
  • Prop is not of type function: PROP_NAME - Incorrect prop type passed.

Validation erros

iTransact’s servers validate data submitted in Checkout’s payment form. Validation errors are visible to a customer when payment data contains errors.

One exception is Unauthorized which appears as a visible error in Checkout when the apiUsername used to configure checkout is invalid.


Security recommendations

A payment information submitted with Checkout is made with a secure HTTPS connection. We still recommend protecting yourself from other forms of man-in-the-middle attacks by serving your pages containing Checkout over HTTPS.

Review our security guide for additional security information.


Supported browsers

Checkout is intended to support all recent version of major browsers that continue to receive security updates. While we do our best to offer a great experience for a majority of users, we do not proactively test browsers that represent a small minority of traffic.

If you have an experience with a specific browser using Checkout, please contact us with details.


Next Steps

Once the token is submitted to your server, the following actions are common next steps: