API Integration for Subscriptions

This guide shows you how to implement subscriptions using either the prebuilt UI component or direct API integration.

When to Use API Integration

Perfect For

Choose API integration when you need full customization

Custom branded checkout experience
Non-React frameworks (Vue, Angular, vanilla JS, mobile)
Complex subscription logic (trials, upgrades, prorations)
Multi-step checkout with additional business logic
Backend-only subscription management
Custom payment method collection flows
Teams with frontend development capacity

Integration time: 1-2 weeks for custom UI

Consider Prebuilt UI If

These scenarios work better with the prebuilt component

React/Next.js apps with standard subscription flows
Quick validation of subscription business model (hours vs weeks)
Limited resources for building custom payment UI
Standard checkout without complex customization needs
Faster time to market is critical priority

→ See Prebuilt Coinflow UI for fastest integration

Trade-offs: Speed vs Control

The prebuilt UI gets you live in hours with minimal code, while API integration takes 1-2 weeks but gives you complete control over the user experience. Both support the same payment methods, currencies, and business logic.

UI Implementation

Installation

Install the latest Coinflow packages:

npm i @coinflowlabs/react

Configuration

To use the provided purchase page for subscriptions:

Supply the merchantId and planCode in the CoinflowPurchase component
The subscription cost and information will automatically populate the form

Example Implementation

// Example of how to configure CoinflowPurchase for subscriptions
<CoinflowPurchase
  sessionKey={'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw'}
  merchantId={'YOUR_MERCHANT_ID'}
  env={'sandbox'} // Change to 'prod' for production
  onSuccess={(...args) => {
    console.log('Purchase Success', args);
    // Create your own on success function after payment success
  }}
  chargebackProtectionData={[
    {
      productName: "Subscription plan",
      productType: "subscription",
      quantity: 1,
      rawProductData: {
        description: "subscription to gold tier products",
        productsInGoldTier: ["celebrity access passes", "cool merchandise"],
        tradible: false
      }
    }
  ]}
  planCode={'12345'}
/>

Component Display

How the `CoinflowPurchase` component looks configured for an existing subscription plan.

How the Subscription Purchase Works

When a customer subscribes:

Payment Method: Customer provides a payment method (card or bank account)
Initial Payment: The first payment is processed immediately
Subscription Creation: If payment succeeds, the subscription is created with Active status
Recurring Billing: Future payments are automatically processed according to the plan schedule

Note: If the first payment fails, the subscription is not created. The customer must retry the entire subscription purchase.

API Implementation

Follow these steps to implement subscriptions via direct API integration.

Step 1: Create a Subscription Plan

Create a subscription plan using the merchant API. This is a one-time setup for each plan you want to offer.

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/merchant/subscription/plans \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "interval": "Monthly",
  "amount": {
    "currency": "USD",
    "cents": 1000
  },
  "name": "Gold Tier Plan",
  "code": "12345",
  "duration": 4,
  "description": "A monthly subscription to gain access to our gold tier product suite",
  "settlementType": "USD"
}
'

Note: Use USDC or EUROe for settlementType if you want stablecoin settlement; see Settlement Types.

Response:

{
  "merchant": "6840bca9c7cb21ee5baaae76",
  "name": "Gold Tier Plan",
  "code": "12345",
  "interval": "Monthly",
  "duration": 4,
  "amount": {
    "cents": 1000,
    "currency": "USD"
  },
  "description": "A monthly subscription to gain access to our gold tier product suite",
  "settlementType": "USD",
  "active": true,
  "_id": "6851d74578269da7d5a533c4",
  "__v": 0,
  "id": "6851d74578269da7d5a533c4"
}

Step 2: Get Available Subscription Plans

Get all available subscription plans that customers can purchase. Use this endpoint in your application to display plan options.

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/subscription/mello/plans \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw'

Response:

[
  {
    "id": "6851d74578269da7d5a533c4",
    "name": "Gold Tier Plan",
    "code": "12345",
    "interval": "Monthly",
    "duration": 4,
    "amount": {
      "cents": 1000,
      "currency": "USD"
    },
    "description": "A monthly subscription to gain access to our gold tier product suite",
    "settlementType": "USD",
    "active": true
  }
]

Step 3: Create Subscription with Credit Card

Enable customers to subscribe to a plan with a credit card. This processes the first payment and creates the subscription.

Important: You must tokenize the card before making this request. See the card tokenization guide for details.

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/subscription/mello/subscribers/card \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw' \
     --data '
{
  "card": {
    "cardToken": "411111YJM5TX1111",
    "expYear": "30",
    "expMonth": "10",
    "email": "test@gmail.com",
    "firstName": "Dwayne",
    "lastName": "Johnson",
    "address1": "201 E Randolph Street",
    "city": "Chicago",
    "zip": "60625",
    "state": "IL",
    "country": "US"
  },
  "chargebackProtectionData": [
    {
      "productName": "Subscription plan",
      "productType": "subscription",
      "quantity": 1,
      "rawProductData": {
        "example": "{\"description\": \"subscription to gold tier products\", \"productsInGoldTier\": [\"celebrity access passes\", \"cool merchandise\"], \"tradible\": false}"
      }
    }
  ],
  "planCode": "12345"
}
'

Response:

c10d7ac6-cca8-436b-b99f-2c7418f1cbe1

Step 4: Enable Customer to Cancel Subscription

Allow customers to cancel their subscription when needed.

Get Customer Subscriptions

First, retrieve all subscriptions for the customer:

# Gets all the subscriptions the customer is currently subscribed to
# API Reference: /api-reference/api-reference/customers/get-customersubscriptions
curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/subscription/mello/subscribers \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw'

Response:

[
  {
    "id": "6851d8c378269da7d5a535d6", // This is the subscriptionId
    "customerId": "dwaynejohnson75",
    "blockchain": "user", // Internal routing field; can be ignored for bank/card subscriptions
    "merchantId": "mello",
    "email": "test@gmail.com",
    "plan": "Gold Tier Plan",
    "planCode": "12345",
    "status": "Canceled"
  }
]

Cancel the Subscription

Use the subscription ID from the previous response to cancel:

# Allows customer to cancel their subscription
# See also: Cancel Subscription (by merchant) as an alternative for server-to-server cancellation
# API Reference: /api/cancelsubscription
curl --request PATCH \
     --url https://api-sandbox.coinflow.cash/api/subscription/mello/subscribers/6851d8c378269da7d5a535d6 \
     --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiZHdheW5lam9obnNvbjc1IiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWF0IjoxNzUwMTk0MDM5LCJleHAiOjE3NTAyODA0Mzl9.4WQPzfu6niH2S7oE7KATJY9r1D_PB_ssPajaRz4Pvsw'

Testing

To test credit card purchases for a subscription, please see our testing credit card purchase documentation. For bank-account testing, see the ACH testing guide.