Stripe Client Library Reference

Complete reference for the iaptic Stripe client library (IapticStripe).

Installation

<script src="https://js.stripe.com/v3/"></script>
<script src="https://cdn.iaptic.com/v1/iaptic.min.js"></script>

Initialization

const iaptic = new IapticStripe({
  stripePublicKey: string;  // Stripe publishable key (pk_*)
  appName: string;          // Your app identifier
  apiKey: string;          // Iaptic public API key
  customIapticUrl?: string; // Optional custom API URL
});

Products and Prices

getProducts()

Fetches available products with prices.

interface ProductsResponse {
  ok: boolean;
  products: Array<{
    type: 'subscription' | 'consumable' | 'non_consumable';
    id: string;
    title: string;
    description?: string;
    offers: Array<{
      id: string;
      platform: 'stripe';
      offerType: 'Subscription' | 'Default';
      pricingPhases: Array<{
        priceMicros: number;
        currency: string;
        billingPeriod?: string;  // ISO 8601 duration
        recurrenceMode: 'INFINITE_RECURRING' | 'NON_RECURRING';
        paymentMode: 'PayAsYouGo' | 'PayUpFront';
      }>;
    }>;
    metadata?: Record<string, string>;
  }>;
}

const { products } = await iaptic.getProducts();

Checkout

createStripeCheckout()

Creates a checkout session for subscription or one-time purchase.

interface CheckoutResponse {
  ok: boolean;
  sessionId: string;     // Stripe session ID (cs_*)
  url: string;          // Checkout URL
  accessKey: string;    // Access key for verification
}

const response = await iaptic.createStripeCheckout({
  offerId: string;              // Format: "stripe:prod_xyz#price_xyz"
  applicationUsername: string;   // User identifier
  successUrl: string;           // Redirect after success
  cancelUrl: string;            // Redirect after cancel
});

Subscription Management

getPurchases()

Verifies subscription status and returns purchase details.

interface Purchase {
  purchaseId: string;        // Format: "stripe:sub_xyz"
  transactionId: string;     // Format: "stripe:pi_xyz"
  productId: string;         // Format: "stripe:prod_xyz"
  platform: 'stripe';
  purchaseDate: string;      // ISO 8601
  lastRenewalDate?: string;  // ISO 8601
  expirationDate: string;    // ISO 8601
  renewalIntent: 'Renew' | 'Cancel';
  isTrialPeriod: boolean;
  amountMicros: number;
  currency: string;
}

interface PurchasesResponse {
  ok: boolean;
  purchases: Purchase[];
  new_access_keys?: Record<string, string>;
}

const { purchases, new_access_keys } = await iaptic.getPurchases(
  subscriptionId?: string,  // Optional: specific subscription
  accessKey?: string       // Optional: stored access key
);

changePlan()

Changes subscription to a different plan.

interface ChangePlanResponse {
  ok: boolean;
  purchase: Purchase;
  new_access_keys?: Record<string, string>;
}

const response = await iaptic.changePlan({
  id: string;          // Subscription ID
  offerId: string;     // New offer ID
  accessKey?: string;  // Current access key
});

redirectToCustomerPortal()

Redirects to Stripe Customer Portal for subscription management.

await iaptic.redirectToCustomerPortal({
  id?: string;         // Subscription ID
  accessKey?: string;  // Access key
  returnUrl: string;   // Return URL after management
});

Utility Methods

formatCurrency()

Formats price amount with currency symbol.

const formatted = iaptic.formatCurrency(
  amountMicros: number,  // Price in micros (1/1,000,000)
  currency: string       // Currency code (e.g., 'USD')
);
// Returns: "$9.99"

formatBillingPeriodEN()

Formats ISO 8601 duration in plain English.

const period = iaptic.formatBillingPeriodEN(
  period: string  // ISO 8601 duration (e.g., "P1M")
);
// Returns: "Monthly"

Error Handling

interface ErrorResponse {
  status: number;   // HTTP status code
  code: number;     // Error code
  message: string;  // Error message
}

try {
  await iaptic.getPurchases();
} catch (error) {
  if (error.code === 'INVALID_ACCESS_KEY') {
    // Handle invalid/expired access key
  }
}

Storage Management

Access Keys

// Store access key
localStorage.setItem('stripe_access_key', response.accessKey);

// Get stored key
const key = localStorage.getItem('stripe_access_key');

// Clear stored keys
localStorage.removeItem('stripe_access_key');

Debug Methods

debugDump()

Returns internal state for debugging.

const debug = iaptic.debugDump();
// Returns: {
//   version: string;
//   config: Object;
//   storage: Object;
//   refreshScheduler: Object;
// }