@synko-lab/paymints-react

React Provider and hooks for the Paymints SDK. Wraps @synko-lab/paymints with idiomatic React patterns.

Installation

pnpm add @synko-lab/paymints @synko-lab/paymints-react

Peer dependency: @synko-lab/paymints must be installed alongside this package.

Quick Start

1. Wrap your app with the Provider

import { PaymintsProvider } from "@synko-lab/paymints-react";

function App() {
  return (
    <PaymintsProvider apiKey="pmts.your_public_key">
      <YourApp />
    </PaymintsProvider>
  );
}

You can optionally pass baseUrl and edgeUrl to override the default endpoints:

<PaymintsProvider
  apiKey="pmts.your_public_key"
  baseUrl="https://custom-api.example.com"
  edgeUrl="https://custom-edge.example.com"
>

2. Check subscription status

import { useSubscription } from "@synko-lab/paymints-react";

function SubscriptionBanner({ userId }: { userId: string }) {
  const { data, isLoading, error, refetch } = useSubscription(userId);

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

  if (data?.hasActiveSubscription) {
    return (
      <div>
        <p>Plan: {data.subscription?.planName}</p>
        <p>Status: {data.subscription?.status}</p>
      </div>
    );
  }

  return <p>No active subscription.</p>;
}

3. Launch checkout

import { useCheckout } from "@synko-lab/paymints-react";

function UpgradeButton({ userId }: { userId: string }) {
  const { checkout, isLoading, error } = useCheckout();

  const handleClick = async () => {
    await checkout({
      customerReference: userId,
      customerEmail: "[email protected]",
      priceId: "price_xxxxx", // optional
      successUrl: "https://myapp.com/success",
      cancelUrl: "https://myapp.com/cancel",
    });
  };

  return (
    <button onClick={handleClick} disabled={isLoading}>
      {isLoading ? "Redirecting..." : "Upgrade"}
    </button>
  );
}

4. Access the client directly

import { usePaymints } from "@synko-lab/paymints-react";

function CustomComponent() {
  const client = usePaymints();
  // client.http and client.edgeHttp available for custom requests
}

API Reference

<PaymintsProvider>

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | Yes | Your public API key (starts with pmts.) | | baseUrl | string | No | Override core API URL | | edgeUrl | string | No | Override edge gateway URL | | children | ReactNode | Yes | Child components |

useSubscription(customerReference)

Fetches subscription status on mount and when customerReference changes.

Parameters:

• customerReference (string | undefined) — Customer identifier. Skips fetch if undefined.

Returns: | Field | Type | Description | |-------|------|-------------| | data | SubscriptionCheckResponse \| null | Subscription data | | isLoading | boolean | Loading state | | error | Error \| null | Error if request failed | | refetch | () => void | Manually re-fetch |

useCheckout()

Returns a function to launch a checkout session.

Returns: | Field | Type | Description | |-------|------|-------------| | checkout | (params: CreateCheckoutParams) => Promise<void> | Launches checkout and redirects | | isLoading | boolean | Loading state | | error | Error \| null | Error if request failed |

usePaymints()

Returns the underlying PaymintsClient instance for custom usage.

License

MIT