From 9843ca0db4299cd3bb3a1eaffeec24a5cb95b60c Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Fri, 19 Jun 2026 09:41:36 +0000
Subject: [PATCH] docs: add PENDING_AUTH state to card documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sync Mintlify card documentation with OpenAPI schema changes from commits
5ebb4e0 and ea40e01. Cards backed by Embedded Wallet funding sources now
enter PENDING_AUTH state until delegated key authorization is completed
via POST /auth/delegated-keys.

Updated:
- Card lifecycle table in intro snippet (5 → 6 states)
- State diagram and table in issuing-cards snippet
- Webhook event trigger list in webhooks snippet

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 mintlify/snippets/cards/intro.mdx         |  3 ++-
 mintlify/snippets/cards/issuing-cards.mdx | 10 ++++++----
 mintlify/snippets/cards/webhooks.mdx      |  2 +-
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/mintlify/snippets/cards/intro.mdx b/mintlify/snippets/cards/intro.mdx
index 5aee036c..5042a3ed 100644
--- a/mintlify/snippets/cards/intro.mdx
+++ b/mintlify/snippets/cards/intro.mdx
@@ -20,11 +20,12 @@ the same ledger you already use for payouts.
 
 ## Card lifecycle at a glance
 
-A card moves through five states:
+A card moves through six states:
 
 | State | Meaning |
 |-------|---------|
 | `PENDING_KYC` | Cardholder has not finished KYC; the card cannot transact yet. |
+| `PENDING_AUTH` | Card is backed by an Embedded Wallet funding source and the cardholder has not yet completed delegated signing authorization via `POST /auth/delegated-keys`. The card cannot transact. |
 | `PROCESSING` | Card has been requested and is being provisioned with the issuer. |
 | `ACTIVE` | Card is live and can authorize transactions. |
 | `FROZEN` | Card is temporarily disabled. New authorizations are declined; in-flight settlements continue. |
diff --git a/mintlify/snippets/cards/issuing-cards.mdx b/mintlify/snippets/cards/issuing-cards.mdx
index f0c36bbd..9b2603c2 100644
--- a/mintlify/snippets/cards/issuing-cards.mdx
+++ b/mintlify/snippets/cards/issuing-cards.mdx
@@ -32,9 +32,10 @@ one currency.
 ## The lifecycle
 
 ```text
-PROCESSING    ──► ACTIVE ──► FROZEN ──► ACTIVE ──► CLOSED
-       │             │                              ▲
-       │             └──────────────────────────────┘
+PROCESSING    ──► PENDING_AUTH ──► ACTIVE ──► FROZEN ──► ACTIVE ──► CLOSED
+       │               │              │                              ▲
+       │               │              └──────────────────────────────┘
+       │               └──────────────────────────────────────────────┘
        │
        └─► CLOSED (stateReason: ISSUER_REJECTED)
 ```
@@ -42,7 +43,8 @@ PROCESSING    ──► ACTIVE ──► FROZEN ──► ACTIVE ──► CLOSE
 | State | When you see it |
 |-------|-----------------|
 | `PROCESSING` | Returned synchronously from `POST /cards`. The card cannot transact yet. |
-| `ACTIVE` | Issuer provisioned the card. Reached via `CARD.STATE_CHANGE` webhook. |
+| `PENDING_AUTH` | Card is backed by an Embedded Wallet funding source and awaiting delegated key authorization via `POST /auth/delegated-keys`. Only appears for Embedded Wallet-funded cards. |
+| `ACTIVE` | Issuer provisioned the card (and delegated key authorization completed, if applicable). Reached via `CARD.STATE_CHANGE` webhook. |
 | `FROZEN` | You called `PATCH /cards/{id}` with `state: "FROZEN"`. |
 | `CLOSED` | You called `PATCH /cards/{id}` with `state: "CLOSED"` (or the issuer rejected provisioning). Terminal. |
 
diff --git a/mintlify/snippets/cards/webhooks.mdx b/mintlify/snippets/cards/webhooks.mdx
index e2301997..5d6ec577 100644
--- a/mintlify/snippets/cards/webhooks.mdx
+++ b/mintlify/snippets/cards/webhooks.mdx
@@ -12,7 +12,7 @@ extends the Transaction model with a card destination type).
 
 | Type | Fires on |
 |------|----------|
-| `CARD.STATE_CHANGE` | `PROCESSING → ACTIVE`, `→ CLOSED (ISSUER_REJECTED)`, and every subsequent `ACTIVE ⇄ FROZEN` and `→ CLOSED` transition. |
+| `CARD.STATE_CHANGE` | `PROCESSING → ACTIVE`, `PROCESSING → PENDING_AUTH`, `PENDING_AUTH → ACTIVE`, `→ CLOSED (ISSUER_REJECTED)`, and every subsequent `ACTIVE ⇄ FROZEN` and `→ CLOSED` transition. |
 | `CARD.FUNDING_SOURCE_CHANGE` | Whenever `PATCH /cards/{id}` updates the `fundingSources` array. |
 
 All three carry the standard envelope: