docs: sync documentation with SCA schema changes#701
Conversation
…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 <[email protected]>
|
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.| | Event | Description | | ||
| |-------|-------------| | ||
| | `OUTGOING_PAYMENT.PENDING` | Transaction created, quote pending confirmation | | ||
| | `OUTGOING_PAYMENT.PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication (EU customers only) | |
There was a problem hiding this comment.
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.
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: 197
Comment:
**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`.
**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.
Summary
PENDING_AUTHORIZATIONquote/transaction status for Strong Customer Authentication (EU customers)Changes
Documentation Updates
PENDING_AUTHORIZATIONstatus,scaChallengeobject, and/quotes/{quoteId}/authorizeendpointPENDING_AUTHORIZATIONto the status tableOUTGOING_PAYMENT.PENDING_AUTHORIZATIONwebhook eventNot Updated (No Changes Needed)
Test plan
make lintto verify OpenAPI spec is validmake mintto preview documentation locally🤖 Generated with Claude Code