feat(cards): add PENDING_AUTH funding authorization status by DhruvPareek · Pull Request #1108 · lightsparkdev/grid-api

DhruvPareek · 2026-10-01T23:15:57Z

Reason

A provisioned USDB Embedded Wallet card cannot fund purchases until its delegated signing key is usable. Exposing it as ACTIVE hides the remaining signed authorization steps, including when an active USD card is switched to USDB.

Overview

Add server-managed PENDING_AUTH and DELEGATION_REQUIRED to the public card lifecycle.
Show terminal CLOSED transitions in both USD and USDB lifecycle diagrams, including closure from pending and frozen cards.
Document provisioning to PENDING_AUTH, USD-to-USDB and key-revocation transitions to PENDING_AUTH, PENDING_AUTH → FROZEN status-change webhooks, and automatic activation after the final delegated-key retry or a switch back to USD.
Preserve PROCESSING, FROZEN, and CLOSED during delegation completion. Explicit activation without usable delegation returns 409 INVALID_STATE_TRANSITION; callers cannot request PENDING_AUTH.
Add PENDING_AUTH-related issuance, funding, delegated-key, and webhook documentation and examples. Align the Embedded Wallet guide with pending status after key revocation, CARD_NOT_ACTIVE declines on new synchronous authorizations, and recovery through both signed retries. Preserve the existing state definitions and asynchronous issuance wording, and rebuild both bundled specifications.
Remove the unused global Mintlify install from the lint workflow. make lint uses the tools installed by npm ci; the global install was failing on an unpublished dependency before lint ran.

The webdev implementation is separately gated by card_program.pending_state.enabled, default off. Coordinate this contract with webdev #36815 (generated artifacts) and the implementation stack: core lifecycle #36857, delegation/backfill #36859, issuer provisioning #36860, and dashboard #36816. Publishing these docs does not enable the rollout. The webdev stack has been rebased and validated against current main.

The card status PENDING_AUTH distinguishes funding authorization from PENDING_KYC. Delegated keys retain their separate PENDING status.

Test Plan

make build — passed; regenerated openapi.yaml and mintlify/openapi.yaml.
make lint — passed with 0 errors and existing warnings/informational findings.
node_modules/.bin/markdownlint mintlify/snippets/cards/funding-sources.mdx mintlify/snippets/cards/implementation-overview.mdx mintlify/snippets/cards/intro.mdx mintlify/snippets/cards/issuing-cards.mdx mintlify/snippets/cards/quickstart.mdx mintlify/snippets/cards/webhooks.mdx — passed.
git diff --check — passed.
node_modules/.bin/markdownlint mintlify/snippets/cards/embedded-wallet-funding.mdx — passed after aligning the pending/revocation guidance.
CI refresh: restacked onto Grid API main at a80638013eadc4675ddbd762cca83e4851bf4a14; npm run lint passed with 0 errors, Markdown lint passed for all changed card snippets, and the bundled source matches webdev’s vendored spec byte-for-byte. The webdev grid-api-spec check still requires this PR to merge before the generated-artifact PR.

vercel · 2026-10-01T23:16:00Z

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

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Oct 8, 2026 10:58pm UTC
grid-flow-builder	Ignored	Preview	Oct 8, 2026 10:58pm UTC
grid-wallet-demo	Ignored	Preview	Oct 8, 2026 10:58pm UTC

mintlify · 2026-10-01T23:16:01Z

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

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Oct 8, 2026, 10:58 PM

DhruvPareek · 2026-10-01T23:16:13Z

feat(cards): add PENDING_AUTH funding authorization status #1108 👈 (View in Graphite)
main

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

greptile-apps · 2026-10-02T17:54:18Z

Confidence Score: 4/5

[Critical risk] Adds new card funding authorization status to public API contract.

The PR appears safe to merge, with non-blocking documentation inconsistencies to correct.

Findings

Revocation guidance conflicts ▶
Pending freeze event omitted ▶
Already-active response needs handling ▶
Lifecycle state count is stale ▶

Fix with agent prompt

### Issue 1
openapi/paths/auth/auth_delegated-keys_{id}.yaml:48-50
The new contract says revoking a delegated key moves an active card to `PENDING`, but the Embedded Wallet funding guide still says the card stays `ACTIVE` and every authorization declines. Please align the guide so integrators expect the right status and troubleshoot a missing key using the right flow.

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!

