Add payment documents for payouts that need supporting evidence

[Awinfredwa]

What this does

Some payouts need supporting documents before the partner will pay them out. A business payout in CNY to China is the first one. Each purpose of payment needs its own set of documents, such as an invoice, a contract, or a purchase order.

Today the API has no way to send those documents. This PR adds the contract for it.

How it works

A platform does three things:

1. Finds out what is needed. The requirements are published in the docs, in a new page, Supporting Documents for China Business Payouts (mintlify/payouts-and-b2b/payment-flow/supporting-documents.mdx). They are the same for every China B2B payout, and the purpose of payment picks which row applies. The page lists the requirement IDs for each purpose and the document types each requirement accepts.
2. Uploads the files. POST /payment-documents takes one file per request and returns a document ID. GET /payment-documents/{id} shows its status.
3. Creates the quote with the IDs. POST /quotes takes up to 3 documentIds. Grid attaches every file to the payment before it returns the quote.

Quotes enforce the requirements. If documents are missing, POST /quotes returns 400 DOCUMENTS_REQUIRED, and details.missingRequirements lists the missing requirement IDs. That is the per-payout, machine-readable signal.

If any file fails to attach, Grid creates no quote. The platform retries the same request with the same Idempotency-Key.

Rules worth knowing:

• Files are PDF, JPEG, or PNG, from 1 to 8,000,000 bytes.
• A document can be used for 24 hours and on one quote only.
• A document belongs to one customer. Only that customer's quotes can use it. Without a customerId, it belongs to the platform, for the platform's own quotes.
• documentIds requires an Idempotency-Key.
• A service payment picks the purpose that names the service: COMMISSION_ON_GOODS, COMMISSION_ON_SERVICES, ACCOUNTING_SERVICES, or EXHIBITION_SERVICES. SERVICE_CHARGES is not accepted on China B2B payouts.
• Sending documentIds on a payout that does not use them is a 400. So is a China B2B payout whose purposeOfPayment is not one of the China business purposes in the docs.
• The quote lists the IDs of its attached documents in a new documentIds field.
• The quote also echoes the purposeOfPayment it was created with, in a new purposeOfPayment field.

New error codes

• DOCUMENTS_REQUIRED (400): documents are missing. details.missingRequirements says which.
• PAYMENT_DOCUMENT_NOT_FOUND (404)
• PAYMENT_DOCUMENT_ALREADY_USED (409)
• PAYMENT_DOCUMENT_EXPIRED (410)
• PAYMENT_DOCUMENT_ATTACHMENT_FAILED (424): nothing was created, so retry.

Notes

• Everything is additive, so info.version is unchanged.
• The requirements live in the docs, not in an API field. They don't vary per payout, and integrators are expected to set expectations up front rather than drive their UX from a response. The external-account lookup is unchanged. /discoveries is unchanged too, since it lists banks. A machine-readable version can be added later if integrators ask for one.
• The four service purposes replace a separate serviceCategory field. The payout partner has one purpose for all four services and takes the service name as free text. A second field on our side added a rule without matching anything the partner needs.
• The China-specific purposes are no longer documented as rejected on other corridors. Grid sends the payout partner the closest purpose it accepts there, or the partner's "other" purpose when none fits. China B2B payouts still accept only the purposes listed in the docs.
• This replaces the per-quote upload design in draft Add the payment-document contract for quotes that need supporting evidence #1045. It keeps that PR's document type enum.
• Some response values are documented rather than fixed in the schema: the requirement IDs in missingRequirements, contentType, and sizeBytes. Generated clients validate enums and limits, so fixing them would make a new format, a larger file, or a new corridor a breaking change. Today's values are listed in each description.
• The server side follows once this merges.

Checks

• make build regenerates openapi.yaml and mintlify/openapi.yaml.
• make lint-openapi passes.

🤖 Generated with Claude Code

[vercel]

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

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Sep 25, 2026 4:41pm UTC
grid-flow-builder	Ignored	Preview	Sep 25, 2026 4:41pm UTC
grid-wallet-demo	Ignored	Preview	Sep 25, 2026 4:41pm UTC

[mintlify]

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

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Sep 25, 2026, 4:42 PM

[Awinfredwa]

@greptile-apps review

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no outstanding or newly introduced actionable defect remains.

