Test helpers

/v1/test_helpers is the administrative test subsurface, following Stripe's own namespace for capabilities beyond real-API parity. Same key, same lane. Two helpers today: the dispute trigger (Mockpay-specific — Stripe has none) and test clocks.

Dispute trigger

Method	Path	Action
`POST`	`/v1/test_helpers/payment_intents/:id/dispute`	Chargeback any succeeded intent, regardless of payment method. Answers the dispute (`needs_response`); the normal dispute lifecycle follows. `400` when the intent has no successful charge or is already disputed.

Disputes also open organically: confirm with pm_card_createDispute. The trigger exists for chargebacks on intents that already succeeded with any other method.

Test clocks

Method	Path	Action
`POST` / `GET`	`/v1/test_helpers/test_clocks`	Create (`frozen_time` epoch seconds required, `name` optional); list
`GET` / `DELETE`	`/v1/test_helpers/test_clocks/:id`	Retrieve; delete (attached customers delete, their active subscriptions cancel)
`POST`	`/v1/test_helpers/test_clocks/:id/advance`	Advance to a later `frozen_time`. Synchronous — the clock answers `ready`.

Attach a customer at creation with test_clock. Clocked customers and their subscriptions anchor created and period math to the clock's frozen time. Advancing rolls active subscription periods forward while current_period_end <= frozen_time; cancel_at_period_end subscriptions cancel at the boundary (ended_at = period end). No invoices — period rollover emits customer.subscription.updated.

# Chargeback a succeeded intent
curl -X POST https://api.mockpay.net/v1/test_helpers/payment_intents/pi_.../dispute \
  -u mock_sk_...:

# Clock → clocked customer → subscription → advance a month
curl https://api.mockpay.net/v1/test_helpers/test_clocks \
  -u mock_sk_...: -d frozen_time=1755000000

curl https://api.mockpay.net/v1/customers \
  -u mock_sk_...: -d email=swan@example.com -d test_clock=clock_...

curl https://api.mockpay.net/v1/test_helpers/test_clocks/clock_.../advance \
  -u mock_sk_...: -d frozen_time=1757592060

Official SDK reachability

Test clocks are first-party SDK methods: stripe.testHelpers.testClocks.create(...), .advance(...), .del(...). The dispute trigger is Mockpay-specific; reach it without leaving the configured client:

await stripe.rawRequest(
  "POST",
  `/v1/test_helpers/payment_intents/${intent.id}/dispute`,
  {},
);

Event types

test_helpers.test_clock.created / test_helpers.test_clock.advancing / test_helpers.test_clock.ready / test_helpers.test_clock.deleted
charge.dispute.created (from the dispute trigger)

Not emulated

Stripe test helpers for resources Mockpay does not emulate answer 404: customers/:id/fund_cash_balance, refunds/:id/expire (Mockpay refunds settle synchronously), confirmation_tokens, issuing, terminal, treasury. They arrive with the resources they exercise.