Subscription Payments

Accept your first subscription payment in 6 steps.

Overview

This guide walks you through:

1. Creating an API key

2. Configuring a webhook endpoint

3. Creating a subscription plan

4. Generating a client session

5. Initializing the payment iframe

6. Verifying the subscription

Prerequisites

• A Flintn account at hub.sandbox.flintn.com

• A server capable of receiving webhook notifications

Step 1: Create an API Key

Create an API key with the permissions needed for subscription payments.

1. Go to hub.sandbox.flintn.com

2. Navigate to Developers > API Keys

3. Click Create API Key

4. Enter a name (e.g., "Subscription Integration")

5. Select these permissions:

   • subscription.client_session.create

   • subscription.read

   • subscription_plan.read

   • subscription_plan.write

6. Click Create

7. Copy and securely store your API key - it won't be shown again

Your key will look like: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

For more details, see Authentication.

Step 2: Configure Webhook Endpoint

Set up a webhook to receive subscription events.

Create Your Endpoint

Your server needs an HTTPS endpoint to receive webhook notifications:

// Express.js example
const express = require('express');
const crypto = require('crypto');

const app = express();

app.post('/webhooks/flintn', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature-primary'];
  const payload = req.body.toString();

  // Verify signature (see Webhooks documentation)
  // Process event...

  res.status(200).send('OK');
});

Register the Webhook

1. Go to hub.sandbox.flintn.com

2. Navigate to Developers > Webhooks

3. Click Add Webhook

4. Enter your HTTPS endpoint URL

5. Select these events:

   • SUBSCRIPTION_ACTIVATED

   • SUBSCRIPTION_RENEWED

   • SUBSCRIPTION_CANCELLED

   • SUBSCRIPTION_EXPIRED

   • TRANSACTION_SETTLED

6. Click Create

7. Copy your webhook secret for signature verification

For more details, see Configure Webhooks.

Step 3: Create a Subscription Plan

Create a plan that defines your subscription's pricing and billing terms.

curl -X POST https://api.sandbox.flintn.com/v1/subscription-plans \
  -H "X-Api-Key: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUBSCRIPTION_NO_TRIAL",
    "name": "Monthly Pro",
    "description": "Full access to Pro features",
    "website_url": "https://yoursite.com/pro",
    "currency": "USD",
    "full_price_amount": 29.99,
    "settlement_interval_hours": 119,
    "billing_frequency_value": 1,
    "billing_frequency_unit": "MONTHS",
    "retry_strategy_id": 5,
    "status": "ACTIVE"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "SUBSCRIPTION_NO_TRIAL",
  "name": "Monthly Pro",
  "description": "Full access to Pro features",
  "website_url": "https://yoursite.com/pro",
  "currency": "USD",
  "full_price_amount": 29.99,
  "settlement_interval_hours": 119,
  "billing_frequency_value": 1,
  "billing_frequency_unit": "MONTHS",
  "retry_strategy_id": 5,
  "status": "ACTIVE",
  "created_at": "2024-01-15T10:00:00Z"
}

Save the id for the next step.

For more options, see Create Plans via API.

Step 4: Create a Client Session

Generate a secure client session token to initialize the payment iframe.

curl -X POST https://api.sandbox.flintn.com/v1/subscriptions/client-sessions \
  -H "X-Api-Key: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_plan_id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_id": "cust_your_customer_id",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[e-mail]"
    }
  }'

Response:

{
  "client_session_token": "ct_xyz789ghi012...",
  "client_session_id": "660f9511-f30c-52e5-b827-557766551111",
  "subscription_plan_id": "550e8400-e29b-41d4-a716-446655440000",
  "subscription_plan_name": "Monthly Pro",
  "amount": 29.99,
  "currency": "USD",
  "customer_id": "cust_your_customer_id",
  "created_at": "2024-01-15T10:30:00Z"
}

The client_session_token is used to initialize the payment iframe. Tokens expire after 24 hours.

Step 5: Initialize the Payment Iframe

Embed the Flintn payment iframe in your checkout page and communicate with it via postMessage.

Add the Iframe

const ORIGIN = 'https://pay.flintn.com';

const container = document.getElementById('payment-container');

const iframe = document.createElement('iframe');
iframe.src = ORIGIN + '/iframe/';
iframe.title = 'Checkout form';
iframe.style.cssText = 'width: 100%; height: 100%; border: none;';
iframe.sandbox = 'allow-scripts allow-forms allow-popups allow-same-origin';
iframe.allow = 'payment *; clipboard-write';
container.appendChild(iframe);

const config = {
  clientSessionId: 'your_client_session_id',
};

function sendConfig() {
  if (!iframe.contentWindow) return;
  iframe.contentWindow.postMessage(
    { type: 'WIDGET_CONFIG', payload: config },
    ORIGIN,
  );
}

iframe.addEventListener('load', sendConfig);

window.addEventListener('message', (event) => {
  if (event.origin !== ORIGIN) return;

  const { type, payload } = event.data || {};

  switch (type) {
    case 'WIDGET_READY':
      sendConfig();
      break;

    case 'PAYMENT':
      console.log('Payment result:', payload);
      break;

    case 'EXPRESS_PAYMENT':
      console.log('Express payment result:', payload);
      break;

    case 'REDIRECT':
      if (payload?.url) {
        window.location.href = payload.url;
      }
      break;
  }
});

Configuration Options

Option	Type	Required	Default	Description
clientSessionId	string	✅	—	Client session ID from your backend
isCardHolderRequired	boolean	❌	true	Require cardholder name field
successRedirectUrl	string	❌	—	Redirect URL after successful payment

Note: isCardHolderRequired only applies when using Primer as the payment provider.

For more details, see Checkout Reference.

Step 6: Verify the Subscription

After the customer completes payment, verify the subscription was created.

Via Webhook

Your webhook endpoint will receive a SUBSCRIPTION_ACTIVATED event:

{
  "id": "evt_abc123",
  "type": "SUBSCRIPTION_ACTIVATED",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "subscription_id": "660f9511-f30c-52e5-b827-557766551111",
    "subscription_plan_id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_id": "cust_your_customer_id",
    "status": "ACTIVE"
  }
}

Via API

Query the subscription directly:

curl -X GET https://api.sandbox.flintn.com/v1/subscriptions/660f9511-f30c-52e5-b827-557766551111 \
  -H "X-Api-Key: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response:

{
  "id": "660f9511-f30c-52e5-b827-557766551111",
  "subscription_plan_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "cust_your_customer_id",
  "email": "[e-mail]",
  "status": "ACTIVE",
  "term_number": 1,
  "start_date": "2024-01-15T10:30:00Z",
  "next_charge_at": "2024-02-15T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

View Transactions

Verify the payment transaction:

curl -X GET https://api.sandbox.flintn.com/v1/transactions \
  -H "X-Api-Key: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Test Cards

Use these test card numbers in the sandbox environment:

Card Number	Result
4111 1111 1111 1111	Successful payment
4000 0000 0000 0002	Declined
4000 0000 0000 9995	Insufficient funds

Use any future expiry date and any 3-digit CVV.

See Testing for more test scenarios.

Next Steps

You've successfully set up subscription payments. Continue with:

• Managing Subscriptions - Cancel, pause, and monitor subscriptions

• Handling Failed Payments - Configure retry logic and dunning

• Webhook Events - Detailed event payloads

Production Checklist

Before going live:

• Replace sandbox API keys with production keys (pk_live_*)

• Update API endpoints to production (api.flintn.com)

• Configure production webhook endpoints

• Test end-to-end with a real card (small amount)

• Implement proper error handling

• Set up monitoring for webhook failures