Skip to content

docs(openapi): document card pending auth state #591

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

Merged
DhruvPareek merged 1 commit into from
Jun 18, 2026
Merged

docs(openapi): document card pending auth state #591

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
8 changes: 6 additions & 2 deletions mintlify/openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 6 additions & 2 deletions openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions openapi/components/schemas/cards/CardState.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
type: string
enum:
- PENDING_KYC
- PENDING_AUTH
- PROCESSING
- ACTIVE
- FROZEN
Expand All @@ -11,6 +12,7 @@ description: |
| State | Description |
|-------|-------------|
| `PENDING_KYC` | The cardholder has not yet completed KYC. Cards in this state cannot transact. |
| `PENDING_AUTH` | The card has been created with an Embedded Wallet funding source, but the cardholder has not yet completed card-specific delegated signing authorization with `POST /auth/delegated-keys`. Cards in this state cannot transact. |
| `PROCESSING` | The card has been requested and is being provisioned with the issuer. |
| `ACTIVE` | The card is live and can authorize transactions. |
| `FROZEN` | The card is temporarily disabled by the platform. New authorizations are declined with `CARD_PAUSED`. Existing settlements and refunds continue to reconcile. |
Expand Down
20 changes: 17 additions & 3 deletions openapi/paths/cards/cards.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,18 @@ post:
with `CARDHOLDER_KYC_NOT_APPROVED`.


If any funding source is an Embedded Wallet internal account, the
cardholder must authorize Grid to sign Spark token transactions for that
card by completing the delegated-key creation flow with
`POST /auth/delegated-keys`. Until an active delegated key exists for the
card, the card remains in `state: "PENDING_AUTH"` and cannot transact.


New cards start in `state: "PROCESSING"` while the card issuer
provisions the card. The `card.state_change` webhook fires on the
transition to `ACTIVE` (or to `CLOSED` with `stateReason:
provisions the card. Cards that require delegated signing authorization
move from `PENDING_AUTH` to `PROCESSING` after delegated-key creation is
complete. The `card.state_change` webhook fires on each state transition,
including the transition to `ACTIVE` (or to `CLOSED` with `stateReason:
"ISSUER_REJECTED"` if provisioning fails).
Comment thread
greptile-apps[bot] marked this conversation as resolved.
operationId: createCard
tags:
Expand All @@ -33,7 +42,12 @@ post:
- InternalAccount:019542f5-b3e7-1d02-0000-000000000002
responses:
'201':
description: Card issued successfully
description: >-
Card created successfully. Cards funded by an Embedded Wallet internal
account may be returned in `PENDING_AUTH` until delegated signing
authorization is completed with `POST /auth/delegated-keys`; otherwise
newly-created cards start in `PROCESSING` while the issuer provisions
them.
content:
application/json:
schema:
Expand Down
Loading