SixpaySubscriptionModal renders the hosted subscription experience: billing-period and network selection, token and funding-source selection, wallet connection, Permit2 authorization, and the create-subscription transaction. Use it when a merchant wants SixPay to own the recurring-payment UI while the merchant owns the page entry point and fulfillment logic. The component is a React export. The browser script-tag checkout bundles support one-time checkout only.

Before you integrate

  1. Create and publish a subscription plan in Subscriptions > Plans in the Merchant Console.
  2. Copy the plan’s Subscription ID. This is the subscriptionProductId.
  3. Configure a signed webhook endpoint for the tenant.
  4. Install the UI package and its React peer dependencies.
subscriptionProductId is the merchant product ID, not a customer’s on-chain subscriptionId, an on-chain plan ID, or a transaction hash. See Subscription payments.

Start from a published product

For the normal hosted flow, pass only subscriptionProductId. The modal loads the published product and creates the on-chain subscription after the customer chooses the terms and a wallet.
Keep the merchant button focused on opening the modal. SDK UI performs wallet connection only after it opens; do not add wallet readiness or connection state to the merchant button.

Use a server-created subscription session

Create a subscription checkout session when the merchant needs to associate its own pending subscription order or customer reference with the checkout. The Merchant API Key stays on the server. Return only id, checkoutToken, and expiresAt to the browser, and keep the token in page memory rather than a URL, local storage, analytics, or logs.
Subscription sessions expire after 15 minutes by default and cannot be created for more than 24 hours ahead. Create a fresh session for an expired checkout. A session must reference a published product belonging to the authenticated tenant.

React with Privy

Wrap the merchant application in its own PrivyProvider, then provide usePrivyWallet() as the modal’s walletAdapter. SDK UI’s wallet selection then uses the merchant’s Privy configuration. Embedded Privy wallets require HTTPS.
Without a walletAdapter, the modal can use an injected EIP-1193 browser wallet when available.

Confirmation and fulfillment

onComplete reports a submitted browser transaction. It is not proof that the subscription was indexed or that a recurring collection succeeded. Verify signed webhooks, deduplicate by webhook id, and make fulfillment decisions from confirmed subscription events:
  • subscription.created: create or activate the merchant-side subscription record.
  • subscription.payment_succeeded: grant or extend access for the paid billing period.
  • subscription.failed, subscription.cancelled, and subscription.expired: pause or revoke access according to merchant policy.
See Subscription webhook events and Webhooks for verification and payload handling.

Custom transaction handling

By default, the component calls sdk.subscription.createFromProduct. Supply onCreate only when the merchant deliberately owns transaction submission. Its request includes the selected product, strategy, token, funding source, wallet address, EIP-1193 provider, and selected authorization cycle count. A custom handler must preserve the product’s published chain and token constraints; do not trust browser-provided plan or amount data for a separate backend flow. platformEndpointURL and theme are optional private/staging overrides. Production integrations should use the default SixPay endpoint.