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

npm install @atlas/react

Basic Usage

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

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

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:

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:

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

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

No additional code is needed for 3DS support.

Error Handling

<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

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

Getting Started

Payments

UI Components

Billing

Data & Security

Mobile

Developer

Payment Sheet

Overview

Installation

Basic Usage

Props

Appearance Customization

Payment Result

Programmatic Control

Hook Methods

Apple Pay Integration

3D Secure Handling

Error Handling

Error Object

​Overview

​Installation

​Basic Usage

​Props

​Appearance Customization

​Payment Result

​Programmatic Control

​Hook Methods

​Apple Pay Integration

​3D Secure Handling

​Error Handling

​Error Object

Overview

Installation

Basic Usage

Props

Appearance Customization

Payment Result

Programmatic Control

Hook Methods

Apple Pay Integration

3D Secure Handling

Error Handling

Error Object