Charge on a Schedule

Create one escrow-backed charge per billing period using a wallet spend permission.

Use the deployed SpendPermissionPaymentCollector when a wallet approves repeated collection. Your scheduler still creates a fresh PaymentInfo and unique salt for every billing period because each protocol payment can be charged only once.

Demo

The demo above is mock only. If you want to see onchain demos on Vibenet, head to Base chain demos.

Charge One Billing Period

The collector reconstructs a spend permission from PaymentInfo: the payer is the account, the collector is the spender, the token and allowance come from the payment, and preApprovalExpiry is the permission end. Encode the permission signature and optional MagicSpend withdrawal request as collectorData.

Use a durable billing key such as subscriptionId:periodStart before submitting the protocol charge.

TypeScript

export async function chargeSubscriptionPeriod(args: {
  paymentInfo: PaymentInfo;
  collectorData: Hex;
  billingKey: string;
  amount: bigint;
  store: BillingStore;
}) {
  if (!(await args.store.reserveOnce(args.billingKey))) {
    throw new Error("Billing period was already submitted");
  }
  const simulation = await publicClient.simulateContract({
    account,
    address: AUTH_CAPTURE_ESCROW,
    abi: authCaptureEscrowAbi,
    functionName: "charge",
    args: [
      args.paymentInfo,
      args.amount,
      SPEND_PERMISSION_PAYMENT_COLLECTOR,
      args.collectorData,
      0n,
      zeroAddress,
    ],
  });
  const hash = await walletClient.writeContract(simulation.request);
  const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 });
  if (receipt.status !== "success") throw new Error("Scheduled charge reverted");
  await args.store.complete(args.billingKey, hash);
  return receipt;
}

A successful charge emits PaymentCharged and creates a protocol refundableAmount for that billing period.

Store the billing key, paymentInfoHash, charge transaction, amount, and spend-permission usage in one durable workflow.

The Commerce Payments Protocol does not run a scheduler. Protect the operator key, serialize retries, and do not reuse a prior period’s PaymentInfo or salt.

See Also

Request a Payment

Use the same charge lifecycle for a one-time checkout.

Refund a Payment

Reverse a charged billing period before refund expiry.