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

# Payment Sheet

A fully responsive, mobile-optimized checkout sheet. Automatically handles Apple Pay, Google Pay, and card entry with built-in animations and validation.

## Overview

The Payment Sheet is designed to sit on top of your existing UI and provide a native checkout experience. It automatically adapts to the user's device theme (Light/Dark) and handles all payment method logic.

## Installation

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

## Basic Usage

```tsx theme={null}
import { AtlasProvider, PaymentSheet } from '@atlas/react';

export function Checkout() {
  return (
    <AtlasProvider
      publishableKey="pk_test_..."
      environment="sandbox"
    >
      <PaymentSheet
        clientSecret="cs_test_..."
        applePay={{
          merchantId: 'merchant.com.acme',
          countryCode: 'US'
        }}
        appearance={{
          theme: 'light',
          variables: { borderRadius: '12px' }
        }}
        onSuccess={(payment) => {
          console.log('Payment successful:', payment.id);
        }}
      />
    </AtlasProvider>
  );
}
```

## Props

| Prop           | Type     | Required | Description                                       |
| -------------- | -------- | -------- | ------------------------------------------------- |
| `clientSecret` | string   | Yes      | Client secret from the payment session (cs\_xxx)  |
| `appearance`   | object   | No       | Appearance customization                          |
| `onReady`      | function | No       | Called when the payment form is ready             |
| `onChange`     | function | No       | Called when form validation state changes         |
| `onSuccess`    | function | No       | Called when payment succeeds                      |
| `onError`      | function | No       | Called when an error occurs                       |
| `onFocus`      | function | No       | Called when a field gains focus                   |
| `onBlur`       | function | No       | Called when a field loses focus                   |
| `className`    | string   | No       | Additional CSS class name                         |
| `minHeight`    | number   | No       | Minimum height of the payment form (default: 300) |
| `loading`      | boolean  | No       | Show loading state                                |
| `disabled`     | boolean  | No       | Disable the form                                  |

## Appearance Customization

```tsx theme={null}
<PaymentSheet
  clientSecret="cs_test_..."
  appearance={{
    theme: 'default', // 'default', 'night', or 'minimal'
    variables: {
      colorPrimary: '#06b6d4',
      colorBackground: '#ffffff',
      colorText: '#1e293b',
      colorDanger: '#ef4444',
      colorSuccess: '#22c55e',
      fontFamily: 'system-ui, sans-serif',
      fontSizeBase: '16px',
      borderRadius: '8px',
      borderColor: '#e2e8f0',
      spacingUnit: '4px',
    }
  }}
/>
```

## Payment Result

On success, you receive a `PaymentResult` object:

```typescript theme={null}
interface PaymentResult {
  id: string;
  status: 'succeeded' | 'processing' | 'requires_action' | 'failed';
  amount: number;
  currency: string;
  payment_method?: {
    type: string;
    card?: {
      brand: string;
      last4: string;
      exp_month: number;
      exp_year: number;
    };
  };
  wallet?: {
    type: 'apple_pay' | 'google_pay';
    card_network?: string;
  };
}
```

## Programmatic Control

Use the `usePaymentSheet` hook to control the payment form programmatically:

```tsx theme={null}
import { usePaymentSheet } from '@atlas/react';

function CheckoutForm() {
  const { confirm, clear, focus, update } = usePaymentSheet();

  const handleSubmit = async () => {
    update({ loading: true });
    await confirm();
  };

  return (
    <>
      <PaymentSheet clientSecret="cs_test_..." />
      <button onClick={handleSubmit}>Pay Now</button>
      <button onClick={clear}>Clear Form</button>
    </>
  );
}
```

### Hook Methods

| Method              | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| `confirm(options?)` | Trigger payment confirmation                                         |
| `clear()`           | Clear all form fields                                                |
| `focus(field)`      | Focus a specific field ('cardNumber', 'expiry', 'cvc', 'cardHolder') |
| `update(options)`   | Update form state (disabled, loading)                                |

## Apple Pay Integration

The Payment Sheet automatically shows Apple Pay when available:

```tsx theme={null}
<PaymentSheet
  clientSecret="cs_test_..."
  applePay={{
    merchantId: 'merchant.com.yourcompany',
    countryCode: 'US',
    merchantName: 'Your Company'
  }}
/>
```

Requirements:

* Valid Apple Developer account
* Apple Pay merchant ID registered in Atlas dashboard
* HTTPS domain with Apple Pay domain verification

## 3D Secure Handling

The Payment Sheet automatically handles 3D Secure authentication. When a card requires 3DS, the SDK:

1. Opens the 3DS challenge in an iframe
2. Handles the authentication flow
3. Completes the payment automatically
4. Calls `onSuccess` or `onError` based on the result

No additional code is needed for 3DS support.

## Error Handling

```tsx theme={null}
<PaymentSheet
  clientSecret="cs_test_..."
  onError={(error) => {
    console.error('Payment failed:', error.message);
    console.error('Error code:', error.code);
    console.error('Decline code:', error.declineCode);
  }}
/>
```

### Error Object

```typescript theme={null}
interface PaymentError {
  message: string;    // Human-readable message
  code: string;       // Error code for programmatic handling
  declineCode?: string; // Card-specific decline reason
}
```