Skip to content

docs: sync card documentation with PENDING_AUTH state #606

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
claude wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: sync card documentation with PENDING_AUTH state #606

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion mintlify/snippets/cards/intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Comment on lines 27 to 29

@greptile-apps greptile-apps Bot Jun 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 The table in intro.mdx lists states in lifecycle order (PENDING_KYC → PROCESSING → ACTIVE → FROZEN → CLOSED), but PENDING_AUTH has been inserted between PENDING_KYC and PROCESSING. In the actual lifecycle, PENDING_AUTH occurs after PROCESSING — as correctly shown in the issuing-cards.mdx state table. Placing it before PROCESSING here will confuse developers trying to map the sequence.

Suggested change
| `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. |
| `PENDING_KYC` | Cardholder has not finished KYC; the card cannot transact yet. |
| `PROCESSING` | Card has been requested and is being provisioned with the issuer. |
| `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. |
Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/cards/intro.mdx
Line: 27-29

Comment:
The table in `intro.mdx` lists states in lifecycle order (PENDING_KYC → PROCESSING → ACTIVE → FROZEN → CLOSED), but `PENDING_AUTH` has been inserted between `PENDING_KYC` and `PROCESSING`. In the actual lifecycle, `PENDING_AUTH` occurs after `PROCESSING` — as correctly shown in the `issuing-cards.mdx` state table. Placing it before `PROCESSING` here will confuse developers trying to map the sequence.

```suggestion
| `PENDING_KYC` | Cardholder has not finished KYC; the card cannot transact yet. |
| `PROCESSING` | Card has been requested and is being provisioned with the issuer. |
| `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. |
```

How can I resolve this? If you propose a fix, please make it concise.

| `ACTIVE` | Card is live and can authorize transactions. |
| `FROZEN` | Card is temporarily disabled. New authorizations are declined; in-flight settlements continue. |
Expand Down
10 changes: 6 additions & 4 deletions mintlify/snippets/cards/issuing-cards.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,17 +32,19 @@ one currency.
## The lifecycle

```text
PROCESSING ──► ACTIVE ──► FROZEN ──► ACTIVE ──► CLOSED
│ │ ▲
│ └──────────────────────────────┘
PROCESSING ──► PENDING_AUTH ──► ACTIVE ──► FROZEN ──► ACTIVE ──► CLOSED
│ │ │ ▲
│ │ └──────────────────────────────┘
│ └──────────────────────────────────────────────┘
│
└─► CLOSED (stateReason: ISSUER_REJECTED)
```
Comment on lines 34 to 41

@greptile-apps greptile-apps Bot Jun 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Direct PROCESSING → ACTIVE path missing from lifecycle diagram

The new diagram routes all cards through PENDING_AUTH, but the state table directly below (and the webhooks page) confirm that PENDING_AUTH "only appears for Embedded Wallet-funded cards." Regular cards still follow PROCESSING → ACTIVE directly. Any developer who reads this diagram first will conclude that PENDING_AUTH is mandatory for every card, which contradicts the conditional path described in the text.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/cards/issuing-cards.mdx
Line: 34-41

Comment:
**Direct `PROCESSING → ACTIVE` path missing from lifecycle diagram**

The new diagram routes all cards through `PENDING_AUTH`, but the state table directly below (and the webhooks page) confirm that `PENDING_AUTH` _"only appears for Embedded Wallet-funded cards."_ Regular cards still follow `PROCESSING → ACTIVE` directly. Any developer who reads this diagram first will conclude that `PENDING_AUTH` is mandatory for every card, which contradicts the conditional path described in the text.

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!


| 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. |

Expand Down
2 changes: 1 addition & 1 deletion mintlify/snippets/cards/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading