feat(cards): add PIN management APIs and status webhooks by DhruvPareek · Pull Request #897 · lightsparkdev/grid-api

DhruvPareek · 2026-09-04T00:43:33Z

Reason

Platforms need to let cardholders choose or replace a PIN, recover a blocked PIN, and receive status changes. Platforms configure the website hosting the PIN iframe once, then request a temporary URL without repeating that setting.

Overview

Add three online-PIN operations: encrypted set/change (POST /cards/{id}/set-pin), hosted PIN-entry URL retrieval (GET /cards/{id}/set-pin-url), and unblock (POST /cards/{id}/pin/unblock). Read pinStatus from GET /cards/{id}. Offline PIN cards and PIN reveal are unsupported.

Configure cardConfigs.pinTargetOrigin using PATCH /platform/config. The value is a canonical HTTPS origin shared by all user-specific paths on that website. Omission preserves it; null clears it. GET URL requests take no body or origin parameter and return 409 CONFLICT if the setting is absent. Changes to the setting apply to newly requested URLs.

Each URL request creates a fresh temporary PIN-entry session and returns CardPinUrlResponse: iframeUrl, sessionToken, expiresAt, and environment. The URL permits one successful PIN submission. Responses specify Cache-Control: no-store; the operation requires card-management permission and an attributable audit actor. Fetching the URL does not change the PIN. The obsolete POST session operation and its request schema are removed.

The guide covers platform configuration, loading the iframe, submitting a PIN, and confirming the result. Custom PIN entry requires client-side encryption of the complete nonce/PIN payload with the downloadable public key. An OK status alone cannot confirm replacement of an existing PIN.

Card.pinStatus is the last observed status, present from issuance when PIN management is supported and absent when unsupported. CARD.PIN_STATUS_CHANGE carries the updated Card after an observed status change. Initial issuance and replacements that leave the status OK do not emit an event. The webhook guide covers signature verification, event deduplication, and out-of-order handling. No PIN material or session credentials are included in notifications.

The implementation stack is webdev #34392 (regeneration), #34393 (handlers), #34394 (Ops UI), and #36190 (platform notifications). This GET/platform-configuration revision updates only the Grid API contract and docs. Corresponding webdev regeneration, configuration persistence, handler, and caller changes are deferred; the webdev PRs have not been updated for this contract. Incoming PIN updates also depend on the Lithic webhook subscription.

Test Plan

make build and make lint: pass; Spectral reports 0 errors. Its broad pagination rule adds a warning for the single-object GET URL response, alongside existing warnings.
mint openapi-check mintlify/openapi.yaml: pass.
Checked that the GET operation has no request body, exposes the no-store response header, and returns the renamed response schema; the old POST session operation and schemas are absent.
Checked that both platform configuration schemas reference the updated CardConfig, null is allowed, the origin example matches the pattern, valid origins pass, and HTTP URLs, paths, queries, fragments, credentials, whitespace, and backslashes fail the pattern.
Verified the root and Mintlify OpenAPI bundles are identical, stale session-endpoint references are absent, and git diff --check passes.
No backend or live iframe validation for this contract revision; webdev changes are deferred.

vercel · 2026-09-04T00:43:36Z

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

Project	Deployment	Actions	Updated
grid-statements-demo	Error		Sep 25, 2026 5:06pm UTC

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Sep 25, 2026 5:06pm UTC
grid-flow-builder	Ignored	Preview	Sep 25, 2026 5:06pm UTC
grid-wallet-demo	Ignored	Preview	Sep 25, 2026 5:06pm UTC

mintlify · 2026-09-04T00:43:37Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Sep 25, 2026, 5:06 PM

DhruvPareek · 2026-09-04T00:43:46Z

feat(cards): add PIN management APIs and status webhooks #897 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

github-actions · 2026-09-04T00:44:25Z

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

go

feat(api): add pinStatus field to Card and webhook event responses

kotlin

feat(api): add pinStatus field to Card model

openapi

feat(api): add PIN management methods (set/session/unblock) and pinStatus field to cards

php

feat(api): add pinStatus field to Card model

python

feat(api): add pin_status field to Card