### Issue 2
openapi/webhooks/card-status-change.yaml:5-8
PATCH permits `PENDING → FROZEN` and sends a status-change webhook for every successful status transition, but this event list does not include that transition. Add it here and in the webhook guide so consumers know to handle a pending card being frozen.

### Issue 3
mintlify/snippets/cards/quickstart.mdx:49-53
The quickstart now says creation can return an `ACTIVE` card, then directs readers to wait for an activation webhook. An already-active response needs no later activation transition, so a reader could wait for an event that never follows. Tell readers to use that response directly and wait for the webhook only when activation is still pending.

```suggestion
The card returns `status: "PROCESSING"` if issuer provisioning is still
in progress. Synchronous provisioning can return `ACTIVE` for USD funding
or `PENDING` for USDB funding awaiting delegated signing authorization.
`platformCardId` is generated by the server, and any value supplied in the
request is ignored. If the response is already `ACTIVE`, use it directly.
Otherwise, when activation completes, a `CARD.STATUS_CHANGE` webhook fires
with `status: "ACTIVE"`:
```

### Issue 4
mintlify/snippets/cards/intro.mdx:32
Adding `PENDING` brings this table to six states, while the introduction still says five. Update the count so the overview matches the public lifecycle it presents.

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!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR adds a server-managed PENDING card status for provisioned USDB-funded cards awaiting delegated signing authorization, updates lifecycle and webhook documentation, regenerates both OpenAPI bundles, and removes an unused global Mint installation from lint CI.

The contract distinguishes issuer provisioning from funding readiness and documents automatic status changes on delegation, revocation, and funding-source replacement.
Several card guides still need alignment with the new lifecycle, particularly revocation and synchronous issuance.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  PROCESSING -->|USD or usable delegation| ACTIVE
  PROCESSING -->|USDB, delegation needed| PENDING
  PENDING -->|delegation completes or USD funding| ACTIVE
  ACTIVE -->|required key revoked or USDB funding lacks key| PENDING
  PENDING -->|platform freezes| FROZEN
  ACTIVE <--> FROZEN
  PENDING --> CLOSED
  ACTIVE --> CLOSED
  FROZEN --> CLOSED

_{Reviews (1) · Last reviewed commit: "fix(ci): use locked dependencies for doc..."}

greptile-apps · 2026-10-02T17:54:21Z

+    Revoke an `ACTIVE` delegated signing key. An active card using this funding
+    source becomes `PENDING` with `statusReason: "DELEGATION_REQUIRED"`. Frozen
+    and closed cards retain their status. Grid uses the custodied


Revocation guidance conflicts The new contract says revoking a delegated key moves an active card to PENDING, but the Embedded Wallet funding guide still says the card stays ACTIVE and every authorization declines. Please align the guide so integrators expect the right status and troubleshoot a missing key using the right flow.

Knowledge Base Used: Cards API

Prompt To Fix With AI

This is a comment left during a code review. Path: openapi/paths/auth/auth_delegated-keys_{id}.yaml Line: 48-50 Comment: **Revocation guidance conflicts** The new contract says revoking a delegated key moves an active card to `PENDING`, but the Embedded Wallet funding guide still says the card stays `ACTIVE` and every authorization declines. Please align the guide so integrators expect the right status and troubleshoot a missing key using the right flow. **Knowledge Base Used:** [Cards API](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/cards-api.md) --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

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!

benwgold · 2026-10-07T06:55:25Z

-PROCESSING ──► ACTIVE ◄──► FROZEN
-                 │
-                 └──► CLOSED
+USD:  PROCESSING ──► ACTIVE ◄──► FROZEN


hmm, this is missing PENDING_KYC?

or maybe we remove PENDING_KYC and make sure its represented as a statusReason?

Also just curious but what if it needs KYC AND delegation. Are we sure this will still work properly in that case?

Yea if we need KYC and delegation, we are in PROCESSING status because something still needs to be done on our side. If:
- KYC completes, status moves to PENDING
- Delegation completes, status moces to PROCESSING

PROCESSING is also the status when KYC needs to be approved on our side

benwgold · 2026-10-07T06:56:00Z

 | State | When you see it |
 |-------|-----------------|
 | `PROCESSING` | Returned synchronously from `POST /cards`. The card cannot transact yet. |