Summary

This PR adds the API contract for uploading supporting payment documents, discovering corridor-specific document requirements, and attaching uploaded documents when creating quotes.

• Adds upload and retrieval endpoints for payment documents.
• Exposes payment requirements through external-account lookup responses.
• Extends quote requests and responses with document IDs, service categories, and attached-document metadata.
• Adds document-specific errors and Stainless resource configuration.
• Clarifies that advertised requirements never exceed the quote document limit while keeping evolving response values open for forward compatibility.

Diagram

sequenceDiagram
    participant Platform
    participant Grid
    participant Partner

    Platform->>Grid: "GET /receiver/external-account/{accountId}"
    Grid-->>Platform: paymentRequirements
    loop One request per required file
        Platform->>Grid: POST /payment-documents
        Grid-->>Platform: PaymentDocument ID
    end
    Platform->>Grid: POST /quotes with documentIds
    Grid->>Partner: Attach supporting documents
    alt Every attachment succeeds
        Grid-->>Platform: Quote with documents
    else Attachment fails
        Grid-->>Platform: 424 PAYMENT_DOCUMENT_ATTACHMENT_FAILED
    end

Loading

_{Reviews (2) · Last reviewed commit: "Leave payment document formats and sizes..."}

[Awinfredwa]

this is solid, once this flow is approved can be set ready

[shreyav]

if this is static could it just be a table in docs? i can't imagine people would programatically collect documents but could be wrong
cc @pengying for thoughts as well

[Awinfredwa]

yea this is purely hardcoded for Thune's requirement, they presented this as a table so do u mean we should just have something like this:

[ls-bolt]

🦣 Congratulations @shreyav - your substantive review earned a Dromornis! (common)

This three-meter Australian bird had a massive skull but was probably herbivorous.

View your Frost-dex: https://zeus.dev.dev.sparkinfra.net/#/dinodex/shreyav?section=ice-age

[pengying]

Will this be different on a per transaction basis? If not, it might be better in the discovery API + documentation than in the lookup API.

I would expect that integrators are setting up expectations to their customers about what's required to send to China vs dynamically driving their UX from these API responses

[Awinfredwa]

Yes discovery makes more sense since they don't change per transaction, updating now, thanks!

[Awinfredwa]

Good question. It doesn't vary per transaction. The requirements are the same for every China B2B payout, and only the purpose picks which row applies. The per-transaction check already happens at quote time: DOCUMENTS_REQUIRED lists the missing requirements. So this now drops paymentRequirements from the lookup and publishes the table in the docs (mintlify/payouts-and-b2b/payment-flow/supporting-documents.mdx). I didn't add it to /discoveries, since that endpoint lists banks. We can add a machine-readable version later if integrators ask for one.

[Awinfredwa]

Went with docs only in the end: /discoveries lists banks per country/currency, but these requirements depend on rail, beneficiary type and purpose, which it can't express. Happy to add a machine-readable version there later if integrators ask.

[pengying]

Ok, let's start with docs under the CNY external account. If integrators run into issues we can add an API.

[ls-bolt]

🦣 Congratulations @pengying - your substantive review earned a Woolly rhinoceros! (rare)

A broad front horn and thick coat suited it to grazing across cold Eurasian steppe.

View your Frost-dex: https://zeus.dev.dev.sparkinfra.net/#/dinodex/pengying?section=ice-age

[pengying]

Do the documents need to turn into documentIds in the response? I don't think we need to change the data structure, and it's not a super RESTful pattern.

[Awinfredwa]

fixing now, will send and return documentIds. Details stay available from GET /payment-documents/{id}.

[Awinfredwa]

Agreed. Size isn't the concern (it's at most 3), but echoing the request shape is cleaner. The quote now returns documentIds, and QuoteDocument is gone. Details stay available from GET /payment-documents/{id}.

[pengying]

Does this need to be a different endpoint than documents?

[Awinfredwa]

Yes i think this should. /documents takes kyb/kyc docs and passes them right to sumsub, no storage. payment documents in this case would need to be stored. also the types of documents are vastly different, /document is for identity verification and /payment-document is per transaction docs like receipts and invoices.

[pengying]

All right. I was wondering if we wanted a single general document endpoint, but I guess there aren't that many document types?