docs(payments): sync quote/transfer/webhook examples with schema

[jklein24]

Comprehensive sync of payments documentation examples with the current OpenAPI schema.

Changes

Quote responses:

• Use id (not quoteId).
• Flat totalSendingAmount / totalReceivingAmount / feesIncluded integers + separate sendingCurrency / receivingCurrency Currency objects (was nested sendingAmount / receivingAmount CurrencyAmount objects).
• Required sourceType / destinationType discriminators added.
• Removed invented currency field from source / destination.
• Quote-execute response is a Quote, not a transaction with invented executedAt.

Webhooks:

• Envelope: {id, type, timestamp, data} per BaseWebhook (was {webhookId, transaction, ...}).
• Event types use OBJECT.EVENT dot-notation (OUTGOING_PAYMENT.COMPLETED, INCOMING_PAYMENT.PENDING, etc.).

Receivers / UMA:

• global-p2p/sending-receiving-payments/receiving-payments.mdx migrated from User* → Customer* vocabulary (userId → customerId, etc.).
• UMA lookup endpoint corrected to /receiver/uma/{address}?customerId=...; response matches ReceiverUmaLookupResponse.

Other:

• currencies-and-rails.mdx: MXN decimals: 8 → 2; reconciled prose math.
• Idempotency-Key shown as HTTP header (not body field).
• fiat-crypto-conversion.mdx: fixed broken JSON; receivingAmount → totalReceivingAmount.

Sibling PRs

