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
- Create and publish a subscription plan in Subscriptions > Plans in the Merchant Console.
- Copy the plan’s Subscription ID. This is the
subscriptionProductId. - Configure a signed webhook endpoint for the tenant.
- 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 onlysubscriptionProductId. The modal loads the published product and creates the on-chain subscription after the customer chooses the terms and a wallet.
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 onlyid, checkoutToken, and expiresAt to the browser, and keep the token in page memory rather than a URL, local storage, analytics, or logs.
React with Privy
Wrap the merchant application in its ownPrivyProvider, 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.
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, andsubscription.expired: pause or revoke access according to merchant policy.
Custom transaction handling
By default, the component callssdk.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.