From 2eb6cd594809ec8f7d9e8d481dd32fe17aab53bd Mon Sep 17 00:00:00 2001 From: Dhruv Pareek Date: Tue, 16 Jun 2026 15:40:40 -0700 Subject: [PATCH] docs(openapi): document card pending auth state Add PENDING_AUTH to CardState and explain how cards funded by Embedded Wallet internal accounts remain pending until delegated signing authorization is completed via POST /auth/delegated-keys. --- mintlify/openapi.yaml | 8 ++++++-- openapi.yaml | 8 ++++++-- .../components/schemas/cards/CardState.yaml | 2 ++ openapi/paths/cards/cards.yaml | 20 ++++++++++++++++--- 4 files changed, 31 insertions(+), 7 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 14036ae6..52d99adf 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -6838,7 +6838,9 @@ paths: description: | Issue a new card for a cardholder. Every card must be bound to at least one funding source at create time. The cardholder must have KYC status `APPROVED` before a card can be issued; otherwise the request is rejected with `CARDHOLDER_KYC_NOT_APPROVED`. - 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: "ISSUER_REJECTED"` if provisioning fails). + 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. 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). operationId: createCard tags: - Cards @@ -6861,7 +6863,7 @@ paths: - 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: @@ -19246,6 +19248,7 @@ components: type: string enum: - PENDING_KYC + - PENDING_AUTH - PROCESSING - ACTIVE - FROZEN @@ -19256,6 +19259,7 @@ components: | 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. | diff --git a/openapi.yaml b/openapi.yaml index 14036ae6..52d99adf 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -6838,7 +6838,9 @@ paths: description: | Issue a new card for a cardholder. Every card must be bound to at least one funding source at create time. The cardholder must have KYC status `APPROVED` before a card can be issued; otherwise the request is rejected with `CARDHOLDER_KYC_NOT_APPROVED`. - 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: "ISSUER_REJECTED"` if provisioning fails). + 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. 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). operationId: createCard tags: - Cards @@ -6861,7 +6863,7 @@ paths: - 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: @@ -19246,6 +19248,7 @@ components: type: string enum: - PENDING_KYC + - PENDING_AUTH - PROCESSING - ACTIVE - FROZEN @@ -19256,6 +19259,7 @@ components: | 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. | diff --git a/openapi/components/schemas/cards/CardState.yaml b/openapi/components/schemas/cards/CardState.yaml index 04c17862..85d8b692 100644 --- a/openapi/components/schemas/cards/CardState.yaml +++ b/openapi/components/schemas/cards/CardState.yaml @@ -1,6 +1,7 @@ type: string enum: - PENDING_KYC + - PENDING_AUTH - PROCESSING - ACTIVE - FROZEN @@ -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. | diff --git a/openapi/paths/cards/cards.yaml b/openapi/paths/cards/cards.yaml index 4813781d..45dfa24d 100644 --- a/openapi/paths/cards/cards.yaml +++ b/openapi/paths/cards/cards.yaml @@ -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). operationId: createCard tags: @@ -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: