Skip to main content
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

PropTypeRequiredDescription
clientSecretstringYesClient secret from the payment session (cs_xxx)
appearanceobjectNoAppearance customization
onReadyfunctionNoCalled when the payment form is ready
onChangefunctionNoCalled when form validation state changes
onSuccessfunctionNoCalled when payment succeeds
onErrorfunctionNoCalled when an error occurs
onFocusfunctionNoCalled when a field gains focus
onBlurfunctionNoCalled when a field loses focus
classNamestringNoAdditional CSS class name
minHeightnumberNoMinimum height of the payment form (default: 300)
loadingbooleanNoShow loading state
disabledbooleanNoDisable 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

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

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