> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlaspay.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Elements SDK

Embed secure payment fields directly in your checkout page. Card data is tokenized client-side and never touches your servers.

## Overview

The Elements SDK renders secure iframes on your page for collecting payment details. This gives you full control over your checkout UX while Atlas handles PCI compliance.

## Installation

```bash theme={null}
npm install @atlas/elements
```

Or include via CDN:

```html theme={null}
<script src="https://js.atlas.co/v1/atlas.js"></script>
```

## Integration Flow

### Step 1: Create Session (Server-side)

```javascript theme={null}
// Your server
const sessionRes = await fetch('https://api.atlas.co/functions/v1/create-session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 4990,
    currency: 'USD',
    merchant_reference: 'order_12345'
  })
});
const session = await sessionRes.json();
// Return client_secret to your frontend
```

### Step 2: Initialize SDK (Client-side)

```javascript theme={null}
import { Atlas } from '@atlas/elements';

Atlas.init({
  publishableKey: 'pk_test_xxx',
  environment: 'sandbox' // or 'production'
});
```

### Step 3: Mount Payment Form

```javascript theme={null}
Atlas.mount({
  elementId: 'payment-form', // Your div id
  clientSecret: session.client_secret,
  appearance: {
    theme: 'night',
    variables: {
      colorPrimary: '#0ea5e9'
    }
  },
  onSuccess: (payment) => {
    // Payment complete! SDK called confirm-payment automatically
    console.log('Payment succeeded:', payment.id);
    window.location.href = '/success';
  },
  onError: (error) => {
    console.error('Payment failed:', error.message);
  }
});
```

### Step 4: Add Container to Your Page

```html theme={null}
<div id="payment-form"></div>
```

## Appearance Customization

Customize the look and feel to match your brand:

```javascript theme={null}
Atlas.mount({
  elementId: 'payment-form',
  clientSecret: session.client_secret,
  appearance: {
    theme: 'stripe', // 'stripe', 'night', 'flat', or 'none'
    variables: {
      colorPrimary: '#0ea5e9',
      colorBackground: '#ffffff',
      colorText: '#1a1a1a',
      colorDanger: '#ef4444',
      fontFamily: 'system-ui, sans-serif',
      borderRadius: '8px',
      spacingUnit: '4px'
    },
    rules: {
      '.Input': {
        border: '1px solid #e5e7eb',
        boxShadow: 'none'
      },
      '.Input:focus': {
        border: '1px solid #0ea5e9',
        boxShadow: '0 0 0 1px #0ea5e9'
      }
    }
  }
});
```

## Events

| Event                | Description                         |
| -------------------- | ----------------------------------- |
| `onSuccess(payment)` | Payment completed successfully      |
| `onError(error)`     | Payment failed or was declined      |
| `onReady()`          | Form is mounted and ready for input |
| `onChange(event)`    | Form field values changed           |
| `onFocus(field)`     | A field received focus              |
| `onBlur(field)`      | A field lost focus                  |

## Response

On success, you receive the payment object:

```json theme={null}
{
  "id": "pay_8xM2nQ4vR7kL9pYz",
  "session_id": "sess_2xK9mN7vQ3pL8wYz",
  "amount": 4990,
  "currency": "USD",
  "status": "captured",
  "payment_method_type": "card",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2025
  }
}
```