Skip to content

docs(cards): clarify currency and units for USDB-funded cards #1037

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
Sep 18, 2026
+36 −25
Merged

docs(cards): clarify currency and units for USDB-funded cards #1037

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: 4 additions & 4 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.

15 changes: 9 additions & 6 deletions mintlify/snippets/cards/funding-sources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,10 @@ The internal account must:
- Belong to the customer.
- Be denominated in a card-eligible currency.

The card's `currency` is derived from the funding source at issue time. If the
account does not qualify, Grid rejects the request with `400 INVALID_INPUT`.
The card program fixes the card's `currency` at issuance. USDB-funded cards
transact in USD, with funding converted at 1 USDB = 1 USD. Their spending
limits are in USD cents. If the account does not qualify, Grid rejects the
request with `400 INVALID_INPUT`.

If the funding source is an `EMBEDDED_WALLET` account, the cardholder must
also authorize a delegated signing key before the card can fund a
Expand All @@ -44,9 +46,10 @@ curl -X PATCH "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010" \
}'
```

The replacement account must belong to the customer and be denominated in the
card's currency. The response returns the updated `Card` resource. Changing
`fundingSource` does not fire a webhook.
The replacement account must belong to the customer and use a currency
supported by the card's program, including USDB for USD cards. The response
returns the updated `Card` resource. Changing `fundingSource` does not change
the card's currency or spending-limit units, and does not fire a webhook.

You cannot supply `fundingSource` alongside `status: CLOSED`. To stop a card
from spending, set `status: FROZEN` instead.
Expand All @@ -55,7 +58,7 @@ from spending, set `status: FROZEN` instead.

| Status | Code | What it means |
|--------|------|---------------|
| 400 | `INVALID_INPUT` | The account does not belong to the customer, or is not denominated in a card-eligible currency at creation or the card's currency when replaced. Also returned when `fundingSource` is supplied alongside `status: CLOSED`, or another request field is invalid. |
| 400 | `INVALID_INPUT` | The account does not belong to the customer, or its currency is not supported by the card program. Also returned when `fundingSource` is supplied alongside `status: CLOSED`, or another request field is invalid. |
| 409 | `CARD_NOT_MUTABLE` | The card is `CLOSED`. |

## Stop a card from spending
Expand Down
8 changes: 6 additions & 2 deletions mintlify/snippets/cards/issuing-cards.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,12 @@ curl -X POST "$GRID_BASE_URL/cards" \
| `maxSpendPerDay` | No | Cumulative new spend allowed per UTC calendar day, in the smallest unit of the card's currency. Refunds, reversals, and expiries do not restore capacity that day. |
| `maxTransactionsPerDay` | No | Number of transactions the card may authorize per UTC calendar day. Each approved authorization counts once; reversals and expiries do not restore capacity that day. |

The card's `currency` is derived from the funding source at issue time
and surfaces on the returned `Card` resource.
The card program fixes the card's `currency` at issuance and returns it on
the `Card` resource. USDB-funded cards have `currency: "USD"`, with funding
converted at 1 USDB = 1 USD. Spending limits use the smallest unit of the
card's currency: for a USDB-funded card, `50000` means $500.00 in USD cents.
Changing the funding source does not change the card's currency or
spending-limit units.

## The lifecycle

Expand Down
8 changes: 4 additions & 4 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.

7 changes: 5 additions & 2 deletions openapi/components/schemas/cards/Card.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,11 @@ properties:
currency:
type: string
description: >-
Currency the card transacts in (ISO 4217 for fiat, tickers for crypto).
Derived from the funding source at issue time.
Currency the card transacts in, fixed at issuance by its card program.
USDB-funded cards transact in USD, with funding converted at
1 USDB = 1 USD. Spending limits use the smallest unit of the card's
currency (USD cents for USDB-funded cards). Changing the funding source
does not change the card's currency or spending-limit units.
example: USD
processorRef:
type: string
Expand Down
4 changes: 2 additions & 2 deletions openapi/components/schemas/cards/CardCreateRequest.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,8 @@ properties:
maximum: 9007199254740991
description: >-
Optional card-specific cap on cumulative new spend during one UTC
calendar day, in the smallest unit of the card currency derived from its
funding source. Omit this field for no card-specific daily cap. When the
calendar day, in the smallest unit of the card's currency (USD cents for
USDB-funded cards). Omit this field for no card-specific daily cap. When the
platform config also supplies `cardConfigs.maxSpendPerDay`, Grid enforces
the lower of the two values. The window resets at 00:00 UTC, and refunds,
reversals, and authorization expiries do not restore capacity during the
Expand Down
7 changes: 4 additions & 3 deletions openapi/components/schemas/cards/CardUpdateRequest.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,10 @@ properties:
type: string
description: >-
Replaces the card's funding source. Must belong to the customer and be
denominated in the card's currency. Cannot be supplied alongside
`status: CLOSED`. To stop a card from spending, set `status: FROZEN`
instead.
denominated in a currency supported by the card's program, including
USDB for USD cards. Changing the funding source does not change the
card's currency or spending-limit units. Cannot be supplied alongside
`status: CLOSED`. To stop a card from spending, set `status: FROZEN` instead.
example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002
maxSpendPerTransaction:
anyOf:
Expand Down
4 changes: 2 additions & 2 deletions openapi/paths/cards/cards_{id}.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,8 +204,8 @@ patch:
'400':
description: >-
Bad request. Returned with `INVALID_INPUT` when a supplied funding
source does not belong to the cardholder or is not denominated in the
card's currency, when `fundingSource` is combined with any `status`
source does not belong to the cardholder or uses a currency unsupported
by the card program, when `fundingSource` is combined with any `status`
Comment on lines 206 to +208

@greptile-apps greptile-apps Bot Sep 18, 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 Conflicting funding currency requirements

The updated error description allows a funding source whose currency is supported by the card program, and the request schema explicitly allows USDB funding for USD cards. However, this operation's main description still requires the source to use the card's currency. For a USD card funded by USDB, callers are incorrectly told that a valid replacement must use USD, leaving the public PATCH contract contradictory. Update the operation description at lines 66–68 to use the same program-supported currency rule.

Knowledge Base Used: Cards API

Prompt To Fix With AI 
This is a comment left during a code review.
Path: openapi/paths/cards/cards_{id}.yaml
Line: 206-208

Comment:
**Conflicting funding currency requirements**

The updated error description allows a funding source whose currency is supported by the card program, and the request schema explicitly allows USDB funding for USD cards. However, this operation's main description still requires the source to use the card's currency. For a USD card funded by USDB, callers are incorrectly told that a valid replacement must use USD, leaving the public PATCH contract contradictory. Update the operation description at lines 66–68 to use the same program-supported currency rule.

**Knowledge Base Used:** [Cards API](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/cards-api.md)

---

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

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!

change on a card program where the card issuer makes authorization
decisions, when `status` is supplied without `substatus` or without a
non-empty `reason`, and for general invalid parameters.
Expand Down
Loading