docs(openapi): split Card processorRef (Lithic) from issuerRef (Lead)

[benwgold]

Summary

Companion docs change to the card-id standardization (webdev#29318).

• Adds processorRef to the Card schema — the Lithic card token, parallel to CardTransaction.issuerTransactionToken. This is the field the implementation now returns alongside the Card:<uuid> id (the spec's id was already Card:<uuid>; the implementation was the side that diverged).
• Corrects issuerRef: its example was a Lithic token (lithic_card_...), but Lithic is the card processor — the issuer of record is Lead Bank. issuerRef now describes the Lead identifier; the Lithic ref lives in processorRef. This matches the data model (processor_ref = Lithic, issuer_ref = Lead).

Test plan

• make build (rebundles openapi.yaml + mintlify/openapi.yaml)
• make lint-openapi → exit 0 (no new findings on the Card schema)

Proof-of-concept companion to the implementation PR; leaving as a draft.

Slack thread: https://lightsparkgroup.slack.com/archives/D0AJJH3A4J1/p1782347206097239

---

🤖 sovereign-reactor-4(#4) | Feedback

Original PR: #619

[akanter]

• docs(openapi): split Card processorRef (Lithic) from issuerRef (Lead) #620 👈 (View in Graphite)
• main

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

[github-actions]

✱ 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

csharp

feat(api): add processor_ref field, update issuer_ref docs in card

go

feat(api): add processorRef field to card model

kotlin

feat(api): add processorRef field to Card model

openapi

feat(api): add processorRef field to Card model

php

feat(api): add processorRef field to Card model

python

feat(api): add processor_ref field to card model

ruby

feat(api): add processor_ref field to card model

typescript

feat(api): add processorRef field to cards

✅ grid-typescriptstudio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/83719ecf4bd54561b2ee7455d94489529c345cb2/dist.tar.gz

⚠️grid-openapistudio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️

✅ grid-rubystudio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️grid-gostudio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@cf48207bec1bf0192905d072310174debfe19ee7

⚠️grid-kotlinstudio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ✅ → test ❗

⚠️grid-pythonstudio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/86037b1b43ab183e2dd5ae19072799358fd41181/grid-0.0.1-py3-none-any.whl

⚠️grid-csharpstudio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ✅ → test ❗

✅ grid-phpstudio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → lint ✅ → test ✅

⚠️grid-clistudio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ❗

---

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-06-27 01:09:03 UTC

[greptile-apps]

Greptile Summary

This PR corrects the processor-vs-issuer terminology in the Card OpenAPI schema: issuerRef now correctly describes the Lead Bank identifier, a new processorRef field is added for the Lithic card token (adjacent to issuerRef), and the panEmbedUrl description is updated from "card issuer's iframe" to "card processor's iframe".

• processorRef added — new readOnly string field for the Lithic card token, placed immediately before issuerRef so the processor/issuer pair reads together.
• issuerRef corrected — description and example updated to reflect Lead Bank as the issuer of record; old Lithic example value removed.
• Webhook + bundled files synced — card-state-change.yamlactivated example and both openapi.yaml / mintlify/openapi.yaml bundles are updated consistently.

Confidence Score: 5/5

Purely additive docs change — adds a new readOnly field and corrects descriptions; no logic, auth, or data-path changes.

All four changed files are OpenAPI schema and webhook documentation. The new processorRef field is additive and readOnly, the description fixes are accurate, and the bundled outputs match the source. No breaking changes to existing fields.

No files require special attention. The one open nit is the pre-existing omission of processorRef/issuerRef from the frozen webhook example.

Important Files Changed

Filename	Overview
openapi/components/schemas/cards/Card.yaml	Adds processorRef (Lithic token) immediately before issuerRef (Lead Bank id); corrects panEmbedUrl description from "issuer" to "processor"; updates issuerRef description and example to reflect Lead Bank.
openapi/webhooks/card-state-change.yaml	Updates the activated example to include processorRef: card_b81c2a4f and corrected issuerRef: lead_card_7a1b9c3d; frozen and issuerRejected examples are unchanged (pre-existing omission of ref fields).
openapi.yaml	Bundled output file — identical changes to the source Card schema and webhook, generated by make build.
mintlify/openapi.yaml	Mintlify-specific bundled output — same schema and webhook changes as openapi.yaml, in sync with the source.

Entity Relationship Diagram

%%{init: {'theme': 'neutral'}}%%
erDiagram
Card {
string id "Card:uuid"
string platformCardId "platform-assigned opaque id"
string processorRef "Lithic card token (NEW)"
string issuerRef "Lead Bank card identifier (corrected)"
string panEmbedUrl "Lithic embed URL (description fixed)"
string currency
string state
}
CardTransaction {
string id
string issuerTransactionToken "parallel to processorRef on Card"
}
Card ||--o{ CardTransaction : "has"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
erDiagram
Card {
string id "Card:uuid"
string platformCardId "platform-assigned opaque id"
string processorRef "Lithic card token (NEW)"
string issuerRef "Lead Bank card identifier (corrected)"
string panEmbedUrl "Lithic embed URL (description fixed)"
string currency
string state
}
CardTransaction {
string id
string issuerTransactionToken "parallel to processorRef on Card"
}
Card ||--o{ CardTransaction : "has"

Loading

_{Reviews (3): Last reviewed commit: "docs(openapi): address Greptile — group ..." | Re-trigger Greptile}

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jun 25, 2026 9:32pm
grid-wallet-demo	Ignored	Preview	Jun 25, 2026 9:32pm

[ls-bolt]

Addressed Greptile review

• Field adjacency — processorRef now sits immediately before issuerRef, so the processor-vs-issuer pair is visible together in the schema.
• panEmbedUrl wording — changed "card issuer's iframe" → "card processor's iframe" (it's a Lithic / embed.lithic.com endpoint).
• Bonus consistency fix — the card-state-change webhook example still showed the stale issuerRef: lithic_card_…; it now shows processorRef (Lithic) + issuerRef (Lead).

make build + make lint-openapi clean. @greptile-apps please re-review.