Top-up page
An end user of your app funds their own budget by credit card on a hosted page. Your server creates a top-up session; the user opens the page and authorizes; the result is a credit card authorization-backed budget for that user with one stream that pays your app's service node. Your app then meters work against that stream.
Status: Live in Stripe TEST mode. Live credit card keys are release-gated (the live-ready switch).
The credit card rail must be configured on the deployment (Stripe TEST keys, or the in-repo simulator in tests); otherwise creating a top-up is refused with topup_card_mode_absent. No card data reaches Dynamo: the rail authorizes through Stripe with payment method tokens only. With CORE_CARD_PUBLISHABLE_KEY set, the page has a card form whose card field is Stripe's own (see the card form).
Create a session (your server)
cd ~
pwd
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/topups" \
-H "Authorization: Bearer $DYNAMO_API_KEY" -H 'content-type: application/json' \
-d '{"endUserRef":"user-42","amountMicroUsd":"5000000","payeeServiceNode":"0x00000000000000000000000000000000000000a1"}'
| Field | Required | Meaning |
|---|---|---|
endUserRef | yes | your id for the end user (letters, digits, _ . : -, up to 64) |
amountMicroUsd | yes | the funded ceiling, integer micro-USD as a decimal string |
payeeServiceNode | yes | the service node that is paid; must have a connected account on the deployment |
mandate | no | {categories?, maxDepth?}; the safe default when absent |
ratePerSecondUnits | no | the stream's per-second allowance (default: the whole amount per second) |
expiresInSeconds | no | how long the page link works, 60 to 86400 (default 3600) |
payeeOffer | when own hops are required | the app agent's signed payee offer (signPayeeOffer: categories, issuedAt, expiresAt, signature), valid from now until the link expires; required when the credit card mode requires own hops (the default for money modes) |
sessionKeyAddress | no | owner-api 1.9.0: a session key the payer signs vouchers with itself; library and self-hosted cores only (see below) |
A payer-supplied session key. A library or self-hosted core can be configured with the payer's session signers (CoreConfig.sessionSigners, a resolver from key address to a signer handle; never read from the environment). With sessionKeyAddress, the top-up's stream opens on that key and every voucher is signed through the resolver, and the core stores no key for the stream. A key the resolver does not supply is refused with session_signer_missing at create, and again when the end user pays if it was withdrawn meanwhile (the top-up stays pending, nothing authorized). The hosted tier answers session_signer_unavailable. Without the field the core generates the stream's per-stream key as before.
The answer carries topupId, state: "pending" and url (/pay/topup/<token>). Send the user to <base><url>. The token in the URL works for that one top-up only.
GET /owner/v1/topups (paginated) and GET /owner/v1/topups/:id show the state: pending, funding (the authorization is running), funded (with budgetId and streamId) or failed (with failureCode).
Who signs what
The app agent (the payee) signs its payee offer with its own key when your server creates the session. With @dynamoprotocol/sdk and a viem account holding the app agent's key, the signing step is:
import { payeeOffer, signPayeeOffer } from "@dynamoprotocol/sdk";
const { audience } = await (await fetch(`${process.env.DYNAMO_CORE_URL}/payee/v1/audience`)).json(); // this core's audience
const now = BigInt(Math.floor(Date.now() / 1000));
const offer = await signPayeeOffer(appAgent, payeeOffer({
serviceNode: appAgent.address, categories: ["*"], audience, standing: true, // the end user is not known in advance
issuedAt: now, expiresAt: now + 7200n, // a standing offer lives at most 7 days
}));
// POST /owner/v1/topups with { endUserRef, amountMicroUsd, payeeServiceNode: appAgent.address, payeeOffer: offer }
Where own hops are required, a child allowance below the top-up needs two signatures: the app agent signs the hop (signHopIntent(appAgent, hopIntent({...})), sent as delegation), and the payee of the child signs its own offer (payeeOffer). The pay-per-use starter (examples/starters/pay-per-use/run.mjs) does all three.
The end user holds no key. When the top-up carries a payee offer, their click on the page, checked against the page's CSRF token, is recorded as the consent for the budget's first hop (without an offer, which an operator setting of CORE_OWN_HOPS=optional allows, no consent is recorded). The budget's signed record names the top-up, and evidence 1.4.0 marks that first hop consented, not key-signed. Every allowance the app agent opens below it is signed by the app agent's own key as usual.
The page (the end user)
The page shows the amount and the payee, a card field when the card form is on, and one Authorize button. The authorization runs at most once per top-up, even when the page is open in two tabs. A decline leaves nothing charged and the top-up failed; create a new session to try again.
Without CORE_CARD_PUBLISHABLE_KEY the page has no card form: the button reads Authorize $X with the test card and authorizes the deployment's test payment method (CORE_CARD_PAYMENT_METHOD, pm_card_visa by default), not a card of the end user's.
The card form
Set CORE_CARD_PUBLISHABLE_KEY to your Stripe TEST publishable key (pk_test_…). A live key (pk_live_…) refuses boot with card_publishable_live_key, and the key needs the credit card rail configured. With the key set:
- The page loads Stripe.js from
js.stripe.comand shows Stripe's card
field (Stripe Elements, with its default postal code field) inside Stripe's own frame. A small script the core serves (/pay/topup.js) asks Stripe for a payment method and posts only its id (pm_…) with the page's CSRF value. The page has no card input of its own, and a post carrying anything else (a card number, a CVC, a malformed id) is refused with invalid_request before any call to Stripe.
- The core authorizes exactly that payment method for the top-up amount,
rounded up to whole cents. A post without a payment method is refused; the deployment's test payment method is never used instead.
- Only the top-up page's content security policy allows Stripe: scripts and
frames from js.stripe.com, frames from hooks.stripe.com, and connections to api.stripe.com. Every other hosted page keeps the narrow policy.
- Cards that ask for bank authentication (3-D Secure) are not supported in
the preview: the authorization is refused with topup_authentication_required and nothing is charged.
- The hold is not renewed. Stripe keeps an online card authorization for 7
days (Stripe: place a hold on a payment method, read 2026-11-06). The core closes the budget out one day before the hold expires: it stops the streams, captures what the payees' signed vouchers cover, and releases the rest. The card hold lasts up to 7 days and is not renewed: the budget ends before the hold expires, and the end user funds a new top-up after that.
Stripe's test cards are listed on Stripe: testing.
Error codes
topup_card_mode_absent
The credit card rail is not configured on this deployment. Configure Stripe TEST keys and the payee map (CORE_CARD_PAYEES), and allow the card mode.
topup_payee_not_routable
The payee service node has no connected account here. Add it to CORE_CARD_PAYEES. Refused before any authorization.
topup_payee_offer_required
This deployment requires own hops on credit card budgets. Sign a payee offer with the app agent's key and send it as payeeOffer. Nothing was created.
topup_payee_offer_invalid
The payee offer is not signed by payeeServiceNode, is malformed, or does not cover the time from now until the link expires. Nothing was created.
session_signer_missing
The deployment's session signer resolver supplies no signer for sessionKeyAddress. Supply it, or omit the field. Nothing was created or authorized.
session_signer_unavailable
The hosted tier takes no payer-supplied session signer. Omit sessionKeyAddress. Nothing was created.
topup_not_pending
The top-up already ran (funded or failed). Create a new session.
topup_declined
The credit card authorization was declined. Nothing was charged.
topup_authentication_required
The card asks for bank authentication (3-D Secure), which the preview does not support. Nothing was charged; the top-up is failed. Create a new session and use a card that does not ask for it.
topup_funding_failed
The authorization did not complete. Nothing was charged.
test_fixture_money_mode
The payee is a reserved test service node; those run on Control Mode budgets only. See testing.
csrf_invalid
The page's form was not submitted from the page that rendered it.
invalid_request
The body failed validation; param names the field. On the page's post: the form carried a field other than its CSRF value and a payment method id, a malformed id, no payment method while the card form is on, or one while it is off. Nothing was authorized.
Token codes are listed on widgets, and each has its own error page:
token_missing
No browser token was sent. See token_missing.
token_malformed
The token is not a top-up token in the expected format. See token_malformed.
token_wrong_kind
A token minted for another surface. See token_wrong_kind.
token_signature_invalid
The token's signature does not verify. See token_signature_invalid.
token_expired
The top-up session ended. See token_expired.
token_revoked
The token was revoked or is unknown. See token_revoked.