Payment crediting
Let PaymentService own orders and issue Primary Card credits only after paid.
Payment status paid and wallet fulfillment status are independent: paid does not mean Credits have arrived. Free-amount topups credit the Primary Card; card purchases use the entitlement snapshot and stable fulfillment time captured for the order. This example handles topups only. Card fulfillment should use the second callback argument, fulfillment, for entitlement and expiration.
const credits = new CreditsService();
const payment = new PaymentService({
providers: [stripePaymentProvider()],
resolve_topup: ({ topup_amount_minor }) => ({
credits: topup_amount_minor * 10_000,
}),
on_paid: async (record, fulfillment) => {
if (fulfillment.entitlement.kind !== "topup") {
throw new Error("This integration supports topups only");
}
await credits.topup({
card: { kind: "primary", user_id: record.user_id },
credits: record.credits,
source: "payment",
ref: record.payment_id,
idempotency_key: `payment:${record.payment_id}`,
note: record.note,
});
},
});Users create a Payment order directly; Credits does not store pending payment topups:
await city.payment.method("stripe").invoke({
topup_amount_minor: 500,
idempotency_key: "order_123",
note: "Buy Credits",
});The user submits the intended payment amount. resolve_topup calculates and snapshots Credits on Federation, so the client never controls the conversion rate. Payment confirmation must use trusted amount, currency, and external transaction facts from a verified event or Provider API and compare them with the local order snapshot. Request metadata is not proof of payment. Tax, discount, and currency conversion semantics must be explicit; missing or mismatched facts block fulfillment and require review. Every paid event requires trusted amount, currency, and an external transaction ID; missing or mismatched facts cause a 422 failure and enter review. Stripe projects subtotal minus discount and checks the total equation. Creem uses signed order amount_paid when present, otherwise amount. Waffo converts the signed decimal amount exactly using currency precision. Dodo currently requires one-time dynamic pricing in the same currency, no discounts/PPP, and tax-inclusive pricing, then checks signed total_amount. See the Provider pages for exact fields and limits. These rules do not promise automatic support for arbitrary tax, discount, or currency-conversion schemes.
Use your account wallet
Open Account → Wallet for available Credits and individual Credits cards. Your unique Primary never expires and has a bottom-right top-up action. Limited-time cards show remaining Credits, expiry and status. Select a card for its ledger, Buy limited-time cards for plan cards, or Orders for payment and delivery details. An expired card shows its last recorded balance but contributes no available Credits. Ledger balances remain historical facts.
Top-ups credit the permanent Primary. Limited-time cards are bought through external payment without spending existing Credits. Operators configure name, currency, minor-unit price, Credits, duration in seconds and sale status in Fedman's card-plan page. No configuration means no plans on sale; local Demo prices are never production products.
Purchases submit only a server plan_id, method_id and stable idempotency_key. Later price, entitlement or sale-status changes do not change existing orders. Validity starts at the persisted first fulfillment time; retries retain that time. The success redirect only asks you to check the order and never grants Credits. Paid orders with failed delivery can retry fulfillment.
This wallet does not provide automatic refunds, chargeback recovery, balance-to-card exchange or subscriptions. Disabling a plan does not refund an order; contact the service operator for payment disputes.
Event inbox and recovery
After signature verification and normalization, webhook handling persists the trusted event in the inbox and enqueues it before returning HTTP 200. This acknowledges receipt, not completed fulfillment. Enqueue failures return an error, while the stored event remains recoverable. Queue runs payment.events/process; replay uses the stored normalized event without re-verifying the old HTTP request signature.
The host must periodically call payment.recover_events(), or an administrator can call POST /v1/payment/events/recover, to wake due pending events and processing events with expired leases. The current Edge Worker scans every five minutes; federation.toml declares deployment schedules through deployment.crons.
Transient failures retry with exponential backoff starting at 15 seconds, capped at one hour, and move to review after 20 attempts. Amount validation failures (422) enter review directly instead of retrying indefinitely.
Administrators use GET /v1/payment/events/inbox to inspect the latest 100 events, status, attempts, and diagnostic errors. After addressing the cause, call POST /v1/payment/events/replay with JSON { "event_id": "provider:event_id" }. Replay repeats order validation and idempotent fulfillment; it never bypasses amount checks. Implement on_paid(record, fulfillment) idempotently using the stable payment_id and entitlement snapshot.