Atlas Interpreter – Sample Checkout Integration Guide

Overview

This document provides a reference implementation and explanation of how to use Atlas Interpreter on a checkout form to securely tokenize card data and submit transactions to the Expitrans Atlas API.

• How to embed the Atlas gateway script.
• How to collect and structure billing and transaction details.
• How to handle the gw:token-ready and gw:token-error events and perform a tokenized payment submission.

1. File Overview

Filename: checkout.html
Purpose: Demonstrates how to build a fully functional checkout form integrated with the Atlas payment gateway using token-based transactions.

2. Dependencies

<script src="https://[gateway_url]/atlas/gateway.js"></script>

This script securely mounts the payment card input fields and handles token generation. It triggers the gw:token-ready event once a card token is successfully created. On validation or tokenization failure, it emits gw:token-error and a client-side token-null event for form validation failures.

3. Gateway Environments

The gateway_url should be set depending on your environment:

When integrating, always confirm which environment you are pointing to before submitting live transactions.

Script include: Load gateway.js from the Atlas-hosted domain for your environment (develop.expitrans.com or secure.troute.io). Do not self-host the interpreter in production.

4. Form Structure

The checkout form (#payment-form) includes required and optional fields for billing, shipping, and transaction details.

[
  {"productname": "Widget A", "description": "Blue widget", "qty": 2, "unitprice": 5.00},
  {"productname": "Service B", "description": "Setup fee", "qty": 1, "unitprice": 25.00}
]

5. Hidden Fields

loginInput.value = "DEMO";
trankeyInput.value = "PASSWORD";

6. Gateway Card Tokenization

<div id="gateway-card-container"></div>

When the card is successfully tokenized, the script dispatches:

window.dispatchEvent(new CustomEvent('gw:token-ready', { detail: { token } }));

On failure, the script dispatches:

window.dispatchEvent(new CustomEvent('gw:token-error', { detail: { status, error } }));
window.dispatchEvent(new CustomEvent('token-null', { detail: { message: 'Input validation failed.' } }));

.gw-field { margin: 8px 0; }
.gw-field label { display: block; font-weight: 600; margin-bottom: 6px; }
.gw-input { box-sizing: border-box; width: 280px; padding: 10px; border: 1px solid #ccc; border-radius: 4px; font-size: 14px; }
.gw-input:focus { outline: none; border-color: #0066cc; box-shadow: 0 0 0 3px rgba(0,102,204,0.15); }
.gw-error { color: #b00020; display: block; margin-top: 4px; font-size: 12px; }
.gw-field-messages .gw-error { margin-top: 8px; }
.gw-row { display: flex; gap: 16px; flex-wrap: wrap; }
.gw-row .gw-field { flex: 1 1 140px; min-width: 140px; }

8. Handling Events

When gw:token-ready is triggered:

1. Retrieve the token.
2. Build a transaction payload from the form data.
3. Send the payload to the transaction endpoint.

fetch('https://[gateway_url]/atlas/transact_token.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-Source': 'domain.com/checkout.html'
  },
  body: JSON.stringify(payload)
});

When gw:token-error or token-null is triggered, surface validation or tokenization errors inline on the page without alerts.

9. Transaction Payload Structure

{
  "token": "string",
  "amount": "10.00",
  "merchant": "TWINOAKSPLACE",
  "x_login": "DEMO",
  "x_tran_key": "PASSWORD",
  "transtype": "AUTH_CAPTURE",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address": "123 Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "country": "USA",
    "email": "john@example.com",
    "notes": "Optional notes here",
    "company": "Acme Inc",
    "phone": "+1-555-555-5555",
    "shipping_first_name": "Jane",
    "shipping_last_name": "Doe",
    "shipping_address": "456 Avenue",
    "shipping_city": "Los Angeles",
    "shipping_state": "CA",
    "shipping_zip": "90002",
    "shipping_country": "USA",
    "shipping_phone": "+1-555-555-0000",
    "shipping_email": "jane@example.com",
    "surcharge_amount": "0.50",
    "tax_amount": "0.75",
    "shipping_amount": "5.00",
    "discount_amount": "1.00",
    "customer_id": "CUST-123",
    "subscription_id": "SUB-456",
    "custom_fields_1": "Blue",
    "custom_fields_2": "Promo-2025",
    "custom_fields_3": "Department-7",
    "custom_fields_4": "",
    "custom_fields_5": "",
    "custom_fields_6": "",
    "custom_fields_7": "",
    "custom_fields_8": "",
    "custom_fields_9": "",
    "custom_fields_10": "",
    "line_items": "[{\"productname\":\"Widget A\",\"description\":\"Blue widget\",\"qty\":2,\"unitprice\":5.00}]"
  }
}

10. Endpoint Details

URL: https://[gateway_url]/atlas/transact_token.php
Method: POST

Content-Type: application/json
X-App-Source: domain.com/checkout.html

The Atlas endpoint validates the token, processes the transaction, and returns a response. Responses may be JSON or Authorize.Net–style CSV. Parse JSON when available and fall back to raw text if needed for diagnostics.

11. Error Handling

The script handles:

• JSON parsing errors from malformed line items.
• Network or fetch errors.
• Gateway response errors (via data.error).
• Client-side validation errors (via token-null) and tokenization failures (via gw:token-error).

<div id="result"></div>

12. Example Integration Flow

1. Customer enters payment and billing info.
2. Atlas mounts card fields and generates a secure token.
3. gw:token-ready fires → script prepares the transaction payload.
4. Data is POSTed to Expitrans /transact_token.php.
5. Response is displayed (success or error).

13. Security Considerations

• Never expose sensitive credentials on the client side.
• Use HTTPS for all API interactions.
• Sanitize user input, especially for custom fields and notes.
• Validate X-App-Source in your backend logs for traceability.
• Use the Atlas-hosted scripts and endpoints; avoid embedding sensitive credentials in client-side code.