feat: sandbox simulate endpoints for the full card-event set#715
Conversation
Add 7 sandbox card-event simulate endpoints, mirroring the existing
authorization/clearing/return simulators: balance_inquiry,
credit_authorization, financial_authorization, financial_credit_authorization,
authorization_advice, credit_authorization_advice, return_reversal. All POST,
sandbox-only, 202 -> { issuerTransactionToken }.
Correct the existing 3 simulators' documented success response from
200/CardTransaction to 202/SandboxCardSimulationResponse to match the actual
issuer-driven, webhook-delivered behavior.
Authorization expiry and authorization reversal/void are intentionally excluded
(no card-issuer simulate path).
Co-Authored-By: aaryamanbhute <aaryamanbhute@users.noreply.github.com>
ls-bolt
Bot
added
bolt
breaking-change
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
|
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript ✅ grid-ruby studio · code
|
Greptile SummaryThis PR completes the sandbox card-event simulate surface by adding 7 new
Confidence Score: 4/5Safe to merge with the understanding that the 200→202 response shape change on the three existing simulate endpoints is a visible contract change for any sandbox consumer already parsing those responses. The new endpoints and schemas are well-structured, consistent, and pass lint. The only findings are two 404 description inconsistencies (missing the "(also returned in production for this path)" qualifier on authorization_advice and return_reversal) — cosmetic but worth fixing for documentation clarity. The more substantive point is that the 200→202 correction on the existing authorization, clearing, and return simulators is a real shape change; sandbox-only, but any client already parsing the old CardTransaction body will break. The two new endpoint files sandbox_cards_{id}simulate_authorization_advice.yaml and sandbox_cards{id}_simulate_return_reversal.yaml have the minor 404 description inconsistency. The existing authorization, clearing, and return endpoint files are worth double-checking if any internal sandbox client depends on the old response shape.
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/cards/SandboxCardAuthorizationAdviceRequest.yaml | New schema for authorization_advice — correct use of OpenAPI 3.1 numeric exclusiveMinimum: 0 on amount, required fields match endpoint semantics. |
| openapi/components/schemas/cards/SandboxCardSimulationResponse.yaml | New shared response schema (issuerTransactionToken) used consistently by all 10 simulate endpoints. |
| openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml | New authorization_advice endpoint; 404 description missing the "(also returned in production for this path)" qualifier present on all other endpoints in this family. |
| openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml | New return_reversal endpoint; same inconsistent 404 description as authorization_advice. |
| openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization.yaml | Correctly updated from 200/CardTransaction to 202/SandboxCardSimulationResponse to match async delivery semantics. |
| openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_clearing.yaml | Updated from 200/CardTransaction to 202/SandboxCardSimulationResponse — consistent correction. |
| openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml | Updated from 200/CardTransaction to 202/SandboxCardSimulationResponse — consistent correction. |
| .spectral.yaml | Regex correctly extended with a second branch that exactly enumerates all 7 snake_case simulate paths, keeping the carve-out narrowly scoped. |
| .redocly.lint-ignore.yaml | All 7 new snake_case simulate path keys added to the kebab-case ignore list — complete and correct. |
Sequence Diagram
%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Client
participant GridSandboxAPI as Grid Sandbox API
participant CardIssuer as Card Issuer Sandbox
participant Webhook as Client Webhook
Client->>GridSandboxAPI: "POST /sandbox/cards/{id}/simulate/<event>"
Note over GridSandboxAPI: Validates card id,<br/>request body, sandbox token
GridSandboxAPI->>CardIssuer: Poke issuer sandbox simulate route
CardIssuer-->>GridSandboxAPI: issuerTransactionToken
GridSandboxAPI-->>Client: "202 { issuerTransactionToken }"
Note over CardIssuer,Webhook: Async delivery
CardIssuer->>Webhook: Card operation event (CardTransaction updated)
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Client
participant GridSandboxAPI as Grid Sandbox API
participant CardIssuer as Card Issuer Sandbox
participant Webhook as Client Webhook
Client->>GridSandboxAPI: "POST /sandbox/cards/{id}/simulate/<event>"
Note over GridSandboxAPI: Validates card id,<br/>request body, sandbox token
GridSandboxAPI->>CardIssuer: Poke issuer sandbox simulate route
CardIssuer-->>GridSandboxAPI: issuerTransactionToken
GridSandboxAPI-->>Client: "202 { issuerTransactionToken }"
Note over CardIssuer,Webhook: Async delivery
CardIssuer->>Webhook: Card operation event (CardTransaction updated)
Prompt To Fix All With AI
Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 3
openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml:66-67
**Inconsistent 404 description missing production-context note**
The `authorization` endpoint (and all other new card-level simulate paths — `balance_inquiry`, `credit_authorization`, `financial_authorization`, `financial_credit_authorization`, `credit_authorization_advice`) use `"Card not found (also returned in production for this path)"` as their 404 description to clarify that a sandbox-only endpoint still returns 404 in production. Both `authorization_advice` and `return_reversal` use `"Card or card transaction not found"` without that qualifier. A caller reading only those two endpoint definitions won't know the production vs. sandbox behaviour differs.
### Issue 2 of 3
openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml:68-69
The `return_reversal` 404 description is missing the production-context note used on all other endpoints in this family. The other card-level simulate endpoints follow the pattern `"Card or card transaction not found (also returned in production for this path)"`, but this one drops the parenthetical, leaving callers uncertain about production behaviour.
```suggestion
'404':
description: Card or card transaction not found (also returned in production for this path)
```
### Issue 3 of 3
openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml:66-67
Same issue as `return_reversal` — the 404 description is missing the `"(also returned in production for this path)"` qualifier that every other endpoint in this simulate family uses, including the existing `authorization` and all five other new endpoints.
```suggestion
'404':
description: Card or card transaction not found (also returned in production for this path)
```
Reviews (1): Last reviewed commit: "feat: sandbox simulate endpoints for the..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| '404': | ||
| description: Card or card transaction not found |
There was a problem hiding this comment.
The authorization endpoint (and all other new card-level simulate paths — balance_inquiry, credit_authorization, financial_authorization, financial_credit_authorization, credit_authorization_advice) use "Card not found (also returned in production for this path)" as their 404 description to clarify that a sandbox-only endpoint still returns 404 in production. Both authorization_advice and return_reversal use "Card or card transaction not found" without that qualifier. A caller reading only those two endpoint definitions won't know the production vs. sandbox behaviour differs.
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml
Line: 66-67
Comment:
**Inconsistent 404 description missing production-context note**
The `authorization` endpoint (and all other new card-level simulate paths — `balance_inquiry`, `credit_authorization`, `financial_authorization`, `financial_credit_authorization`, `credit_authorization_advice`) use `"Card not found (also returned in production for this path)"` as their 404 description to clarify that a sandbox-only endpoint still returns 404 in production. Both `authorization_advice` and `return_reversal` use `"Card or card transaction not found"` without that qualifier. A caller reading only those two endpoint definitions won't know the production vs. sandbox behaviour differs.
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| '404': | ||
| description: Card or card transaction not found |
There was a problem hiding this comment.
return_reversal 404 description is missing the production-context note used on all other endpoints in this family. The other card-level simulate endpoints follow the pattern "Card or card transaction not found (also returned in production for this path)", but this one drops the parenthetical, leaving callers uncertain about production behaviour.
| '404': | |
| description: Card or card transaction not found | |
| '404': | |
| description: Card or card transaction not found (also returned in production for this path) |
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml
Line: 68-69
Comment:
The `return_reversal` 404 description is missing the production-context note used on all other endpoints in this family. The other card-level simulate endpoints follow the pattern `"Card or card transaction not found (also returned in production for this path)"`, but this one drops the parenthetical, leaving callers uncertain about production behaviour.
```suggestion
'404':
description: Card or card transaction not found (also returned in production for this path)
```
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| '404': | ||
| description: Card or card transaction not found |
There was a problem hiding this comment.
return_reversal — the 404 description is missing the "(also returned in production for this path)" qualifier that every other endpoint in this simulate family uses, including the existing authorization and all five other new endpoints.
| '404': | |
| description: Card or card transaction not found | |
| '404': | |
| description: Card or card transaction not found (also returned in production for this path) |
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml
Line: 66-67
Comment:
Same issue as `return_reversal` — the 404 description is missing the `"(also returned in production for this path)"` qualifier that every other endpoint in this simulate family uses, including the existing `authorization` and all five other new endpoints.
```suggestion
'404':
description: Card or card transaction not found (also returned in production for this path)
```
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Merge activity
|
3 participants
Summary
Adds the 7 remaining sandbox card-event simulate endpoints, completing the set alongside the existing
authorization,clearing, andreturnsimulators. Each isPOST, sandbox-only, and returns202with{ "issuerTransactionToken": string }— the simulate call drives the card issuer's sandbox and the resulting card operation is delivered asynchronously via webhook.New endpoints (all under
/sandbox/cards/{id}/simulate/):balance_inquirySandboxCardBalanceInquiryRequest(merchantonly — a $0 inquiry)credit_authorizationSandboxCardAuthorizationRequestfinancial_authorizationSandboxCardAuthorizationRequestfinancial_credit_authorizationSandboxCardAuthorizationRequestauthorization_adviceSandboxCardAuthorizationAdviceRequest(cardTransactionId+ new totalamount)credit_authorization_adviceSandboxCardAuthorizationRequestreturn_reversalSandboxCardTransactionRefRequest(cardTransactionId)New schemas:
SandboxCardBalanceInquiryRequest,SandboxCardAuthorizationAdviceRequest,SandboxCardTransactionRefRequest, and a sharedSandboxCardSimulationResponse({ issuerTransactionToken }).SandboxCardAuthorizationRequestandCardMerchantare reused.Response correction to the existing 3 simulators: they were documented as
200returning a fullCardTransaction, but these simulators are asynchronous — they return an issuer transaction token and deliver the resulting card operation over webhook. This PR correctsauthorization,clearing, andreturnto202/SandboxCardSimulationResponseso the whole simulate family is consistent.Intentionally excluded: authorization expiry and authorization reversal / void — neither has a card-issuer simulate path.
Notes
simulate/*path segments are snake_case to match the card issuer's simulate routes verbatim, so they're exempted from the repo's kebab-case path convention (scoped carve-outs in.spectral.yamland.redocly.lint-ignore.yaml, not a global relaxation).info.versionbump: no breaking change to an existing published contract — this documents new endpoints and corrects the stale response shape on the existing simulators.Test plan
make build— rebundlesopenapi.yaml+mintlify/openapi.yaml; both contain the 7 new paths, 7 operationIds, and the 4 new schemas.make lint— passes (Redocly + Spectral + markdown), 0 errors.Original PR: #684