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 synchronizes 20 documentation files with the current OpenAPI schema across the payments, ramps, rewards, and global-p2p product areas. The changes are broadly correct and well-scoped, but the transfer-out/transfer-in request bodies in transaction-lifecycle.mdx were not updated with the required sourceType/destinationType discriminators that are added everywhere else.

• Quote schema: id (not quoteId), flat totalSendingAmount/totalReceivingAmount/feesIncluded integers, separate sendingCurrency/receivingCurrency objects, and required sourceType/destinationType discriminators — applied consistently across all quote and transfer examples except the two same-currency transfer request bodies in transaction-lifecycle.mdx.
• Webhook envelope: Migrated from {webhookId, transaction, …} to {id, type, timestamp, data} with dot-notation event types (OUTGOING_PAYMENT.COMPLETED, INCOMING_PAYMENT.PENDING, etc.) across all 20 files; idempotency code examples updated to match.
• Global-p2p / UMA: User* vocabulary replaced with Customer*; UMA lookup endpoint corrected to /receiver/uma/{address}?customerId=…; ReceiverUmaLookupResponse shape updated with expanded supportedCurrencies and typed requiredPayerDataFields.

Confidence Score: 4/5

Safe to merge with a small follow-up: the same-currency transfer request bodies in transaction-lifecycle.mdx are missing the discriminator fields that this PR adds as required everywhere else.

The transfer-out and transfer-in request bodies in transaction-lifecycle.mdx omit sourceType/destinationType that the rest of the PR marks as required — a developer following only that guide will build requests that fail schema validation. All other structural changes (envelope migration, flat quote amounts, Customer vocabulary, UMA endpoint) are applied correctly and consistently across the remaining 19 files.

mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx — transfer-out and transfer-in request bodies need sourceType/destinationType added.

Important Files Changed

Filename	Overview
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx	Idempotency-Key correctly moved to HTTP header; transfer-out and transfer-in request bodies still missing required sourceType/destinationType discriminators that every other file in this PR adds.
mintlify/snippets/sending/cross-currency.mdx	Quote schema aligned (flat amounts, discriminators, USDC decimals now consistent at 2); OUTGOING_PAYMENT.COMPLETED envelope id added; BALANCE_UPDATED restructured to new data-wrapped format.
mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx	Broken JSON fixed, totalReceivingAmount replaces receivingAmount, reference field path corrected to accountOrWalletInfo.reference, sourceType/destinationType added to quote request.
mintlify/global-p2p/quickstart.mdx	Quote response expanded to full schema, webhook envelope migrated; REALTIME_FUNDING source retains currency field (consistent with fiat-crypto-conversion but inconsistent with other REALTIME_FUNDING examples elsewhere in the PR).
mintlify/global-p2p/sending-receiving-payments/receiving-payments.mdx	Customer vocabulary migration (User→Customer) complete; webhook envelopes use distinct IDs for PENDING/COMPLETED; requestedReceiverCustomerInfoFields correctly placed inside data.
mintlify/snippets/sending/uma.mdx	UMA lookup endpoint corrected to /receiver/uma/{address}; response updated to ReceiverUmaLookupResponse shape with supportedCurrencies expanded and requiredPayerDataFields with mandatory flags.
mintlify/ramps/platform-tools/webhooks.mdx	Webhook envelope migrated (id/type/data), idempotency and transaction-dedup code updated to read from correct fields; test webhook id field renamed.
mintlify/platform-overview/core-concepts/currencies-and-rails.mdx	MXN decimals corrected 8→2; totalSendingAmount/totalReceivingAmount/feesIncluded scaled to match $1,000 example; prose math reconciled.
mintlify/payouts-and-b2b/quickstart.mdx	Webhook envelopes updated to new format; event types updated (INCOMING_PAYMENT.COMPLETED, OUTGOING_PAYMENT.COMPLETED); quote id/sourceType/destinationType fields corrected.
mintlify/snippets/reconciliation/reconciliation.mdx	Webhook envelope restructured to new format; transactionId→id corrected; idempotency prose updated to reference envelope id, data.id, and timestamp.

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant G as Grid API
    participant W as Webhook Endpoint

    C->>G: "POST /quotes {source: {sourceType, ...}, destination: {destinationType, ...}}"
    G-->>C: "Quote {id, status:PENDING, totalSendingAmount, totalReceivingAmount, feesIncluded, sendingCurrency, receivingCurrency}"

    alt ACCOUNT source (internal balance)
        C->>G: "POST /quotes/{id}/execute"
        G-->>C: "Quote {id, status:PROCESSING, transactionId}"
    else REALTIME_FUNDING source
        G-->>C: "Quote {id, paymentInstructions[{accountOrWalletInfo}]}"
        C->>G: External payment (ACH / crypto deposit)
        W-->>C: "{id, type:INTERNAL_ACCOUNT.BALANCE_UPDATED, timestamp, data:{id, balance}}"
    end

    W-->>C: "{id, type:OUTGOING_PAYMENT.COMPLETED, timestamp, data:{id:Transaction, sentAmount, receivedAmount, quoteId}}"

    note over C,W: Idempotent dedup on envelope id

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx:84-88
The `transfer-out` and `transfer-in` request bodies are missing the `sourceType`/`destinationType` discriminators that this PR marks as required throughout every other example. A developer following only the transaction lifecycle guide will omit these fields and get a schema validation error (or a silently wrong request if the server applies lenient coercion).

```suggestion
{
  "source": {"sourceType": "ACCOUNT", "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"},
  "destination": {"destinationType": "ACCOUNT", "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"},
  "amount": 100000
}
```

### Issue 2 of 2
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx:108-112
Same missing discriminator issue for the `transfer-in` request body — `sourceType` is absent from the `source` object, inconsistent with every other updated example in this PR.

```suggestion
{
  "source": {"sourceType": "ACCOUNT", "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"},
  "destination": {"destinationType": "ACCOUNT", "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"},
  "amount": 100000
}
```

_{Reviews (6): 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.