add the sandbox authorization reversal and expiry simulators to the spec

[shreyav]

Summary

POST /sandbox/cards/{id}/simulate/authorization_reversal and POST /sandbox/cards/{id}/simulate/authorization_expiry have been live for some time but were never in the spec, so generated clients could not call them and integrators had no way to discover them.

The return_reversal endpoint's description went further and stated that neither existed:

Note: authorization reversal / void has no dedicated card-issuer simulate path (the void simulator emits a distinct VOID event), so — like authorization expiry — it is not exposed here.

Both are documented now and that note is gone.

What changed

Two new paths

• simulate/authorization_reversal — a merchant cancelling an authorization before it settles, in full or in part. Takes a new SandboxCardReversalRequest: the transaction plus an optional amount. Omit amount to reverse the whole authorization; send one to reverse only that much. The schema does not admit 0 — leaving the field out is the only way to express a full reversal, the same shape as the return simulator's amount. Same production-platform gating as simulate/authorization.
• simulate/authorization_expiry — the card network letting an authorization lapse because the merchant never followed through. Reuses SandboxCardTransactionRefRequest, whose description now names both of its callers. Sandbox-only, like return_reversal.

Both act on an authorization that is still fully open with nothing settled, since the issuer's void simulator rejects a partially-cleared one. Both return 202 with the issuer transaction token and land their result via the events webhook, matching the other simulators.

The descriptions are written for an integrator deciding whether to call the endpoint — what real-world event it stands in for and what to expect afterwards — rather than for someone who already knows the issuer's event names.

Corrected prose — the incorrect note in return_reversal is removed.

Lint config — the two paths join the kebab-case allowlist in .spectral.yaml for the same reason the other simulators are there: they mirror the issuer's routes verbatim and the SDK must call those exact URLs.

Breaking-change check

Additive only: two new paths and one new request schema. No existing path, schema, or enum value changes. Nothing a client has already received is affected.

Test plan

This is a spec + docs repo with no application code, so verification is the spec toolchain:

• npm run lint:openapi — Redocly validates clean at 55 warnings, one fewer than main. Spectral is 901 problems / 0 errors / 179 warnings, identical to main when both are linted in place.
• npm run build:openapi — rebundled openapi.yaml and mintlify/openapi.yaml; the two are identical, and the bundle diff contains exactly the source edits.
• Both new request bodies round-trip through the bundled schema: a reversal with and without amount, and an expiry with only cardTransactionId.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Sep 9, 2026, 5:37 PM

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated
grid-flow-builder	Ignored	Preview	Sep 9, 2026 6:48pm UTC
grid-wallet-demo	Ignored	Preview	Sep 9, 2026 6:48pm UTC

[github-actions]

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

feat: add the sandbox authorization reversal and expiry simulators to the spec

go

feat: add the sandbox authorization reversal and expiry simulators to the spec

kotlin

feat: add the sandbox authorization reversal and expiry simulators to the spec

openapi

feat: add the sandbox authorization reversal and expiry simulators to the spec

php

feat: add the sandbox authorization reversal and expiry simulators to the spec

python

feat: add the sandbox authorization reversal and expiry simulators to the spec

ruby

feat: add the sandbox authorization reversal and expiry simulators to the spec

typescript

feat: add the sandbox authorization reversal and expiry simulators to the spec

⏳ grid-typescript studio

⏳ grid-openapi studio

⏳ grid-ruby studio

⏳ grid-kotlin studio

⏳ grid-go studio

⏳ grid-python studio

⏳ grid-php studio

⏳ grid-cli studio

⏳ These are partial results; builds are still running.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-09-09 19:07:47 UTC

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge with no actionable contract, documentation, or security failures identified.

Summary

• Documents full and partial authorization reversal through a new request schema.
• Documents authorization expiry using the existing card-transaction reference request.
• Preserves the established Basic authentication, asynchronous webhook delivery, issuer-token correlation, and sandbox error-response patterns.
• Updates generated bundles, Spectral path exceptions, and the public changelog consistently.

Diagram

sequenceDiagram
  participant Client
  participant SandboxAPI as Sandbox API
  participant Issuer
  participant Webhook as Events webhook
  Client->>SandboxAPI: POST authorization_reversal or authorization_expiry
  SandboxAPI->>Issuer: Simulate operation on open authorization
  SandboxAPI-->>Client: 202 + issuerTransactionToken
  Issuer-->>Webhook: Resulting card operation

Loading