Subscription payments

SixPay subscriptions authorize recurring same-chain ERC-20 collections. The customer creates the subscription from the hosted subscription checkout. Future collections are submitted by the SixPay Keeper only while the on-chain authorization remains valid.

Merchant setup

Create and publish a subscription product in the Merchant Console, then configure an active webhook URL and tenant signing key in Developers > Webhooks. The same endpoint receives both one-time order and subscription events. Server-side integrations can manage product drafts and read confirmed subscriptions with a Merchant API Key. The customer selects a supported token and funding source:

Funding source	Customer action	Later collections
Wallet authorization	Approves the token for Permit2 and signs a Permit2 allowance for the subscription contract.	The contract pulls up to the authorized amount.
Cheque reserve	Tops up a SixPay cheque reserve.	The contract deducts the reserve.

The customer can authorize a bounded number of billing periods. A subscription must have enough remaining authorization to cover the next period before the Keeper can collect it.

Confirmation flow

customer transaction or Keeper transaction
  -> confirmed chain event
  -> SixPay subscription indexer
  -> durable webhook outbox
  -> signed POST to the merchant webhook URL

Webhook delivery happens after the configured chain confirmation depth, not when a wallet or Keeper merely submits a transaction. The indexer normally polls every 15 seconds, so delivery is intentionally asynchronous.

Handle creation and payment separately

subscription.created means the customer has created an on-chain subscription. It is the event to use for creating a merchant-side subscription record. subscription.payment_succeeded means a SubscriptionPaymentExecuted event was confirmed. Use it to grant or extend paid access for a billing period, regardless of whether the executor was the customer transaction or the Keeper. Do not infer a completed collection only from subscription.created. Store and process each webhook id once. See Subscription webhook events for the payload and Webhooks for signature verification.

Use the subscription ID

Each published subscription plan has a stable subscriptionProductId. It identifies the merchant’s subscription product used to create hosted or SDK checkout sessions. It is distinct from an individual customer’s on-chain subscriptionId and from the on-chain plan ID. In the Merchant Console, open the subscription plan’s detail page under Subscriptions > Plans and use the copy control beside Subscription ID. Use this value as subscriptionProductId when creating a subscription checkout session, or as productId when loading the published product. Use the exact copied value wherever the SDK asks for subscriptionProductId or productId:

import { SigWorldSDK } from '@sigworld/sdk';

const sdk = new SigWorldSDK({
  platformEndpointURL: 'https://api.sixpay.xyz',
});

const session = await sdk.subscription.createCheckoutSession({
  tenantId,
  subscriptionProductId,
  merchantSubscriptionOrderId: order.id,
});

const product = await sdk.subscription.getPublicProduct(subscriptionProductId);

Do not pass an individual on-chain subscriptionId, on-chain plan ID, transaction hash, or shortened display value in place of subscriptionProductId. Treat the copied product ID as an opaque string.

Operations

The Keeper is an independent service. For recurring collections to run, the subscription indexer must be enabled for the chain, the Keeper must be enabled and funded for the chain, and the Diamond deployment must be configured. The merchant receives no renewal webhook if a Keeper transaction fails before it emits a confirmed chain event. Subscription records are created by confirmed SubscriptionCreated events. Do not create a local record from a browser success state or fabricate one through an API call; query SixPay’s confirmed record instead. Terminal events such as subscription.failed, subscription.cancelled, and subscription.expired should revoke or pause access according to the merchant’s policy. They are final state signals; do not retry a collection by replaying a webhook.

Overview

Get started

Build checkout

Operate

Reference

Subscription payments

Merchant setup

Confirmation flow

Handle creation and payment separately

Use the subscription ID

Operations

​Merchant setup

​Confirmation flow

​Handle creation and payment separately

​Use the subscription ID

​Operations

Merchant setup

Confirmation flow

Handle creation and payment separately

Use the subscription ID

Operations