> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# Prebuilt Coinflow UI for Subscriptions

## Overview

Coinflow provides a prebuilt UI component that makes it easy to implement subscription purchases without building your own payment interface. The `CoinflowPurchase` component handles the entire subscription purchase flow, including payment method collection, subscription creation, and initial payment processing.

## When to Use This Method

#### Perfect For

**Choose this when you want the fastest subscription integration**

* React or Next.js applications
* Teams wanting to launch subscriptions quickly (hours to days)
* Businesses validating subscription business models
* Startups without dedicated payment UI resources
* Standard subscription flows without complex customization
* Platforms preferring Coinflow-maintained payment forms

**Integration time:** Hours, not days

#### Consider API Integration If

**These scenarios benefit from custom API implementation**

* **Non-React frameworks** (Vue, Angular, vanilla JS, mobile)
* **Custom branded checkout** matching your exact design
* **Complex subscription logic** (trials, prorations, upgrades)
* **Custom payment flows** beyond standard subscription purchase
* **Backend-only systems** without frontend components
* **Multi-step checkout** with additional business logic

→ See [API Integration](./api-integration) for full control

> **Info**
>
> **Start Simple, Customize Later**
>
> Most merchants begin with this prebuilt UI to validate their subscription offering (hours of integration), then migrate to API integration for custom experiences (1-2 weeks). Both methods support the same payment methods and features.

---

## Installation

Install the Coinflow React package:

```bash
npm i @coinflowlabs/react
```

## Basic Implementation

To use the prebuilt purchase component for subscriptions, you need to:

1. Import the `CoinflowPurchase` component
2. Provide your `merchantId` and the subscription `planCode`
3. Configure the component with appropriate callbacks

### Example Implementation

```javascript
import { CoinflowPurchase } from '@coinflowlabs/react';

function SubscriptionPurchase() {
  return (
    <CoinflowPurchase
      sessionKey={'YOUR_SESSION_KEY'}
      merchantId={'YOUR_MERCHANT_ID'}
      env={'sandbox'} // Use 'prod' for production
      onSuccess={(data) => {
        console.log('Subscription created successfully:', data);
        // Handle successful subscription creation
      }}
      planCode={'YOUR_PLAN_CODE'}
      chargebackProtectionData={[
        {
          productName: "Subscription plan",
          productType: "subscription",
          quantity: 1,
          rawProductData: {
            description: "Monthly subscription to premium features",
            features: ["Feature 1", "Feature 2", "Feature 3"]
          }
        }
      ]}
    />
  );
}
```

## Component Preview

## Key Features

### Automatic Plan Details Display

The component automatically fetches and displays:

* Plan name and description
* Subscription price
* Billing frequency (Monthly/Yearly)
* Duration (if applicable)

### Multiple Payment Methods

The prebuilt UI supports:

* **Credit/Debit Cards** - Visa, Mastercard, American Express, Discover
* **ACH Bank Transfers** - Direct bank account payments
* **Saved Payment Methods** - Returning customers can use previously saved cards or bank accounts

### Built-in Features

* **Secure Payment Processing** - PCI-compliant card handling
* **Responsive Design** - Works on desktop and mobile devices
* **Customizable Branding** - Match your brand colors and style
* **Error Handling** - Clear error messages for failed payments
* **Loading States** - Smooth loading indicators during processing

## Configuration Options

### Required Props

| Prop         | Type   | Description                                   |
| ------------ | ------ | --------------------------------------------- |
| `sessionKey` | string | Authentication token for the customer session |
| `merchantId` | string | Your Coinflow merchant identifier             |
| `planCode`   | string | The unique code for the subscription plan     |
| `env`        | string | Environment: 'sandbox' or 'prod'              |

### Optional Props

| Prop                       | Type     | Description                                        |
| -------------------------- | -------- | -------------------------------------------------- |
| `onSuccess`                | function | Callback when subscription is created successfully |
| `onError`                  | function | Callback when an error occurs                      |
| `chargebackProtectionData` | array    | Product information for chargeback protection      |
| `theme`                    | object   | Custom theme colors and styling                    |

## Subscription Flow

When a customer uses the prebuilt UI:

1. **Plan Display** - The component shows the subscription details
2. **Payment Method** - Customer enters credit card or connects bank account
3. **Initial Payment** - First payment is processed immediately
4. **Subscription Creation** - If payment succeeds, subscription is created
5. **Recurring Billing** - Future payments are automatically processed according to the plan schedule

## Session Key Generation

Before using the component, you must generate a session key for the customer on your backend:

```javascript
// Server-side code to generate session key
const response = await fetch('https://api-sandbox.coinflow.cash/api/session-key', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: 'customer-unique-id',
    merchantId: 'YOUR_MERCHANT_ID'
  })
});

const { sessionKey } = await response.json();
```

> **Important**: Session keys should be generated server-side to protect your API key. Never expose your API key in client-side code.

For more details, see the [session key API reference](/api-reference/api-reference/authentication/get-session-key).

## Chargeback Protection

Include product details to enable chargeback protection:

```javascript
chargebackProtectionData={[
  {
    productName: "Premium Subscription",
    productType: "subscription",
    quantity: 1,
    rawProductData: {
      description: "Monthly subscription to premium features",
      planType: "premium",
      features: [
        "Unlimited access",
        "Priority support",
        "Advanced analytics"
      ],
      tradable: false
    }
  }
]}
```

## Customization

### Theme Customization

Customize the component appearance to match your brand:

```javascript
<CoinflowPurchase
  // ... other props
  theme={{
    primary: '#2563eb',
    background: '#ffffff',
    backgroundAccent: '#f3f4f6',
    textColor: '#111827',
    textColorAccent: '#6b7280'
  }}
/>
```

### Custom Callbacks

Handle subscription events:

```javascript
<CoinflowPurchase
  // ... other props
  onSuccess={(data) => {
    // Subscription created successfully
    console.log('Subscription ID:', data.subscriptionId);
    // Redirect user to success page
    window.location.href = '/subscription/success';
  }}
  onError={(error) => {
    // Handle errors
    console.error('Subscription error:', error);
    // Show error message to user
  }}
/>
```

## Testing

To test subscriptions in sandbox mode:

1. Use the sandbox environment: `env={'sandbox'}`
2. Use test credit cards from our [testing guide](/guides/checkout/testing/testing-credit-cards)
3. For ACH testing, use Plaid's test credentials

## Next Steps

* [Learn how subscriptions work](/guides/subscriptions/overview/how-subscriptions-work)
* [Configure subscription webhooks](/guides/subscriptions/implementation-methods/api-integration#webhooks)
* [API Integration guide](./api-integration)