ruby

feat(api): add pin_status field to Card model

typescript

feat(api): add pinStatus field to Card response

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-typescript studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

New diagnostics (4 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/session`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/unblock`

✅ grid-openapi studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗

New diagnostics (4 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/session`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/unblock`

✅ grid-kotlin studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ⏭️ (prev: test ❗)

New diagnostics (4 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/session`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/unblock`

✅ grid-ruby studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

New diagnostics (4 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/session`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/unblock`

✅ grid-go studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️
go get github.com/stainless-sdks/grid-go@029033a1e06e66bd4e9d620077088797fbe86b4a
New diagnostics (4 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/session`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/unblock`

✅ grid-python studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

New diagnostics (4 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/session`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/unblock`

✅ grid-php studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → lint ⏭️ → test ⏭️

New diagnostics (4 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/session`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/unblock`

✅ grid-cli studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

New diagnostics (4 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/session`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /cards/{id}/pin/unblock`

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-09-22 22:42:54 UTC

greptile-apps · 2026-09-22T21:57:35Z

Confidence Score: 4/5

The API contract appears functionally safe, but the explicit Mintlify procedure requirement should be satisfied before merging and the session-origin schema should be tightened.

Findings

Origin Constraint Is Too Broad ▶
Hosted Flow Lacks Steps ▶

Fix with agent prompt

### Issue 1
openapi/components/schemas/cards/CardPinSessionRequest.yaml:7
`format: uri` accepts values such as `http://app.example.com` and `https://app.example.com/path`, even though the endpoint only accepts a canonical HTTPS origin. Generated validators may therefore approve requests that the server rejects with `400 INVALID_INPUT`. Add schema constraints for the HTTPS, origin-only requirement.

### Issue 2
mintlify/cards/card-management/pins.mdx:12-14
The hosted PIN setup presents SDK initialization, session creation, control mounting, submission, and result verification as prose. The repository's Mintlify writing guide requires complex procedures to use numbered steps and provide expected outcomes. Restructure this flow so readers can follow the required order and confirm success; this repository requirement must be satisfied before merging.

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!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR adds the public contract and integration documentation for setting, hosting, reading, and unblocking card PINs.

Registers four PIN operations and their request, response, and status schemas.
Adds optional last-observed PIN status to the card resource.
Adds a cardholder integration guide and navigation entry.
Keeps the modular specification and both generated bundles synchronized.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Client[Authenticated platform backend] --> Choice{PIN entry flow}
  Choice -->|Hosted| Session[POST /cards/id/pin/session]
  Session --> SDK[Lithic hosted PIN control]
  Choice -->|Client encrypted| Set[POST /cards/id/pin]
  SDK --> Status[GET /cards/id/pin]
  Set --> Status
  Status -->|BLOCKED, retain PIN| Unblock[POST /cards/id/pin/unblock]
  Status -->|BLOCKED or forgotten, replace PIN| Choice

_{Reviews (1) · Last reviewed commit: "feat(cards): add PIN management endpoint..."}

shreyav · 2026-09-23T22:34:49Z

@@ -0,0 +1,135 @@
+parameters:


do we need this? seems like get card already gives you the pin

get card only gives you the pin status, like if the pin was configured, not configured, or blocked

oh sry i meant the get below. seems like it only has the status

Oh yea get pin here is redundant with the existing get card. I can remove it, i'm just curious if it is something where it would seem confusing to an integrator that they cant do GET /cards/{id}/pin when we have an existing POST /cards/{id}/pin?

If i'm wrong about that, i can def remove GET /cards/{id}/pin

i dont think we need it but maybe @pengying has some thoughts. should we also emit some webhooks on these status changes?

For chaning a pin to OK or NOT_SET I don't think we need webhooks because the platform itself is making API calls to get the PIN to that state. For BLOCKED i can add follow up PRs for the webhook

ls-bolt · 2026-09-23T22:35:15Z

🦣 Congratulations @shreyav - your substantive review earned a Argentavis! (rare)

With a wingspan around seven meters, it was among the largest flying birds ever known.

View your Frost-dex: https://zeus.dev.dev.sparkinfra.net/#/dinodex/shreyav?section=ice-age

shreyav · 2026-09-23T22:36:03Z

+description: |
+  State of the card's PIN. On the Card resource, this is the last known status
+  and is present whenever PIN management is supported. An absent value means
+  PIN management is unavailable for this card; it does not mean `NOT_SET`.


should this be a card capability

that sentence is just there because Striga cards operate differently with PINs so this is just an absent value / null for striga cards

just wanted to clarify the difference between null and NOT_SET

shreyav · 2026-09-23T22:38:53Z

@@ -0,0 +1,15 @@
+type: object


what happens if you call create session twice? should the session resource have an id?

wait one sec, turns out Ben implemented card reveal iframes using their old flow which doesnt use sessions

but why do you think a session id would be necessary? sessions are short lived and not really like an object that would be used later on or need to be referred to

the question underneath is what happens to session 1 when you create session 2. because the status, and the unblock api are scoped to the card and not the session

that's a lithic thing but they aren't explicit in their docs about it, it does Look like either session can still update the card though

so it shouldnt matter

Yea highly confident either can update the PIN still

Adds three card PIN endpoints and a pinStatus field on the Card resource. - POST /cards/{id}/pin takes a PIN block the client encrypted for the card processor. Grid forwards it verbatim and never sees the PIN. - POST /cards/{id}/pin/session mints a short-lived session token for the processor's hosted PIN-entry iframe, for platforms without their own PIN UI. The processor returns a token rather than a URL, so the response carries the token and the client's embed SDK builds the iframe from it. - POST /cards/{id}/pin/unblock clears a PIN blocked by three consecutive incorrect entries, without changing it. - Card.pinStatus reports NOT_SET / OK / BLOCKED, and is absent on cards whose processor does not offer PIN management. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GsstRe1f8aoPXm1kYQw2Vm

ls-bolt · 2026-09-24T23:54:05Z

🦣 Congratulations @pengying - your substantive review earned a Metailurus! (common)

Its canines were intermediate between the conical teeth of cats and true sabers.

View your Frost-dex: https://zeus.dev.dev.sparkinfra.net/#/dinodex/pengying?section=ice-age

pengying · 2026-09-24T23:55:40Z

+required:
+  - targetOrigin
+properties:
+  targetOrigin:


can we make this on the platform config instead of each set pin request? And then we can make pin url a get.

wdym by "make pin url a get." ?

POST /cards/{id}/pin/session
{
"targetOrigin": "https://app.example.com"
}

becomes

GET /cards/{id}/set-pin-link

DhruvPareek · 2026-09-25T19:21:24Z

Merge activity

Sep 25, 7:21 PM UTC: A user started a stack merge that includes this pull request via Graphite.
Sep 25, 7:21 PM UTC: @DhruvPareek merged this pull request with Graphite.

mintlify Bot deployed to staging - mintlify September 4, 2026 00:45 View deployment

DhruvPareek force-pushed the dp/card-pin-management branch from 2c2098d to 8a85f10 Compare September 4, 2026 00:54

mintlify Bot deployed to staging - mintlify September 4, 2026 00:55 View deployment

DhruvPareek force-pushed the dp/card-pin-management branch from 8a85f10 to e64c7ef Compare September 21, 2026 23:54

vercel Bot had a problem deploying to Preview – grid-statements-demo September 21, 2026 23:54 Failure

mintlify Bot deployed to staging - mintlify September 21, 2026 23:55 View deployment

DhruvPareek marked this pull request as ready for review September 22, 2026 21:54

greptile-apps Bot reviewed Sep 22, 2026

View reviewed changes

Comment thread openapi/components/schemas/cards/CardPinSessionRequest.yaml Outdated

Comment thread mintlify/cards/card-management/pins.mdx Outdated

DhruvPareek force-pushed the dp/card-pin-management branch from e64c7ef to b5d5e50 Compare September 22, 2026 21:59

github-actions Bot added the breaking-change Introduces a breaking change to the OpenAPI spec label Sep 22, 2026

mintlify Bot deployed to staging - mintlify September 22, 2026 22:00 View deployment

DhruvPareek force-pushed the dp/card-pin-management branch from b5d5e50 to dba77ee Compare September 22, 2026 22:17

mintlify Bot deployed to staging - mintlify September 22, 2026 22:18 View deployment

DhruvPareek force-pushed the dp/card-pin-management branch from dba77ee to 63e02dd Compare September 22, 2026 22:27

mintlify Bot deployed to staging - mintlify September 22, 2026 22:28 View deployment

DhruvPareek force-pushed the dp/card-pin-management branch from 63e02dd to d1d5ef9 Compare September 22, 2026 22:39

mintlify Bot deployed to staging - mintlify September 22, 2026 22:40 View deployment

DhruvPareek force-pushed the dp/card-pin-management branch from d1d5ef9 to b414afd Compare September 23, 2026 21:05

mintlify Bot deployed to staging - mintlify September 23, 2026 21:06 View deployment

shreyav reviewed Sep 23, 2026

View reviewed changes

DhruvPareek changed the title ~~feat(cards): add PIN management endpoints~~ feat(cards): add PIN management APIs and status webhooks Sep 24, 2026

DhruvPareek force-pushed the dp/card-pin-management branch from b414afd to ea631b8 Compare September 24, 2026 18:36

mintlify Bot deployed to staging - mintlify September 24, 2026 18:37 View deployment

DhruvPareek force-pushed the dp/card-pin-management branch 2 times, most recently from ea631b8 to ef03da1 Compare September 24, 2026 18:59

mintlify Bot deployed to staging - mintlify September 24, 2026 19:00 View deployment

DhruvPareek force-pushed the dp/card-pin-management branch from ef03da1 to 6d7ba06 Compare September 24, 2026 23:14

github-actions Bot removed the breaking-change Introduces a breaking change to the OpenAPI spec label Sep 24, 2026

mintlify Bot deployed to staging - mintlify September 24, 2026 23:15 View deployment

fix(ci): remove unused global Mintlify installation

daac752

pengying reviewed Sep 24, 2026

View reviewed changes

Comment thread openapi/paths/cards/cards_{id}_set_pin.yaml

pengying reviewed Sep 24, 2026

View reviewed changes

pengying reviewed Sep 25, 2026

View reviewed changes

Comment thread openapi/openapi.yaml Outdated

pengying reviewed Sep 25, 2026

View reviewed changes

Comment thread openapi/openapi.yaml Outdated

refactor(cards): name the PIN-setting endpoint set-pin

fe68936

mintlify Bot deployed to staging - mintlify September 25, 2026 00:17 View deployment

DhruvPareek added 2 commits September 25, 2026 09:54

chore: restore the existing Mintlify CI install step

6d6d379

feat(cards): get PIN-entry URLs using platform configuration

556e6ed

mintlify Bot deployed to staging - mintlify September 25, 2026 17:06 View deployment

DhruvPareek requested review from pengying and shreyav September 25, 2026 17:14

pengying approved these changes Sep 25, 2026

View reviewed changes

DhruvPareek merged commit bf17b3f into main Sep 25, 2026
10 checks passed

DhruvPareek deleted the dp/card-pin-management branch September 25, 2026 19:21

DhruvPareek mentioned this pull request Sep 25, 2026

docs(cards): correct the platform configuration endpoint path #1077

Merged

Conversation

DhruvPareek commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reason

Overview

Test Plan

Uh oh!

vercel Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlify Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DhruvPareek commented Sep 4, 2026

Uh oh!

github-actions Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds for grid

Uh oh!

greptile-apps Bot commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Summary

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ls-bolt Bot commented Sep 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ls-bolt Bot commented Sep 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DhruvPareek commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

DhruvPareek commented Sep 4, 2026 •

edited

Loading

vercel Bot commented Sep 4, 2026 •

edited

Loading

mintlify Bot commented Sep 4, 2026 •

edited

Loading

github-actions Bot commented Sep 4, 2026 •

edited

Loading

greptile-apps Bot commented Sep 22, 2026 •

edited

Loading

DhruvPareek commented Sep 25, 2026 •

edited

Loading