feat(sandbox): add the card correction simulate endpoint

[ls-bolt]

Summary

Adds POST /sandbox/cards/{id}/simulate/correction, so integrators can drive a network correction against a settled card transaction in the sandbox.

A correction is an adjustment the card network makes to money it has already moved. The two directions behave differently and the request says which:

• DEBIT takes further funds from the cardholder. It is permanent — nothing releases it and no capture settles against it.
• CREDIT returns funds the network took in error, the way a return does.

The resulting card operation is delivered asynchronously via the events webhook, like every other card simulator, and the endpoint 404s in production.

Why the direction is an explicit field

Every card transaction event carries an effective_polarity (CREDIT | DEBIT) — the network's own statement of which way the money moved. Taking the direction explicitly on the request keeps the simulated event's polarity consistent with its type, so a simulated correction exercises the same direction contract a real one would rather than having it inferred.

Changes

• openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_correction.yaml — new path, modelled on the other card simulators (same auth, same error set, same 202 + SandboxCardSimulationResponse).
• openapi/components/schemas/cards/SandboxCardCorrectionRequest.yaml — new request body: cardTransactionId, amount, direction.
• openapi/openapi.yaml — path registration.
• openapi.yaml / mintlify/openapi.yaml — rebundled via npm run build:openapi.

Testing

• npm run build:openapi bundles clean.
• npm run lint (redocly + spectral) reports nothing against the new path or schema; the remaining output is the repo's pre-existing schema-properties-have-examples / -have-descriptions warnings on unrelated schemas.
• Both examples (correctionDebit, correctionCredit) are spelled out on the request body.

The implementation of this route lands separately in the internal backend.

Requested by @AaryamanBhute

[mintlify]

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

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Sep 16, 2026, 10:12 AM

[vercel]

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

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Sep 16, 2026 10:11am UTC
grid-flow-builder	Ignored	Preview	Sep 16, 2026 10:11am UTC
grid-wallet-demo	Ignored	Preview	Sep 16, 2026 10:11am UTC

[lightspark-bot]

• feat(sandbox): add the card correction simulate endpoint #1010 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✱ Stainless preview builds for grid

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

cli

chore(internal): regenerate SDK with no functional changes

go

chore(internal): regenerate SDK with no functional changes

kotlin

chore(internal): regenerate SDK with no functional changes

openapi

feat(api): add simulate correction endpoint to sandbox cards

php

chore(internal): regenerate SDK with no functional changes

python

chore(internal): regenerate SDK with no functional changes

ruby

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-typescript studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ❗) → test ✅

New diagnostics (1 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /sandbox/cards/{id}/simulate/correction`

✅ grid-cli studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ❗ → lint ❗ → test ❗

New diagnostics (1 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /sandbox/cards/{id}/simulate/correction`

✅ grid-openapi studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗

New diagnostics (1 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /sandbox/cards/{id}/simulate/correction`

✅ grid-kotlin studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ❗

New diagnostics (1 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /sandbox/cards/{id}/simulate/correction`

✅ grid-ruby studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ (prev: build ✅) → lint ✅ → test ✅

New diagnostics (1 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /sandbox/cards/{id}/simulate/correction`

✅ grid-go studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ (prev: build ✅) → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@04e76cadd8e404c507ec82b0b843aac1744ea26d

New diagnostics (1 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /sandbox/cards/{id}/simulate/correction`

✅ grid-python studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ❗) → test ❗

New diagnostics (1 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /sandbox/cards/{id}/simulate/correction`

✅ grid-php studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → lint ✅ → test ✅

New diagnostics (1 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /sandbox/cards/{id}/simulate/correction`

---

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-16 10:15:12 UTC