Pay MPP subscriptions
A page approves the access key of a merchant once, and the merchant charges each period.
Overview
A Machine Payments Protocol (MPP) subscription lets a merchant other than the app, such as an API, charge each period. The merchant's route responds with an HTTP 402 challenge that names its own access key, the amount, the period, and the expiry.
accounts.fetch opens Tempo ID's dialog, where the user approves that access key once. The merchant then charges each period itself, and the chain enforces the approved limit.
Only a browser page subscribes, since the approval needs the dialog.
The demo subscribes to 1 OUSD each minute for 10 minutes, and shows each charge.
Walkthrough
The mpp-subscription example runs a subscription against its own merchant, with the session on its backend, as Pay for a backend's session shows.
Create the instance
The mpp plugin adds accounts.fetch. maxAmount caps the cost of one period.
import { Accounts } from 'accounts'
import { mpp } from 'accounts/mpp'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
// `accounts.fetch` needs an access key. A subscription never spends it.
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
// A period of a subscription may charge at most 10 OUSD.
plugins: [mpp({ maxAmount: '10' }), react()],
})Sign the user in
dialog.signIn opens Tempo ID's dialog on the page, and sets the session.
import { accounts } from './tempo.config.js'
export function App() {
const { session } = accounts.useSession()
if (!session)
return (
<button onClick={() => accounts.dialog.signIn()} type="button">
Sign in with Tempo
</button>
)
return <p>Signed in as {session.user.email}</p>
}import { Accounts } from 'accounts'
import { mpp } from 'accounts/mpp'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
// `accounts.fetch` needs an access key. A subscription never spends it.
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
// A period of a subscription may charge at most 10 OUSD.
plugins: [mpp({ maxAmount: '10' }), react()],
})Subscribe
Tempo ID's dialog shows the challenge's amount, period, and expiry. After the approval, the request sends again with the approval as its credential, and the merchant charges the first period. The session keeps its own access key.
The merchant serves the route with the subscription method of mppx's server, as api.ts of the example shows. The dialog can approve with any Tempo Account of the user, so the merchant checks that the credential's signer belongs to its user.
import { Receipt } from 'mppx'
import { useState } from 'react'
import { accounts } from './tempo.config.js'
const url = 'https://merchant.example/api/subscription'
export function Subscribe() {
const [reference, setReference] = useState<string>()
if (reference) return <p>Charged in {reference}</p>
return (
<button
onClick={async () => {
const response = await accounts.fetch(url)
if (!response.ok)
throw new Error(`The merchant failed with ${response.status}.`)
// The receipt names the transaction of the first charge.
setReference(Receipt.fromResponse(response).reference)
}}
type="button"
>
Subscribe
</button>
)
}import { Accounts } from 'accounts'
import { mpp } from 'accounts/mpp'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
// `accounts.fetch` needs an access key. A subscription never spends it.
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
// A period of a subscription may charge at most 10 OUSD.
plugins: [mpp({ maxAmount: '10' }), react()],
})Handle a refused subscription
accounts.fetch rejects before any payment: with Accounts.RequestError for a denial, and with MaxAmountError for a period above maxAmount.
import { Accounts } from 'accounts'
import { MaxAmountError } from 'accounts/mpp'
import { useState } from 'react'
import { accounts } from './tempo.config.js'
const url = 'https://merchant.example/api/subscription'
export function Subscribe() {
const [refusal, setRefusal] = useState<string>()
return (
<>
<button
onClick={async () => {
try {
await accounts.fetch(url)
} catch (error) {
if (error instanceof Accounts.RequestError)
setRefusal(`Tempo ID refused the subscription: ${error.code}.`)
else if (error instanceof MaxAmountError)
setRefusal('A period costs more than `maxAmount`.')
else throw error
}
}}
type="button"
>
Subscribe
</button>
{refusal && <p role="alert">{refusal}</p>}
</>
)
}import { Accounts } from 'accounts'
import { mpp } from 'accounts/mpp'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
// `accounts.fetch` needs an access key. A subscription never spends it.
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
// A period of a subscription may charge at most 10 OUSD.
plugins: [mpp({ maxAmount: '10' }), react()],
})Handle the expiry
The subscription ends at its challenge's expiry, and the route responds with 402 again. A plain fetch reads that status with no payment.
import { useState } from 'react'
const url = 'https://merchant.example/api/subscription'
export function Status() {
const [active, setActive] = useState<boolean>()
async function check() {
const response = await fetch(url)
setActive(response.status !== 402)
}
if (active === undefined)
return (
<button onClick={check} type="button">
Check subscription
</button>
)
return <p>{active ? 'Subscribed' : 'No active subscription'}</p>
}Use cases
Each use case sets an option of the mpp plugin, or of one payer.
Pay for a backend's session
A page whose backend holds the session has no access key. accounts.mpp({ account }) pays the subscription for the Tempo Account that the backend names. Such a payer pays only subscriptions, in a browser.
import { accounts } from './tempo.config.js'
export function App() {
async function subscribe() {
// The backend names the Tempo Account of its session.
const response = await fetch('/v1/me')
if (!response.ok) return location.assign('/login')
const me = (await response.json()) as { account: `0x${string}` }
await accounts
.mpp({ account: me.account })
.fetch(new URL('/v1/subscription', location.origin))
}
return (
<button onClick={subscribe} type="button">
Subscribe
</button>
)
}import { Accounts } from 'accounts'
import { mpp } from 'accounts/mpp'
// The backend holds the session, so the page's instance requests no access key.
export const accounts = Accounts.create({
accessKey: false,
chain: 'testnet',
plugins: [mpp({ maxAmount: '10' })],
})Pay only subscriptions
A route can offer a one-time charge beside a subscription. orderChallenges filters and sorts the offers before any payment, and the payer pays the first that it returns.
import { Accounts } from 'accounts'
import { mpp } from 'accounts/mpp'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
// `accounts.fetch` needs an access key. A subscription never spends it.
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
plugins: [
mpp({
maxAmount: '10',
orderChallenges: (candidates) =>
candidates.filter(
(candidate) => candidate.challenge.intent === 'subscription',
),
}),
react(),
],
})Identify the user to the merchant
identity sends the session's access token and ID token with each request to the origins of its scope. A merchant that verifies them with mppx's Tempo ID extension then keys the subscription by user.
import { Accounts } from 'accounts'
import { mpp } from 'accounts/mpp'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
// `accounts.fetch` needs an access key. A subscription never spends it.
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
plugins: [
mpp({
identity: { scope: ['https://merchant.example'] },
maxAmount: '10',
}),
react(),
],
})Skip the deposit page
The merchant charges the first period at once, and refuses an unfunded account only after the approval, with a generic error. So for a balance below the first period, Tempo ID's deposit page shows before the dialog.
retry with balance: false turns that page off, such as for an app with its own deposit flow.
import { Accounts } from 'accounts'
import { mpp } from 'accounts/mpp'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
// `accounts.fetch` needs an access key. A subscription never spends it.
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
// A period of a subscription may charge at most 10 OUSD.
plugins: [mpp({ maxAmount: '10', retry: { balance: false } }), react()],
})