The Payments SDK for React enables you to subscribe users using React-specific features.

​
Getting Started

​
1. Install the SDK

Install the SDK with your preferred package manager.

npm install @microapp-io/react

​
2. Wrap Your App with the Provider

In order for your microapp to have access to payments features, it needs to be wrapped in the SubscriptionProvider component:

import { SubscriptionProvider } from "@microapp-io/react";

function App() {
  return <SubscriptionProvider>{/* Your microapp code here */}</SubscriptionProvider>;
}

For local development, we recommend using the sandbox feature on the SubscriptionProvider component to return mocked subscriptions:

import { SubscriptionProvider, SubscriptionPlanCycle } from "@microapp-io/react";

const sandbox = {
  enabled: process.env.NODE_ENV !== "production",
  subscription: () => ({
    id: 'some-subscription-id',
    appId: 'some-app-id',
    user: {
      id: 'some-user-id',
      email: '[email protected]',
      name: 'FirstName LastName',
    },
    active: true,
    subscriptionPlan: {
      id: 'some-subscription-plan-id',
      name: 'free',
      priceInCents: 0,
      cycle: SubscriptionPlanCycle.ONE_TIME,
      features: [
        {
          name: 'some-feature-name',
          description: 'some-feature-description'
        },
      ],
      createdAt: new Date(),
      updatedAt: new Date(),
    },
    createdAt: new Date(),
    updatedAt: new Date(),
  }),
};

function App() {
  return (
    <SubscriptionProvider sandbox={sandbox}>
      {/* Your microapp code here */}
    </SubscriptionProvider>
  );
}

The sandbox prop should only be used for local development. Do not use it in production.

​
3. Use the useSubscription Hook

The useSubscription hook returns all of the payments data and methods available to your microapp. It returns the following type:

type Payments = {
  hasSubscribed: boolean;
  isLoading: boolean;
  subscription?: {
    id: string;
    appId: string;
    user: {
      id: string;
      name: string;
    };
    active: boolean;
    subscriptionPlan: {
      id: string;
      name: string;
      description?: string;
      priceInCents: number;
      cycle: SubscriptionPlanCycle;
      features: Array<{
        id: string;
        name: string;
        description?: string;
      }>;
      createdAt: Date;
      updatedAt: Date;
      archivedAt?: Date;
    };
    paymentsProvider?: string;
    paymentsSubscriptionManagementUrl?: string;
    paymentsSubscriptionId?: string;
    paymentsPaymentId?: string;
    createdAt: Date;
    updatedAt: Date;
    cancelledAt?: Date;
    endsAt?: Date;
  };
  error?: Error;
  requireSubscription: () => void;
};

​
4. Prompt the User to Subscribe

You can prompt the user to subscribe by calling the requireSubscription method.

import { useSubscription } from '@microapp-io/react';

function Home() {
  const { requireSubscription } = useSubscription();

  return (
    <button onClick={() => requireSubscription()}>Subscribe</button>
  );
}

​
5. Get Notified when the User subscribes

You can get notified when the user subscribes or changes the subscription passing a callback on Payments initialization

  import { useSubscription } from '@microapp-io/react';

  function Home() {
    const { requireSubscription } = useSubscription({
      onChange: (userSubscription) => console.log('User subscribed', userSubscription),
    });

    requireSubscription();
  }

​
6. Example Usage

Here is an example of how you can use the useSubscription hook in your microapp:

import { useSubscription } from "@microapp-io/react";

function Home() {
  const {
    hasSubscribed,
    isLoading,
    subscription,
    error,
    requireSubscription,
  } = useSubscription({
    onChange: (userSubscription) => console.log('User subscribed', userSubscription),
  });

  if (isLoading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }

  if (!hasSubscribed) {
    return <button onClick={() => requireSubscription()}>Subscribe</button>;
  }
}