Credit card sandbox

The credit card rail (funding: "card") funds the same budget object with a card authorization-backed budget: one manual-capture authorization for the full budget is the funded ceiling. Captures follow the settled voucher totals and never exceed the authorization; split transfers pay each service node's connected account its voucher totals less the platform fee, which is recorded as its own ledger row (on by default at 50 basis points); release cancels what is left of the authorization. This repository runs the rail in Stripe TEST mode only. Status: Live with Stripe TEST keys; live keys are Release-gated. Nothing on this page involves real money.

Turn it on for a local core

The credit card mode needs a Stripe TEST secret key and the payees' TEST connected accounts:

  1. Put your Stripe TEST secret key (sk_test_…) in .env as

STRIPE_SECRET_KEY.

  1. Run make card-setup once. It creates two Stripe TEST connected accounts

to act as payees and prints their acct_… ids.

  1. Boot the core as in Control Mode, adding

CORE_ALLOWED_MODES=none,card, STRIPE_SECRET_KEY and CORE_CARD_PAYEES, a JSON object mapping each payee's serviceNode address to its acct_… id. CORE_CARD_PAYMENT_METHOD names the test payment method that funds budgets; it defaults to pm_card_visa. Optionally set CORE_CARD_PUBLISHABLE_KEY to your Stripe TEST publishable key (pk_test_…) to give the hosted top-up page a card form (top-up page).

Set both STRIPE_SECRET_KEY and CORE_CARD_PAYEES or neither: a half configured credit card mode refuses to boot. A key that is not a Stripe TEST key (sk_test_… or rk_test_…) is refused when the configuration is parsed. Payment methods are Stripe tokens (pm_…); card numbers never touch the system.

To see a whole session without booting a core, make demo-card runs one end to end against Stripe TEST (authorize, streams, captures, split transfers, refund, release) and prints the reconciliation table; make demo-card-decline shows a declined renewal ending in a fail-closed halt at the last funded voucher.

What changes when the credit card rail is on

budget's ceiling is the uncaptured authorization. When the authorization expires, the budget's ceiling is dead and every further charge is refused.

vouchers bill, and cumulative captures never exceed the authorization.

stop; nothing accrues beyond the funded ceiling.

carries the delegator's signed hop intent and the payee's signed offer unless the operator sets CORE_OWN_HOPS=optional.

never captured; after capture, refunds and transfer reversals are recorded against the settlement (holdback and refunds).

Live keys are release-gated

CORE_CARD_RAIL_MODE is test by default. Setting it to live refuses boot until every live safeguard is configured, and even a complete live configuration stops at card_live_release_gated: this build never constructs a live Stripe client. A live-shaped Stripe key in any environment variable refuses boot in either mode.

More depth: card authorization-backed budgets. A credit card session can be exported as an offline-verifiable evidence bundle: the record of what was signed, delivered, settled and refunded.