Components

Overview

The SDK provides individual components that can be used to build custom payment experiences. Access them via client.components.*.

---

Available Components

Component	Description
Invoice Detail	Show detailed invoice information
Payment Method Select	List and select payment methods
Add Payment Method	Add new card or bank account
Payment Confirmation	Review and confirm payment
Payment Result	Display payment outcome

---

Using Components

All components share a common pattern:

// 1. Initialize the client
const client = new AlternativeClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

// 2. Create a component
const component = client.components.invoiceList({
  containerId: 'my-container',
  customerId: 'cus_xxx',
  onSelect: (invoice) => {
    console.log('Selected:', invoice);
  },
});

// 3. Later: cleanup
component.unmount();

---

Common Configuration

All components accept these base properties:

Property	Type	Required	Description
containerId	string	Yes	ID of the HTML element to mount into
theme	ThemeConfig	No	Custom theme (overrides client default)

---

Component Instance

Each component returns a ComponentInstance with these methods:

interface ComponentInstance {
  mount(): void;      // Mount to DOM (auto-called on creation)
  unmount(): void;    // Remove from DOM
  refresh(): Promise<void>;  // Refresh data
}

---

Building Custom Flows

Compose components to create custom payment experiences:

const client = new AlternativeClient({ ... });

let selectedPaymentMethod: PaymentMethod | null = null;
const invoiceId = 'inv_xxx';

// Step 1: Show payment method selection
const paymentSelect = client.components.paymentMethodSelect({
  containerId: 'container',
  customerId: 'cus_xxx',
  onSelect: (pm) => {
    selectedPaymentMethod = pm;
    paymentSelect.unmount();
    showConfirmation();
  },
  onAddNew: () => {
    paymentSelect.unmount();
    showAddPaymentMethod();
  },
});

// Step 2: Confirm and process
function showConfirmation() {
  const confirmation = client.components.paymentConfirmation({
    containerId: 'container',
    invoiceId: invoiceId,
    paymentMethodId: selectedPaymentMethod!.id,
    customerId: 'cus_xxx',
    onPaymentSuccess: (payment) => {
      confirmation.unmount();
      showResult('success', payment);
    },
    onPaymentError: (error) => {
      confirmation.unmount();
      showResult('error', undefined, error);
    },
  });
}

---

Next Steps

Explore individual component documentation for detailed configuration options and examples.