Payment Flow

Overview

The createPaymentFlow() method provides a complete, orchestrated payment experience. It handles navigation between all screens automatically, making it the easiest way to integrate payments.

---

Flow Screens

The payment flow progresses through these screens:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Invoice Detail │ ──▶ │ Payment Method  │ ──▶ │   Confirmation  │
│                 │     │    Selection    │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                ┌───────▼─────────┐
                                                │ Payment Result  │
                                                │                 │
                                                └─────────────────┘

1. Invoice Detail - Displays invoice information and line items

2. Payment Method Selection - Choose existing or add new payment method

3. Add Payment Method - Card or bank account form (if adding new)

4. Confirmation - Review payment details before submitting

5. Result - Success or error screen

---

Basic Usage

const flow = client.createPaymentFlow({
  containerId: 'payment-container',
  invoiceId: 'inv_xxx', // Required
  onPaymentSuccess: (payment) => {
    console.log('Payment successful:', payment);
  },
  onPaymentError: (error) => {
    console.error('Payment failed:', error);
  },
  onClose: () => {
    console.log('Flow closed');
  },
});

---

Configuration

PaymentFlowConfig

Property	Type	Required	Description
containerId	string	Yes	ID of the container element
invoiceId	string	Yes	Invoice ID to pay
theme	ThemeConfig	No	Custom theme configuration
onPaymentSuccess	(payment: Payment) => void	No	Called when payment succeeds
onPaymentError	(error: Error) => void	No	Called when payment fails
onClose	() => void	No	Called when flow is closed
onGoBack	() => void	No	Called when user clicks "Go back" on success screen

---

Common Use Cases

Basic Payment Flow

const flow = client.createPaymentFlow({
  containerId: 'payment-container',
  invoiceId: 'inv_xxx',
  onPaymentSuccess: (payment) => {
    window.location.href = '/payment-success';
  },
  onGoBack: () => {
    window.location.href = '/dashboard';
  },
});

Handle Payment Results

const flow = client.createPaymentFlow({
  containerId: 'payment-container',
  invoiceId: 'inv_xxx',
  onPaymentSuccess: (payment) => {
    // Payment completed successfully
    console.log('Payment ID:', payment.id);
    console.log('Amount:', payment.amount);
    console.log('Status:', payment.status);

    // Redirect to success page
    window.location.href = `/success?payment=${payment.id}`;
  },
  onPaymentError: (error) => {
    // Payment failed
    console.error('Error:', error.message);

    // Show error to user or retry
    showNotification('Payment failed. Please try again.');
  },
  onClose: () => {
    // User closed the flow without completing
    // Navigate back or show message
  },
  onGoBack: () => {
    // User clicked "Go back" on success screen
    window.location.href = '/dashboard';
  },
});

---

Component Instance Methods

The flow returns a ComponentInstance with these methods:

mount()

Mounts the component to the DOM. Called automatically on creation.

flow.mount();

unmount()

Removes the component from the DOM. Call this when navigating away or cleaning up.

flow.unmount();

refresh()

Refreshes the component data. Useful after external changes.

await flow.refresh();

---

Cleanup

Always unmount the flow when the user navigates away to prevent memory leaks:

// Vanilla JS
window.addEventListener('beforeunload', () => {
  flow.unmount();
});

// React
useEffect(() => {
  const flow = client.createPaymentFlow({ ... });
  return () => flow.unmount();
}, []);

// Vue
onUnmounted(() => {
  flow.unmount();
});

---

Already Paid Invoices

If an invoice is already paid (status: RECEIVED), the flow will skip directly to the success screen, showing the payment details without requiring any user action.

---

Related

ComponentsTheming