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 for full control

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:

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

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

Optional Props

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:

// 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.

Chargeback Protection

Include product details to enable chargeback protection:

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:

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

Custom Callbacks

Handle subscription events:

<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
3. For ACH testing, use Plaid’s test credentials

Next Steps

• Learn how subscriptions work
• Configure subscription webhooks
• API Integration guide