Subscriptions (Supayment)

Use Supayment when you need recurring on-chain payments on Sui without taking custody.

Supayment is the subscription product inside Sup Wallet. It gives merchants a Stripe-like flow for plans, checkout links, webhook config, and revenue reads, while keeping the subscriber self-custodial. The merchant creates an on-chain Service<CoinType>. The subscriber signs a transaction from their own wallet/vault. Helpers build unsigned Transaction objects; they do not hold keys and they do not sign.

This page is for both sides:

For the wallet policy model behind this, read Delegation. For app setup, read Quickstart, API, and Protocol.

#Model

Supayment is built on three layers:

The core ethos is simple: Supayment grants payment authority to a contract path, not signing authority to a helper. SDK functions return unsigned transactions. The owner or current signer still signs every transaction.

#Merchant flow

Create a plan from /supayment.

The dashboard creates:

const tx = subscriptionClient.createService({
  coinType: coin.coinType,
  price: toAtomic(price),
  serviceName: name.trim(),
  serviceOwner: payoutAddr,
  yearlyPricePct: Math.floor(yp),
});

After signing, the app reads the ServiceCreated event and stores the returned service_id in a local Plan cache.

ApiKey and Webhook records are local merchant config in localStorage. Plans are on-chain Service<CoinType> objects; the dashboard only caches their ids.

#Revenue and subscribers

Revenue is read from chain state.

fetchPayments queries events by type:

Payment shape:

export type Payment = {
  kind: "new" | "renewal";
  serviceId: string;
  paymentRegistry: string;
  paymentNonce: string;
  subscriber: string;
  amountAtomic: string;
  timestampMs: number;
  digest: string;
};

fetchSubscribers lists ChargeCap objects owned by the payout address.

export type Subscriber = {
  chargeCapId: string;
  serviceId: string;
  subscriber: string;
  isYear: boolean;
  chargeDateMs: number;
};

#Checkout flow

A checkout link uses query params read by /supayment/subscribe.

The checkout page reads the service object via grpcClient.getObject({ objectId: serviceId, include: { json: true } }) and expects JSON fields:

The subscriber signs:

const tx = getSubClient(network).authorizeAndSubscribe({
  walletId,
  serviceId,
  coinType: coin.coinType,
  paymentNonce: nonceParam && nonceParam.length <= 36 ? nonceParam : createPaymentNonce("sub"),
  isYear: year,
});

authorizeAndSubscribe performs two calls in one unsigned Transaction:

The owner signs. The helper does not sign.

#Embed a button

The React export is under @workspace/sup-subscription-sdk/react.

import { SubscriptionConfirm } from "@workspace/sup-subscription-sdk/react";

<SubscriptionConfirm
  planName="Pro"
  monthlyPrice={5}
  coinLabel="USDC"
  yearlyPricePct={90}
  onConfirm={async (isYear) => {
    const tx = client.authorizeAndSubscribe({
      walletId,
      serviceId,
      coinType,
      paymentNonce: createPaymentNonce("sub"),
      isYear,
    });

    const result = await signAndExecuteTransaction({ transaction: tx });
    return { digest: result.Transaction?.digest };
  }}
/>

SubscriptionConfirmProps:

ConfirmResult is:

export type ConfirmResult = { digest?: string } | void;

#QR checkout

The example page builds a QR link from the app origin:

const payLink = `${origin}/supayment/subscribe?service=demo&coin=${coin}`;

For a real plan, use the actual serviceId:

const payLink = `${origin}/supayment/subscribe?service=${serviceId}&coin=${coinLabel}`;

The payer scans the QR, opens checkout, reviews the recurring allowance, and signs from their own wallet.

#SDK package

package.json exposes:

Main exports from ./src/index.ts:

export * from "./client";
export * from "./types";

Confirmed function exports from ./src/client.ts:

SubscriptionClient methods:

Core SDK types:

Runtime config:

const runtime = {
  packages: {
    SUP_WALLET: "0x...",
    SUP_SUBSCRIPTION: "0x...",
  },
  paymentKit: {
    registryId: paymentKitDefaultRegistryId("testnet"),
  },
  serviceType: "0x...::subscription::SubscriptionService",
};

#On-chain module

Module:

module SupSubscription::subscription

Constants:

Key structs:

Events:

Public functions:

create_service asserts:

subscribe computes the first payment, calls intent::request_payment, calls intent::validate_and_pay, processes a PaymentRegistry payment, verifies the receipt, transfers ChargeCap to service.service_owner, transfers Receipt<CoinType> to the subscriber, and emits Subscribed.

charge_fee asserts:

#Retired Sup-plan entitlement bridge (historical)

Do not call this endpoint or send funds from an old Sup plan link. The Wallet-address entitlement bridge is retired, the current route always returns 410 Gone, and the checkout page refuses a ?plan= link before any signature. Current plans use signed-in SSO account checkout at /pricing.

Before retirement, checkout called:

POST /api/billing/subscribe-confirm

Request body:

{
  "address": "0x...",
  "plan": "pro",
  "cycle": "month",
  "network": "mainnet",
  "digest": "..."
}

Request fields:

The endpoint calls:

verifySubscribeTx({
  network,
  digest: body.digest.trim(),
  payer: body.address,
  subscriptionPackage: getRuntime(network).packages.SUP_SUBSCRIPTION,
  serviceId: getPlanServiceId(network, plan.id),
  isYear: cycle === "year",
})

verifySubscribeTx checks that the transaction succeeded, was signed by payer, and is not older than 30 * 60 * 1000 milliseconds. It then requires a <SUP_SUBSCRIPTION>::subscription::Subscribed event whose service_id is the claimed plan's on-chain Service, whose subscriber is payer, and whose is_year matches the claimed cycle.

The event is the proof of payment: the contract emits it only after taking the fee at the Service's own on-chain price, so matching it to the plan's Service is stronger than any amount comparison this endpoint could make. A plan with no deployed Service cannot be claimed at all.

Historically, the digest was claimed in the shared payment ledger. Those writer routes are now 410 Gone; their ledgers remain only as protected evidence.

Historical success response (no longer emitted):

{
  "ok": true,
  "entitlement": {
    "address": "0x...",
    "plan": "pro",
    "network": "mainnet",
    "source": "subscription",
    "cycle": "month",
    "startedAt": 1720000000000,
    "expiresAt": 1722592000000,
    "tx": "..."
  }
}

Historical idempotent response (no longer emitted):

{
  "ok": true,
  "entitlement": {
    "address": "0x...",
    "plan": "pro",
    "network": "mainnet",
    "source": "subscription",
    "cycle": "month",
    "startedAt": 1720000000000,
    "expiresAt": 1722592000000,
    "tx": "..."
  },
  "already": true
}

Historical error responses (the current route always returns 410):

#Gotchas

Check the paymentNonce. The SDK enforces <= 36 characters and non-empty strings. Use createPaymentNonce("sub") unless you need your own idempotency key.

Check the serviceOwner. create_service requires ctx.sender() == service_owner, so the payout address must sign plan creation.

Check the billing units. The Move module stores price as atomic u64. The UI examples divide by 1e9 for display in the testnet demo.

Check the cancellation path. A subscriber cancels by revoking the wallet allowance granted to SubscriptionService for the CoinType.