What Test Clocks Simulate
Test clocks compress time for billing logic, but not everything in a payment system is governed by billing logic. This page is the definitive list of what moves with the clock and what stays on real time.
What the clock animates
| Billing behaviour | Clock-animated? |
|---|---|
| Payment plan scheduling (next due dates) | ✅ Yes |
| Payment dispatch for card plans and subscriptions | ✅ Yes — card collection completes in sandbox |
| Subscription period rollover | ✅ Yes |
| Payment-link expiry | ✅ Yes |
| Dunning / retry schedules | ✅ Yes |
| Plan failure behaviour (retry dates, catch-up) | ✅ Yes |
| Bank (BECS) debit outcomes: submission, settlement, dishonours, late returns | ✅ Yes — see Bank debits on a clock |
Cards and bank debits are both animated. When the clock dispatches a card payment, the sandbox processes it to a final outcome immediately, so a single advance takes a card plan through dispatch and result. A bank debit takes business days, on the clock: see below.
What the clock does not animate
| Behaviour | Why |
|---|---|
| Ledger settlement, holds, payouts | Governed by real time and banking calendars; compressing them would misrepresent real cashflow |
| 3D Secure challenges | Require customer interaction; time alone can’t complete them |
| Refund timing | Refunds aren’t time-scheduled |
| Sandbox funds becoming spendable | Balances show in-transit and lodged amounts, but never advance to spendable in sandbox |
| Audit timestamps | created_at and similar always record real wall-clock time |
Bank debits on a clock
For a customer on a clock, the sandbox bank works on the clock’s time. Each advance:
- sends the clock’s due bank debits to the bank, at the clock’s time;
- settles each debit three business days after it was sent, once that date comes on the clock. Business days are counted on your account’s calendar, in its time zone and with its country’s public holidays;
- applies a late return whose date has come on the clock.
Outcomes land just after the clock reads ready, so poll the payment
intents. To fail one chosen debit, use the
bank test helpers:
dishonour for a debit that’s been sent and hasn’t settled, late_return
for a settled one. Either lands at the clock’s time.
Debits of customers without a clock keep running on real time. The ledger (settlement, holds and payouts) is never animated: the sandbox bank doesn’t post to it.
Timestamps: simulated vs real
Two kinds of time appear on clock-bound objects:
- Scheduling fields (
frozen_time, next payment dates, period starts and ends, link expiry) — simulated time - Audit fields (
created_at,last_advanced_at) — real wall-clock time
A payment intent generated at simulated Feb 1 will show a real-world
created_at of whenever you ran the advance. This is expected.