docs: sync documentation with SCA schema changes - #701
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
Greptile SummaryThis PR documents the Strong Customer Authentication (SCA) flow introduced for EU-region customers, adding a
Confidence Score: 4/5Safe to merge after resolving the transaction vs. quote ownership wording for scaChallenge; the rest of the changes are additive and accurate. The core SCA flow is correctly described and the new state diagram transitions are accurate. One content issue in transaction-lifecycle.mdx points developers to 'the transaction's scaChallenge' when the actual authorize call goes to a quote endpoint — a developer acting solely on the webhook and the status table description would be pointed in the wrong direction. The missing PENDING_AUTHORIZATION payload example compounds this gap. transaction-lifecycle.mdx — the status table description, missing webhook payload tab, and getUserMessage example all need a pass to align with the quote-based authorize flow.
|
| Filename | Overview |
|---|---|
| mintlify/platform-overview/core-concepts/quote-system.mdx | Adds a 'Strong Customer Authentication (EU Customers)' section under Executing a Quote; covers the PENDING_AUTHORIZATION status, scaChallenge object, and /quotes/{quoteId}/authorize endpoint. Only the SMS_OTP authorize flow is shown; the PASSKEY variant is not documented. |
| mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx | Adds PENDING_AUTHORIZATION to the status table, state diagram, and webhook events table; updates the webhook handler example. The status table incorrectly directs developers to 'the transaction's scaChallenge' while the authorize endpoint is quote-based; a PENDING_AUTHORIZATION webhook payload example and an SCA scenario tab are also missing. |
Sequence Diagram
%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant App
participant GridAPI
participant Customer
App->>GridAPI: POST /quotes
GridAPI-->>App: "Quote { status: PENDING_AUTHORIZATION, scaChallenge }"
App->>Customer: Prompt SCA challenge (e.g. SMS OTP)
Customer-->>App: Submits proof (code)
App->>GridAPI: "POST /quotes/{quoteId}/authorize { code }"
GridAPI-->>App: Quote status update
alt More challenges required
GridAPI-->>App: status: PENDING_AUTHORIZATION (next challenge)
App->>Customer: Prompt next SCA challenge
Customer-->>App: Submits proof
App->>GridAPI: "POST /quotes/{quoteId}/authorize"
end
GridAPI-->>App: Quote status: PROCESSING
GridAPI--)App: Webhook: OUTGOING_PAYMENT.PENDING_AUTHORIZATION
GridAPI--)App: Webhook: OUTGOING_PAYMENT.PROCESSING
GridAPI--)App: Webhook: OUTGOING_PAYMENT.COMPLETED
%%{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 App
participant GridAPI
participant Customer
App->>GridAPI: POST /quotes
GridAPI-->>App: "Quote { status: PENDING_AUTHORIZATION, scaChallenge }"
App->>Customer: Prompt SCA challenge (e.g. SMS OTP)
Customer-->>App: Submits proof (code)
App->>GridAPI: "POST /quotes/{quoteId}/authorize { code }"
GridAPI-->>App: Quote status update
alt More challenges required
GridAPI-->>App: status: PENDING_AUTHORIZATION (next challenge)
App->>Customer: Prompt next SCA challenge
Customer-->>App: Submits proof
App->>GridAPI: "POST /quotes/{quoteId}/authorize"
end
GridAPI-->>App: Quote status: PROCESSING
GridAPI--)App: Webhook: OUTGOING_PAYMENT.PENDING_AUTHORIZATION
GridAPI--)App: Webhook: OUTGOING_PAYMENT.PROCESSING
GridAPI--)App: Webhook: OUTGOING_PAYMENT.COMPLETED
Comments Outside Diff (2)
-
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx, line 453-455 (link)The
getUserMessagehelper in the Best Practices accordion is missingOUTGOING_PAYMENT.PENDING_AUTHORIZATION. Developers following this example would fall through to the genericdefaultbranch for EU SCA customers, showing "Payment status updated." instead of prompting the user to complete their authentication challenge.Context Used: mintlify/AGENTS.md (source)
Prompt To Fix With AI
This is a comment left during a code review. Path: mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx Line: 453-455 Comment: The `getUserMessage` helper in the Best Practices accordion is missing `OUTGOING_PAYMENT.PENDING_AUTHORIZATION`. Developers following this example would fall through to the generic `default` branch for EU SCA customers, showing "Payment status updated." instead of prompting the user to complete their authentication challenge. **Context Used:** mintlify/AGENTS.md ([source](https://app.greptile.com/lightspark/github/lightsparkdev/grid-api/-/custom-context?memory=51934046-75fb-42d3-9870-f42d61cb60e3)) How can I resolve this? If you propose a fix, please make it concise.
-
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx, line 307-368 (link)The Scenarios tabs cover Happy Path, Failure with Refund, Failure with Failed Refund, Bank Return, and Manual Cancellation — but there is no tab for the SCA flow (
PENDING → PENDING_AUTHORIZATION → PROCESSING → COMPLETED). Adding this would round out the new documentation and help EU-region developers quickly confirm the expected webhook sequence.Prompt To Fix With AI
This is a comment left during a code review. Path: mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx Line: 307-368 Comment: **Missing SCA scenario tab** The Scenarios tabs cover Happy Path, Failure with Refund, Failure with Failed Refund, Bank Return, and Manual Cancellation — but there is no tab for the SCA flow (`PENDING → PENDING_AUTHORIZATION → PROCESSING → COMPLETED`). Adding this would round out the new documentation and help EU-region developers quickly confirm the expected webhook sequence. 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!
Prompt To Fix All With AI
Fix the following 4 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 4
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx:124
**Misleading field reference — `scaChallenge` lives on the quote, not the transaction**
The description says "authorize the transaction's `scaChallenge`", but the only authorize endpoint documented is `POST /quotes/{quoteId}/authorize`, and the `scaChallenge` object is shown on the quote response (in `quote-system.mdx`). A developer who receives an `OUTGOING_PAYMENT.PENDING_AUTHORIZATION` webhook has a transaction ID, not a quote ID — the status table should either reference the quote's `scaChallenge` and mention using the `quoteId` field, or a webhook payload example for this event should be added showing how to obtain the quote ID needed to call `/quotes/{quoteId}/authorize`.
### Issue 2 of 4
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx:453-455
The `getUserMessage` helper in the Best Practices accordion is missing `OUTGOING_PAYMENT.PENDING_AUTHORIZATION`. Developers following this example would fall through to the generic `default` branch for EU SCA customers, showing "Payment status updated." instead of prompting the user to complete their authentication challenge.
```suggestion
switch (webhookType) {
case 'OUTGOING_PAYMENT.PENDING':
return 'Payment processing...';
case 'OUTGOING_PAYMENT.PENDING_AUTHORIZATION':
return 'Authorization required. Please complete the security challenge to proceed.';
```
### Issue 3 of 4
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx:197
**Missing webhook payload example for `PENDING_AUTHORIZATION`**
The Example Payloads tabs include PENDING, COMPLETED, FAILED, and REFUND_COMPLETED, but there is no tab for `PENDING_AUTHORIZATION`. Without a concrete payload example, developers cannot see what fields (e.g., `quoteId`, `scaChallenge`) are available in the webhook body — which is critical for knowing how to retrieve the SCA challenge and call `POST /quotes/{quoteId}/authorize`.
### Issue 4 of 4
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx:307-368
**Missing SCA scenario tab**
The Scenarios tabs cover Happy Path, Failure with Refund, Failure with Failed Refund, Bank Return, and Manual Cancellation — but there is no tab for the SCA flow (`PENDING → PENDING_AUTHORIZATION → PROCESSING → COMPLETED`). Adding this would round out the new documentation and help EU-region developers quickly confirm the expected webhook sequence.
Reviews (1): Last reviewed commit: "docs: add PENDING_AUTHORIZATION status f..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| | Status | Description | | ||
| |--------|-------------| | ||
| | **PENDING** | Quote is pending confirmation | | ||
| | **PENDING_AUTHORIZATION** | Awaiting Strong Customer Authentication. Only occurs for customers in regions where SCA is required (e.g., EU); authorize the transaction's `scaChallenge` to proceed. | |
There was a problem hiding this comment.
scaChallenge lives on the quote, not the transaction
The description says "authorize the transaction's scaChallenge", but the only authorize endpoint documented is POST /quotes/{quoteId}/authorize, and the scaChallenge object is shown on the quote response (in quote-system.mdx). A developer who receives an OUTGOING_PAYMENT.PENDING_AUTHORIZATION webhook has a transaction ID, not a quote ID — the status table should either reference the quote's scaChallenge and mention using the quoteId field, or a webhook payload example for this event should be added showing how to obtain the quote ID needed to call /quotes/{quoteId}/authorize.
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
Line: 124
Comment:
**Misleading field reference — `scaChallenge` lives on the quote, not the transaction**
The description says "authorize the transaction's `scaChallenge`", but the only authorize endpoint documented is `POST /quotes/{quoteId}/authorize`, and the `scaChallenge` object is shown on the quote response (in `quote-system.mdx`). A developer who receives an `OUTGOING_PAYMENT.PENDING_AUTHORIZATION` webhook has a transaction ID, not a quote ID — the status table should either reference the quote's `scaChallenge` and mention using the `quoteId` field, or a webhook payload example for this event should be added showing how to obtain the quote ID needed to call `/quotes/{quoteId}/authorize`.
How can I resolve this? If you propose a fix, please make it concise.
There was a problem hiding this comment.
Good catch — and it's worse than a wording slip, so thanks for flagging it. I checked the schemas: Transaction/OutgoingTransaction have no scaChallenge property at all (only Quote does, at Quote.yaml:140). So "authorize the transaction's scaChallenge" pointed at a field that doesn't exist on the resource being described.
The transaction does carry quoteId, so that's the bridge. Fixed in three places:
transaction-lifecycle.mdxstatus table now reads: the challenge lives on the quote, fetchGET /quotes/{quoteId}using the transaction'squoteId, then authorize viaPOST /quotes/{quoteId}/authorize.TransactionStatus.yaml+OutgoingTransactionStatus.yamlhad the identical wrong sentence — these are the source the docs were paraphrasing, so I corrected them too rather than leaving the spec and docs disagreeing.- The webhook handler example now shows the actual two-step (
getQuote(data.quoteId)→ prompt withquote.scaChallenge) instead of just notifying the customer with no path to the challenge.
Also added the PENDING_AUTHORIZATION payload tab you asked about in the sibling thread, which makes quoteId concrete on the wire.
Two extra things I found while verifying against the spec, both fixed here:
- The state diagram edge was wrong. This PR had
PENDING_AUTHORIZATION → EXPIREDfor an unsatisfied challenge, butOutgoingTransactionFailureReason.yamldocumentsSCA_NOT_COMPLETEDas a failure reason, andfailureReasononly accompaniesFAILED. Changed toPENDING_AUTHORIZATION → FAILEDand documentedfailureReason: SCA_NOT_COMPLETEDin the new scenario tab. WebhookType.yamlwas missingOUTGOING_PAYMENT.PENDING_AUTHORIZATIONwhileOutgoingPaymentWebhook.yamllisted it. SinceOutgoingPaymentWebhookextendsBaseWebhook, whosetypeis$ref'd toWebhookType, the event we're documenting couldn't validate against the base enum — which is why the generated client has no such member. Added it, so documenting the webhook is now backed by a spec that actually admits it.
make lint passes (exit 0) and the bundle regenerated cleanly — the openapi.yaml / mintlify/openapi.yaml diff is only the lines I changed, no reformat churn.
|
📌 Bolt Status 2026-07-30 16:19:38 UTC — ⚡ Agent |
…on docs Document the new Strong Customer Authentication (SCA) flow for EU customers: - Add PENDING_AUTHORIZATION status to transaction status table - Update state diagram with SCA authorization flow - Add OUTGOING_PAYMENT.PENDING_AUTHORIZATION webhook event - Add SCA section to quote system docs explaining the authorize flow - Update webhook handling example to show SCA case Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
⚡ On it — addressing the two open Greptile threads (the |
The transaction resource has no scaChallenge field — only Quote does. Route readers through the transaction's quoteId, add the missing webhook payload example and SCA scenario tab, and correct the abandoned-challenge terminal state to FAILED/SCA_NOT_COMPLETED. Co-Authored-By: jklein24 <jklein24@users.noreply.github.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
e410530 to
d91e3a9
Compare
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-typescript studio · code · diff
✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-python studio · code · diff
✅ grid-php studio · code · diff
✅ grid-cli studio · code · diff
This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
Revision 2Addressed both open review threads, and fixed three spec inaccuracies surfaced while verifying the docs against the schemas. Review feedback
Found while verifying
|
2 participants
Summary
Documents the
PENDING_AUTHORIZATIONquote/transaction status for Strong Customer Authentication (EU customers), and corrects three places where the existing spec described SCA inaccurately.Documentation
quote-system.mdx— new "Strong Customer Authentication (EU Customers)" section covering thePENDING_AUTHORIZATIONstatus, thescaChallengeobject, andPOST /quotes/{quoteId}/authorize. Spells out that where the challenge appears depends on funding: a prefunded quote gets it fromexecute(the challenge does not exist until then, so the proof always goes on the follow-up authorize and re-callingexecutereturns409), while a realtime/JIT-funded quote gets it earlier withpaymentInstructionswithheld.transaction-lifecycle.mdx—PENDING_AUTHORIZATIONadded to the status table, state diagram, and webhook events table, plus aPENDING_AUTHORIZATIONpayload tab, an "SCA Authorization (EU)" scenario tab, and the event wired into both the webhook handler andgetUserMessageexamples.Corrections
Three inaccuracies in the pre-existing spec, found while verifying this documentation against the schemas:
scaChallengewas attributed to the wrong resource.TransactionStatus.yamlandOutgoingTransactionStatus.yamlboth said "authorize the transaction'sscaChallenge", but neitherTransactionnorOutgoingTransactionhas that property — onlyQuotedoes. A developer holding a transaction from anOUTGOING_PAYMENT.PENDING_AUTHORIZATIONwebhook had no documented path to the challenge. Both now route through the transaction'squoteId→GET /quotes/{quoteId}→POST /quotes/{quoteId}/authorize.WebhookTypeomitted the event this PR documents.OutgoingPaymentWebhook.yamllistedOUTGOING_PAYMENT.PENDING_AUTHORIZATION, butWebhookType.yaml— whichBaseWebhook.typeis$ref'd to, and whichOutgoingPaymentWebhookextends — did not. The event could not validate against the base enum, which is why generated clients carry no such member. Added.Wrong terminal state for an abandoned challenge. An earlier revision of this PR drew
PENDING_AUTHORIZATION → EXPIRED.OutgoingTransactionFailureReason.yamldocumentsSCA_NOT_COMPLETEDas a failure reason, andfailureReasononly accompaniesFAILED, so the edge isPENDING_AUTHORIZATION → FAILEDwithfailureReason: SCA_NOT_COMPLETED.Test plan
make lintpasses (exit 0) — Redocly + Spectral, no new findingsopenapi.yaml/mintlify/openapi.yamlrebundled; diff is only the changed lines, no reformat churnTabs/Tab/Info/Note/Warning/Accordion) and code fences balancedmint devneeds Node 20/22; this pod has v24)Note:
make lint-markdownfails onmaintoo —package.jsonhas nolint:markdownscript. Pre-existing, not from this change.