Introduction

This guide provides a comprehensive walkthrough for integrating Stripe payments into your web application using Iaptic. We will use modern JavaScript/TypeScript practices, refer to the official Iaptic documentation and the IapticJS library, and build upon global best practices for NodeJS and Express distributed systems.

By following this tutorial, you will:

Integrate Stripe subscription and one-time purchases.
Implement a secure validation flow via Iaptic's server-side verification and webhooks.
Explore how to leverage the IapticJS library to simplify your payment logic, manage subscriptions, and handle upgrades/downgrades.

For more information on overall Iaptic setup, see Getting Started with Iaptic. Additionally, check out the IapticJS reference documentation and the demo implementation for live examples of usage.

Prerequisites

A Stripe account (Sign up here)
An Iaptic account (Sign up here)
A web application setup (NodeJS / Express recommended)
Awareness of modern JavaScript or TypeScript
A basic understanding of asynchronous programming with async/await

You will also need your:

Stripe Secret Key (sk_...)
Iaptic Webhook Secret (whsec_...)
App Name from Iaptic Settings (e.g., com.example.app)
Public Key, also from Iaptic settings.

Implementation Flow

Below is the typical sequence of events when you integrate with Iaptic + Stripe:

sequenceDiagram
    participant Client
    participant IapticJS
    participant Iaptic
    participant Server (Your backend)
    participant Stripe

    rect rgb(255, 255, 255)
      Note over Client: App Launch
      Client->>Server (Your backend): Optionally retrieve saved user details
      Client->>IapticJS: Initialize() with Stripe keys
      IapticJS->>Iaptic: Verify existing subscriptions
      Iaptic-->>IapticJS: Subscription & purchase info
      IapticJS-->>Client: Active and pending purchases
      Client->>Server (Your backend): Store / update user subscription data
    end

    rect rgb(255, 255, 255)
      Note over Client: New Purchase
      Client->>IapticJS: createCheckoutSession()
      IapticJS->>Iaptic: Request checkout session
      Iaptic->>Stripe: Create Stripe Checkout session
      Stripe-->>Iaptic: Checkout URL
      Iaptic-->>IapticJS: Return checkout URL
      IapticJS-->>Client: Redirect to Stripe
      Stripe->>Client: Payment flow
      Stripe->>Iaptic: Payment result
      Iaptic->>Server (Your backend): Webhook events
      Server (Your backend)->>Client: Update subscription state
      Note over Client: Return to success URL
    end

Step-by-Step Guide

1. Configure Stripe

Log in to your Stripe Dashboard.
Under "Developers → API keys," retrieve your Publishable Key (pk_...) and Secret Key (sk_...).
Go to "Developers → Webhooks" and create a new Webhook endpoint:
- Enter the URL: https://validator.iaptic.com/v3/webhook/stripe
- Subscribe to relevant events (e.g., customer.subscription.created, payment_intent.succeeded, etc.).
- Copy the webhook signing secret (whsec_...).
Store these keys and secrets securely in your environment variables or configuration.

2. Configure Iaptic

In your Iaptic Dashboard → Settings:
Provide your Stripe Secret Key (sk_...) and the Stripe Webhook Secret (whsec_...).
Set your Application Name (e.g., com.example.app).
Save your changes.

Tip: If you have multiple environments (e.g., dev / prod), you can store different Stripe credentials per environment.

3. Project Setup

In your NodeJS web project (Express or another framework):

• Install any required dependencies:

npm install express body-parser cors
npm install --save iaptic-js

• Ensure you have a route or controller ready to handle post-checkout logic.
• (Optional) Set up server-side logic to persist user purchases to a database.

4. Using IapticJS in Your Frontend

The IapticJS library simplifies integrating Iaptic and Stripe in your client code:

Include the libraries in your HTML:

<script src="https://js.stripe.com/v3/"></script>
<script src="https://cdn.jsdelivr.net/npm/iaptic-js@latest/dist/iaptic-js.js"></script>

Initialize an IapticStripe instance:

const iaptic = IapticJS.createAdapter({
  type: 'stripe',
  appName: 'com.example.app',
  apiKey: 'your_iaptic_public_api_key',
  stripePublicKey: 'pk_test_...',
});

Fetch products and display them:

async function displayProducts() {
  const products = await iaptic.getProducts();
  // Render product cards, subscription plans, or purchase buttons
}

Create checkout sessions:

async function startCheckout(offerId) {
  try {
    await iaptic.initCheckoutSession({
      offerId,
      applicationUsername: 'user123',
      successUrl: 'https://example.com/#success',
      cancelUrl: 'https://example.com/#cancel'
    });
  } catch (error) {
    console.error('Checkout failed:', error);
  }
}

On success, verify the purchase:

async function checkSubscription() {
  try {
    const { purchases } = await iaptic.getPurchases();
    console.log('Purchases found:', purchases);
    // Unlock premium features, or store new subscription data in your backend
  } catch (error) {
    console.error('Error retrieving purchases:', error);
  }
}

Check out the demo page to see a full working example of these steps in code.

Step 5: Handling Webhooks

Server Webhook Endpoint

While Iaptic already listens to Stripe webhooks on your behalf, you may also want to capture these events on your server:

Create an endpoint in your NodeJS app, e.g. POST /webhooks/iaptic-stripe.
Parse the request body and verify the request signature if desired.
Respond with a 2xx status code to indicate successful processing.

The Iaptic Webhook Documentation shows how these events are structured and how to secure your endpoint.

Why Use a Server Webhook?

• Maintain your own copy of user subscription data.
• Trigger internal business logic upon subscription renewal, cancellation, etc.
• Provide real-time subscription updates to your app's UI.

Step 6: Testing Your Integration

• Use Stripe test cards to simulate payments (e.g., 4242 4242 4242 4242).
• Check console logs in your app to see if the purchase was successfully registered.
• Verify your subscription or purchase status with the Iaptic dashboard.
• Ensure your server receives the expected webhooks (if configured).

How-To, Guides & Explanation

Below are some additional resources within this documentation set:

For an overall architectural perspective, see:

Next Steps

Now you have a functional Iaptic + Stripe integration:

Refine your subscription/tier logic.
Add server-side subscription validations if needed.
Enrich your UI/UX for self-serve plan changes.
Explore advanced features like discount codes, usage-based billing, or custom subscription flows.

Finally, monitor usage and conversion in the Iaptic dashboard to gain insights into your subscription performance and user behavior.

Happy coding with Iaptic and Stripe!

First Steps with Stripe