Sandbox

Exported from sandbox.ts. These are the request bodies for POST /v1/sandbox/* — simulating events without any real on-chain activity, only usable with a test API key.

Triggering a charge event — SandboxTriggerSchema

The body of POST /v1/sandbox/charges/{id}/trigger:

import { SandboxTriggerSchema, type TriggerableChargeEvent } from '@klappay/types'

SandboxTriggerSchema.parse({ event: 'charge.confirmed' })
SandboxTriggerSchema.parse({ event: 'charge.partially_paid', amount: 20 })

event is a TriggerableChargeEvent (exported from webhook-events.ts, re-used here rather than re-declared) — every charge event that represents a payment-progress state transition, i.e. every charge event except charge.created (a charge already exists by the time you have an id to trigger against):

export const TriggerableChargeEventSchema = ChargeWebhookEventTypeSchema.exclude([
  'charge.created',
])

Derived with .exclude() from the same enum webhook-events.ts already defines, not a second hand-maintained list — a future charge event added there is automatically excluded-or-included correctly here with no second place to remember to update.

amount applies to two events: charge.partially_paid (the amount to simulate as received so far — must be less than the charge's full amount, defaults to half of it if omitted) and charge.overpaid (the amount received — must be greater than the charge's full amount, defaults to 1.5x it if omitted). Ignored for every other event. Every triggerable event has a real precondition on the charge's current state (e.g. charge.underpaid requires the charge to already be partially_paid) — triggering one out of order is a 422 invalid_trigger_state response, not a silent no-op. This schema only validates the request shape; the state-machine precondition is enforced server-side.

There is no sandbox trigger for a non-charge event — POST /v1/sandbox/events/trigger/SandboxEventTriggerSchema were removed along with the account/security event categories they existed to simulate (2026-08). POST /v1/sandbox/charges/{id}/trigger above is the only sandbox trigger endpoint left.

See also

• webhooks.md — the full event vocabulary this schema draws from.
• An official SDK (github.com/klappay) offers ergonomic, named wrappers (sandbox.confirm(), sandbox.expire(), ...) built on top of this raw request shape, plus charge.waitFor(event) to await the result — see the live API reference for details.