docs(payments): add merchant logo specification for Merchant API#44
Open
riveign wants to merge 4 commits into
Open
docs(payments): add merchant logo specification for Merchant API#44riveign wants to merge 4 commits into
riveign wants to merge 4 commits into
Conversation
New page at payments/merchant-api/logo-specification.mdx documenting dimensions, aspect ratio, formats, file size, and the 400 error codes returned on server-side validation of the iconUrl field on POST/PATCH /v1/merchants. Adds a Merchant API group to the Payments tab in both versions of docs.json (2026-02-18 + 2026-02-19.preview). WCPM-378
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
- Remove the validation section and 400 error code table — server-side validation has not shipped yet, so documenting the codes prematurely would mislead partners. - Reframe the page as a guide: add a "Where the logo appears" section covering the wallet payment sheet, confirmation screens, and transaction history surfaces where the logo renders. - Keep the spec table, format guidance, and "why square" rationale. - Replace the dual valid/400 worked example with a single valid create-merchant example plus a note on the CDN import behaviour (logo is imported into Cloudflare Images; updating the source URL does not re-render until PATCH is called). WCPM-378
…copy
- Add two reference screenshots under "Where the logo appears":
- images/payments/merchant-logo/wallet-payment-sheet.png — wallet
payment sheet with merchant logo as the visual anchor.
- images/payments/merchant-logo/buyer-checkout.png — WalletConnect
Pay buyer checkout page with the logo above the "Pay X to
<Merchant>" headline.
- Split the section into "Wallet payment sheet" and "Buyer checkout"
subsections, each with an italic "Reference image" caption.
- Drop the inaccurate "Transaction history" bullet — the logo is not
currently surfaced in wallet transaction history.
- Drop the Cloudflare Images implementation detail from the intro and
the worked-example closing paragraph. Keep the operationally-useful
point that PATCH is required to change the rendered logo.
WCPM-378
…, constrain image sizes - Replace wallet screenshot with the latest export. - Rename "Wallet payment sheet" → "Wallet payment screen" (heading, body copy, alt text) and the corresponding image file to match. - Add max-width to both reference images so they render at sensible sizes (wallet 320 px, buyer checkout 640 px) instead of full content-width. WCPM-378
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new guide documenting the merchant logo specification for the WalletConnect Pay Merchant API. Partners using
POST /v1/merchantsandPATCH /v1/merchants/{merchantId}now have a documented spec for theiconUrlfield — recommended dimensions, aspect ratio, accepted formats, and file size — alongside context on where the logo actually renders in the buyer experience.payments/merchant-api/logo-specification.mdx2026-02-18(stable) and2026-02-19.previewversions ofdocs.jsonLinear: WCPM-378
Scope
Scope limited to Merchant API docs. Point-of-Sale SDK pages (Flutter, Kotlin, point-of-sale, wallet-implementation) are untouched — the
logoIconfield there is dApp/wallet metadata for WalletConnect pairing, which is a different concept from the WCP merchant logo stored via the Merchant API.Validation rules are intentionally not documented yet. Server-side validation of dimensions/format is not shipping in this iteration. The page describes the recommended specification only — documenting 400 codes before the server enforces them would mislead partners. A follow-up will add a validation section once the server-side checks land in
pay-merchant-experience.Follow-ups
iconUrlfield description at/api-reference/2026-02-18/post-v1-merchants#body-icon-url-one-of-0does not yet link to this guide. The fix belongs upstream in the MX OpenAPI source (pay-merchant-experience) —api/2026-02-18.jsonin this repo is regenerated byscripts/generate-specs.mjsfrom the upstream services, so any manual edit to the description here would be wiped on the next run. Will be filed as an engineering ticket againstpay-merchant-experienceto update theiconUrlfield description with a reference to/payments/merchant-api/logo-specification.pay-merchant-experience.Verification
mint broken-links→ success, no broken linksmint dev→ new page renders at/payments/merchant-api/logo-specificationwith all sections in the right orderTest plan
/api-reference/2026-02-18/post-v1-merchantsand/api-reference/2026-02-18/patch-v1-merchants-merchantidresolve🤖 Generated with Claude Code