Atlas Interpreter

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.

This guide covers:

1. How to embed the Atlas gateway script.
2. How to collect and structure billing and transaction details.
3. 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

1<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:

Important: 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.
• 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.

Line Item Example:

1[
2  {
3    "productname": "Widget A",
4    "description": "Blue widget",
5    "qty": 2,
6    "unitprice": 5.00
7  },
8  {
9    "productname": "Service B",
10    "description": "Setup fee",
11    "qty": 1,
12    "unitprice": 25.00
13  }
14]

5. Hidden Fields

Setup Example:

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

Security Note: In production, x_tran_key should be securely stored on the server and never exposed in client-side JavaScript.

6. Gateway Card Tokenization

Mount Point:

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

Events:

• Success: When the card is successfully tokenized, the script dispatches:

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

• Failure: On failure, the script dispatches:

1window.dispatchEvent(
2  new CustomEvent('gw:token-error', { detail: { status, error } })
3);
4// or for validation failures:
5window.dispatchEvent(
6  new CustomEvent('token-null', {
7    detail: { message: 'Input validation failed.' }
8  })
9);

7. Styling

Atlas mounts card fields using consistent class names. You can style them to fit your brand while preserving usability and validation feedback.

Example CSS:

1.gw-field {
2  margin: 8px 0;
3}
4
5.gw-field label {
6  display: block;
7  font-weight: 600;
8  margin-bottom: 6px;
9}
10
11.gw-input {
12  box-sizing: border-box;
13  width: 280px;
14  padding: 10px;
15  border: 1px solid #ccc;
16  border-radius: 4px;
17  font-size: 14px;
18}
19
20.gw-input:focus {
21  outline: none;
22  border-color: #0066cc;
23  box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.15);
24}
25
26.gw-error {
27  color: #b00020;
28  display: block;
29  margin-top: 4px;
30  font-size: 12px;
31}
32
33.gw-field-messages .gw-error {
34  margin-top: 8px;
35}
36
37.gw-row {
38  display: flex;
39  gap: 16px;
40  flex-wrap: wrap;
41}
42
43.gw-row .gw-field {
44  flex: 1 1 140px;
45  min-width: 140px;
46}

Visibility Control: The interpreter toggles error visibility via the hidden attribute and inline display style to ensure consistency. Avoid overriding these directly.

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.

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

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

9. Transaction Payload Structure

The transaction payload must include all required fields for payment processing:

1{
2  "token": "string",
3  "amount": "10.00",
4  "merchant": "TWINOAKSPLACE",
5  "x_login": "DEMO",
6  "x_tran_key": "PASSWORD",
7  "transtype": "AUTH_CAPTURE",
8  "billing": {
9    "first_name": "John",
10    "last_name": "Doe",
11    "address": "123 Street",
12    "city": "Los Angeles",
13    "state": "CA",
14    "zip": "90001",
15    "country": "USA",
16    "email": "john@example.com",
17    "notes": "Optional notes here",
18    "company": "Acme Inc",
19    "phone": "+1-555-555-5555",
20    "shipping_first_name": "Jane",
21    "shipping_last_name": "Doe",
22    "shipping_address": "456 Avenue",
23    "shipping_city": "Los Angeles",
24    "shipping_state": "CA",
25    "shipping_zip": "90002",
26    "shipping_country": "USA",
27    "shipping_phone": "+1-555-555-0000",
28    "shipping_email": "jane@example.com",
29    "surcharge_amount": "0.50",
30    "tax_amount": "0.75",
31    "shipping_amount": "5.00",
32    "discount_amount": "1.00",
33    "customer_id": "CUST-123",
34    "subscription_id": "SUB-456",
35    "custom_fields_1": "Blue",
36    "custom_fields_2": "Promo-2025",
37    "custom_fields_3": "Department-7",
38    "line_items": "[{\"productname\":\"Widget A\",\"description\":\"Blue widget\",\"qty\":2,\"unitprice\":5.00}]"
39  }
40}

Note: The line_items field must be a JSON string containing an array of product objects. Serialize your line items array before including it in the payload.

10. Endpoint Details

• URL: https://[gateway_url]/atlas/transact_token.php
• Method: POST
• Content-Type: application/json
• Header: X-App-Source: domain.com/checkout.html

Best Practice: Update the X-App-Source header to match your actual domain or app name (e.g., 'shop.example.com/checkout').

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).

Display Div:

1<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.