Document the 1-25 character merchant descriptor limit

[ls-bolt]

Summary

merchant.descriptor on the sandbox card-simulate endpoints must be 1–25 characters — the width of the card network's acceptor-name field (ISO 8583 DE43). The spec promised no limit, so integrators only discovered it as a 400 from a simulate call.

What changed

• CardMerchant.descriptor — describes the 1–25 character bound, scoped to the sandbox simulate endpoints where the field is supplied rather than reported.
• SandboxCardAuthorizationRequest — states the limit alongside the suffix table it already documents.
• POST /sandbox/cards/{id}/simulate/authorization — states the limit and that a longer descriptor is a 400 INVALID_INPUT.
• The sandbox-testing and quickstart card snippets carry the same rule, so the prose doesn't contradict the spec.
• Rebundled openapi.yaml and mintlify/openapi.yaml via make build.

CardMerchant is shared between requests and responses, and a descriptor reported back by a provider can exceed 25 characters — so this is a described bound on the simulate request rather than a maxLength on the shared schema, which would be a promise the read paths don't keep.

Testing

make build then make lint-openapi: 2 warnings, 14 explicitly-ignored problems — identical to the pre-change baseline, so no new lint findings.

Requested by @AaryamanBhute

[mintlify]

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

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Sep 12, 2026, 2:22 AM

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated
grid-flow-builder	Ignored	Preview	Sep 12, 2026 2:20am UTC
grid-wallet-demo	Ignored	Preview	Sep 12, 2026 2:20am UTC

[lightspark-bot]

• Document the 1-25 character merchant descriptor limit #958 👈 (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

docs(api): add character length requirement to merchant.descriptor parameter

go

docs(api): document merchant.descriptor length requirement in sandbox card simulate

kotlin

docs(api): document merchant.descriptor length requirement in cards simulate

openapi

docs(api): document merchant.descriptor length requirement in sandbox simulate endpoints

php

docs(api): add merchant.descriptor length requirement to sandbox cards simulate

python

docs(api): document merchant.descriptor length constraint in sandbox cards simulate

ruby

docs(api): add merchant.descriptor character length constraint to sandbox cards

typescript

docs(api): document merchant.descriptor length constraint in sandbox card authorization

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 "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-openapi studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗

✅ grid-ruby studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-go studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

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

✅ grid-python studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-php studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → lint ⏭️ → test ⏭️

✅ grid-cli studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
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-09-12 02:25:26 UTC

[ls-bolt]

@greptile review

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the documentation is consistently scoped and the generated contract outputs match their modular sources.

Summary

• Updates the shared merchant and sandbox authorization request descriptions.
• Adds the constraint to the authorization simulator documentation and Mintlify card guides.
• Keeps the root and Mintlify OpenAPI bundles synchronized with the modular source.

_{Reviews (1) · Last reviewed commit: "Document the 1-25 character merchant des..."}