+| `PENDING` | The issuer has provisioned the card, but its USDB Embedded Wallet funding source has no active delegated key. Complete delegated-key setup. |


Can we make this more specific? PENDING_DELEGATED_AUTH?

ah nvm i see 'statusReason'

ls-bolt · 2026-10-07T06:56:27Z

🦣 Congratulations @benwgold - your substantive review earned a Giant moa! (common)

Female giant moa towered over males and were among the tallest birds known.

View your Frost-dex: https://zeus.dev.dev.sparkinfra.net/#/dinodex/benwgold?section=ice-age

shreyav · 2026-10-07T18:20:45Z

 enum:
  - PENDING_KYC
  - PROCESSING
+  - PENDING


should we call it PENDING_AUTH or NEEDS_AUTH, i feel like PENDING is kinda confusing with PENDING_KYC

ls-bolt · 2026-10-07T18:21:01Z

🦣 Congratulations @shreyav - your substantive review earned a Sinomastodon! (common)

This short-jawed gomphothere lived across eastern Asia into the Early Pleistocene.

View your Frost-dex: https://zeus.dev.dev.sparkinfra.net/#/dinodex/shreyav?section=ice-age

DhruvPareek · 2026-10-09T00:06:54Z

Merge activity

Oct 9, 12:06 AM UTC: A user started a stack merge that includes this pull request via Graphite.
Oct 9, 12:07 AM UTC: @DhruvPareek merged this pull request with Graphite.

mintlify Bot deployed to staging - mintlify October 1, 2026 23:16 View deployment

DhruvPareek marked this pull request as ready for review October 2, 2026 17:50

greptile-apps Bot reviewed Oct 2, 2026

View reviewed changes

mintlify Bot deployed to staging - mintlify October 2, 2026 17:55 View deployment

mintlify Bot deployed to staging - mintlify October 2, 2026 18:03 View deployment

mintlify Bot deployed to staging - mintlify October 2, 2026 18:20 View deployment

mintlify Bot deployed to staging - mintlify October 2, 2026 23:00 View deployment

DhruvPareek force-pushed the dp/card-pending-api branch from af80af0 to 0e7033f Compare October 6, 2026 23:09

mintlify Bot deployed to staging - mintlify October 6, 2026 23:10 View deployment

benwgold reviewed Oct 7, 2026

View reviewed changes

shreyav reviewed Oct 7, 2026

View reviewed changes

DhruvPareek force-pushed the dp/card-pending-api branch from 0e7033f to 0ed23fc Compare October 7, 2026 20:29

DhruvPareek changed the title ~~feat(cards): add PENDING funding authorization status~~ feat(cards): add PENDING_AUTH funding authorization status Oct 7, 2026

mintlify Bot deployed to staging - mintlify October 7, 2026 20:29 View deployment

DhruvPareek added 6 commits October 8, 2026 15:54

feat(cards): add PENDING funding authorization status

5538914

fix(ci): use locked dependencies for documentation lint

f106677

docs(cards): show terminal closure in lifecycle diagrams

b20bdd8

docs(cards): preserve existing wording when adding pending status

a8d7fe4

docs(cards): include pending freeze webhook transition

5a129e6

docs(cards): align embedded wallet revocation with pending readiness

fc54e5a

DhruvPareek force-pushed the dp/card-pending-api branch from 0ed23fc to fc54e5a Compare October 8, 2026 22:57

mintlify Bot deployed to staging - mintlify October 8, 2026 22:58 View deployment

shreyav approved these changes Oct 9, 2026

View reviewed changes

DhruvPareek merged commit dec16da into main Oct 9, 2026
11 checks passed

DhruvPareek deleted the dp/card-pending-api branch October 9, 2026 00:07

Conversation

DhruvPareek commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reason

Overview

Test Plan

Uh oh!

vercel Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlify Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DhruvPareek commented Oct 1, 2026

Uh oh!

greptile-apps Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Summary

Uh oh!

greptile-apps Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ls-bolt Bot commented Oct 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ls-bolt Bot commented Oct 7, 2026

Uh oh!

DhruvPareek commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DhruvPareek commented Oct 1, 2026 •

edited

Loading

vercel Bot commented Oct 1, 2026 •

edited

Loading

mintlify Bot commented Oct 1, 2026 •

edited

Loading

greptile-apps Bot commented Oct 2, 2026 •

edited

Loading

DhruvPareek commented Oct 9, 2026 •

edited

Loading