Split from a larger sync effort. Two companion draft PRs cover onboarding (#502) and accounts/auth/cards.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 25, 2026 1:47pm

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	May 25, 2026, 8:39 AM

[jklein24]

@greptile review

[greptile-apps]

Greptile Summary

This PR comprehensively syncs payment documentation examples across 20 MDX files to match the current OpenAPI schema, covering quote responses, webhook envelope structure, and receiver/UMA vocabulary changes.

• Quote schema: quoteId → id, nested sendingAmount/receivingAmount objects flattened to totalSendingAmount/totalReceivingAmount integers + separate sendingCurrency/receivingCurrency objects; source/destination discriminators (sourceType/destinationType) added; feesIncluded replaces fee; execute response correctly returns a Quote (not a transaction).
• Webhook envelope: {webhookId, transaction, type, timestamp} → {id, type, timestamp, data} across all event types; event type migrated to dot-notation (OUTGOING_PAYMENT.COMPLETED, INCOMING_PAYMENT.PENDING, etc.); idempotency-key snippets updated to reference id from the new envelope.
• Receivers / UMA / other: User* → Customer* vocabulary throughout receiving-payments.mdx; UMA lookup endpoint corrected to /receiver/uma/{address}?customerId=…; currencies-and-rails.mdx corrects MXN decimals and amount magnitudes; Idempotency-Key shown as HTTP header.

Confidence Score: 4/5

The documentation sync is broad and mostly accurate; a handful of open issues from a prior review pass remain unresolved and will continue to mislead developers copying those examples.

The PR fixes dozens of schema drift issues correctly and consistently across 20 files. Several specific problems flagged in the preceding review wave — the REALTIME_FUNDING currency field left in some files but removed from others, USDC documented with decimals: 2 in cross-currency flows despite real-world 6-decimal precision, and missing sourceType/destinationType discriminators in the transaction-lifecycle guide — are still present in this diff.

mintlify/snippets/sending/cross-currency.mdx (USDC decimal inconsistency), mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx (missing discriminators), mintlify/global-p2p/quickstart.mdx (USDC decimal in sentAmount)

Important Files Changed

Filename	Overview
mintlify/global-p2p/quickstart.mdx	Quote and webhook envelope updated to new schema; USDC decimals: 2 in sentAmount is inconsistent with real-world USDC (6 decimals) — noted in prior review thread.
mintlify/global-p2p/sending-receiving-payments/receiving-payments.mdx	User→Customer vocabulary migrated; webhook envelope restructured to {id, type, timestamp, data}; PENDING/COMPLETED webhooks now carry distinct IDs (007/008); receiverCustomerInfo updated throughout.
mintlify/payouts-and-b2b/payment-flow/send-payment.mdx	Quote responses and JS code updated to use totalSendingAmount/sendingCurrency; source/destination discriminators added; execute response correctly returns a Quote instead of a fabricated transaction with executedAt.
mintlify/payouts-and-b2b/quickstart.mdx	Webhook envelope migrated from old {transaction, webhookId, type} to {id, type, timestamp, data}; event type updated to dot-notation; quoteId → id in quote responses.
mintlify/platform-overview/core-concepts/currencies-and-rails.mdx	MXN decimals: 8 → 2 corrected; amounts scaled accordingly; feesIncluded 5→500; prose fee summary updated from $250 to $5 — now internally consistent.
mintlify/platform-overview/core-concepts/quote-system.mdx	Quote schema updated; webhook handling code switches from req.body.transaction to req.body.data and uses type.startsWith for new dot-notation event types; execute response now returns a Quote object.
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx	Removes invented currency field from transfer-out/transfer-in bodies; idempotency example updated to show Idempotency-Key as HTTP header. sourceType/destinationType discriminators still absent — noted in prior review thread.
mintlify/ramps/accounts/internal-accounts.mdx	Source and destination in quote creation updated to include sourceType/destinationType discriminators; removed invented currency field from destination.
mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx	Quote response overhauled with full schema; instructions.reference path fixed to instructions.accountOrWalletInfo.reference; receivingAmount → totalReceivingAmount; broken JSON corrected; discriminators added.
mintlify/ramps/conversion-flows/self-custody-wallets.mdx	Discriminators added; receivingAmount → totalReceivingAmount; phantom destination.currency and destination.accountInfo.address fields removed from webhook handler.
mintlify/ramps/platform-tools/sandbox-testing.mdx	Source discriminator sourceType: ACCOUNT added; destination currency removed and destinationType: ACCOUNT added; straightforward fix.
mintlify/ramps/platform-tools/webhooks.mdx	Webhook envelope updated; idempotency example now destructures id as webhookId from the new envelope; test webhook payload updated from webhookId to id.
mintlify/ramps/quickstart.mdx	Quote and transaction responses updated; webhook envelope migrated; referenceCode → reference in paymentInstructions; sourceType/destinationType discriminators added throughout.
mintlify/rewards/developer-guides/distributing-rewards.mdx	Quote schema updated (quoteId → id, discriminators added); webhook envelope migrated with id, type: OUTGOING_PAYMENT.COMPLETED, timestamp, and data.
mintlify/rewards/quickstart.mdx	Quote and webhook responses updated consistently with new schema; discriminators added; old OUTGOING_PAYMENT event type corrected to OUTGOING_PAYMENT.COMPLETED.
mintlify/snippets/global-accounts/walkthrough.mdx	Source/destination discriminators added and invented currency fields removed from quote response; straightforward schema sync.
mintlify/snippets/reconciliation/reconciliation.mdx	Webhook envelope fully migrated; reconciliation prose updated to reference data.id and envelope id; source/destination discriminators added.
mintlify/snippets/sending/cross-currency.mdx	Quote and webhook schemas updated; OUTGOING_PAYMENT.COMPLETED now has correct envelope id and sentAmount.currency.code corrected from USD to USDC. USDC decimals: 2 used consistently within file but inconsistent with real-world 6-decimal USDC — noted in prior thread.
mintlify/snippets/sending/same-currency.mdx	Source/destination discriminators added; invented currency fields removed; clean, minimal change.
mintlify/snippets/sending/uma.mdx	UMA lookup endpoint corrected to /receiver/uma/{address}?customerId=...; response updated to ReceiverUmaLookupResponse shape with receiverUmaAddress, lookupId, supportedCurrencies, and requiredPayerDataFields.

_{Reviews (7): Last reviewed commit: "complete envelope migration on USDC webh..." | Re-trigger Greptile}

[jklein24]

@greptile review

[jklein24]

@greptile review

[jklein24]

@greptile review

[jklein24]

@greptile review

[jklein24]

@greptile review

[jklein24]

On the latest finding — confirmed against the schema: TransferInRequest and TransferOutRequest use InternalAccountReference / ExternalAccountReference, both of which only require accountId (no sourceType/destinationType discriminator). The discriminators apply to /quotes (where source/destination are oneOf with multiple types), not to /transfer-out and /transfer-in, which are always account-to-account. The transaction-lifecycle.mdx examples are schema-correct as written.