docs(openapi): document card pending auth state

[DhruvPareek]

Reason

Cards funded by Embedded Wallet internal accounts need card-specific delegated signing authorization before they can transact. The card issuance docs should expose the interim state that occurs after POST /cards but before POST /auth/delegated-keys completes for that card.

Overview

• Add PENDING_AUTH to CardState.
• Document that POST /cards may return cards in PENDING_AUTH when an Embedded Wallet internal account is used as a funding source.
• Keep the documented progression as PENDING_AUTH → PROCESSING → ACTIVE for cards that complete delegated auth before issuer processing finishes.
• Rebuild openapi.yaml and mintlify/openapi.yaml from the OpenAPI source.

Test Plan

• make build
• make lint-openapi

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jun 18, 2026 6:11pm
grid-wallet-demo	Ignored	Preview	Jun 18, 2026 6:11pm

[DhruvPareek]

• docs(openapi): document card pending auth state #591 👈 (View in Graphite)
• add card-scoped /auth/delegated-keys endpoints #574
• add card-scoped DelegatedKey schemas #573
• 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

docs(api): add Embedded Wallet requirements to funding-source parameter

csharp

feat(api): add PendingAuth state to card enums

go

feat(api): add PENDING_AUTH state to card lifecycle

kotlin

feat(api): add PENDING_AUTH state to cards

openapi

feat(api): add PENDING_AUTH state to card state enum

php

feat(api): add PENDING_AUTH state to cards

python

feat(api): add PENDING_AUTH state to cards

ruby

feat(api): add PENDING_AUTH state to card

typescript

feat(api): add PENDING_AUTH state to cards

✅ grid-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

✅ grid-ruby studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️ grid-go studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@102528a1f6992bd5910eafab9ec17247a5789067

✅ grid-kotlin studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️ grid-python studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/8f609854f558c17e2e57856de0b26b177b441883/grid-0.0.1-py3-none-any.whl

⚠️ grid-csharp studio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ✅ → test ❗

✅ grid-php studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → lint ✅ → test ✅

✅ grid-typescript studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/225d436a0923663cfe8e0152d5abdc0a12b160cc/dist.tar.gz

⚠️ grid-cli studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ❗

---

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-06-18 18:51:51 UTC

[greptile-apps]

Greptile Summary

This PR documents the new PENDING_AUTH card state introduced for cards backed by Embedded Wallet internal accounts. The source OpenAPI schema and both generated YAML files (openapi.yaml, mintlify/openapi.yaml) are updated consistently.

• Adds PENDING_AUTH to the CardState enum and its description table, clearly explaining the state occurs before delegated-key authorization is completed via POST /auth/delegated-keys.
• Updates the POST /cards operation description and 201 response description to document the PENDING_AUTH → PROCESSING → ACTIVE lifecycle for Embedded Wallet–funded cards.
• Updates the webhook note to reflect that card.state_change fires on each state transition (not just ACTIVE).

Confidence Score: 5/5

Documentation-only change with no runtime code; all four files are internally consistent and the new state is accurately described.

The change adds a new enum value and accompanying prose to OpenAPI schema and generated YAML files. The lifecycle description, state table, 201 response description, and webhook note are all mutually consistent. The two generated files match each other and the source exactly.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/components/schemas/cards/CardState.yaml	Adds PENDING_AUTH to the enum and the description table with an accurate, consistent explanation. Enum ordering is logical (KYC → AUTH → PROCESSING → ACTIVE → FROZEN → CLOSED).
openapi/paths/cards/cards.yaml	Adds two paragraphs explaining PENDING_AUTH and the delegated-key flow; updates the 201 response description and the webhook note. Content is accurate to the described lifecycle.
openapi.yaml	Generated file, identical changes to the source — enum entry added, description table row added, POST /cards description and 201 response updated correctly.
mintlify/openapi.yaml	Generated file, mirrors openapi.yaml changes exactly — no drift between the two generated outputs.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([POST /cards]) --> B{Embedded Wallet\nfunding source?}
    B -- Yes --> C[PENDING_AUTH\nCannot transact]
    B -- No --> E[PROCESSING\nIssuer provisioning]
    C -- POST /auth/delegated-keys\ncompletes --> E
    E -- Issuer approves --> F[ACTIVE\nCan transact]
    E -- Issuer rejects --> G[CLOSED\nstateReason: ISSUER_REJECTED]
    F -- Platform freezes --> H[FROZEN\nTemporarily disabled]
    H -- Platform unfreezes --> F
    F -- Platform closes --> G
    H -- Platform closes --> G

Loading

%%{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"}}}%%
flowchart TD
    A([POST /cards]) --> B{Embedded Wallet\nfunding source?}
    B -- Yes --> C[PENDING_AUTH\nCannot transact]
    B -- No --> E[PROCESSING\nIssuer provisioning]
    C -- POST /auth/delegated-keys\ncompletes --> E
    E -- Issuer approves --> F[ACTIVE\nCan transact]
    E -- Issuer rejects --> G[CLOSED\nstateReason: ISSUER_REJECTED]
    F -- Platform freezes --> H[FROZEN\nTemporarily disabled]
    H -- Platform unfreezes --> F
    F -- Platform closes --> G
    H -- Platform closes --> G

Loading

_{Reviews (7): Last reviewed commit: "docs(openapi): document card pending aut..." | Re-trigger Greptile}

[DhruvPareek]

Merge activity

• Jun 18, 6:44 PM UTC: @DhruvPareek merged this pull request with Graphite.