Stripe File Uploads

Stripe's Files API exists, but it is scoped to Stripe's own needs — dispute evidence, Connect identity verification, and a few branding assets — with a 16 MB cap per file and no general-purpose retrieval or CDN. The moment your payment flow has to keep something Stripe doesn't natively manage — a customer-uploaded proof of address, a high-resolution passport scan for your own KYC review, a batch of invoice PDFs tied to a subscription, a signed mandate — you need storage you control. files.link sits next to your Stripe integration as that store: a REST API for uploads, private files with expiring signed URLs for anything containing PII, and permanent links you can persist on the payment record.

A typical pattern: your checkout or onboarding collects a verification document, your server uploads it with POST /v1/files/{folderId}, PUTs the bytes to the returned presigned URL, and confirms with POST /v1/files/confirm-upload. You then store the returned file id against the Stripe customer or PaymentIntent in your own database — for example, customer.metadata or a row keyed by the Stripe customer ID.

When a reviewer needs to see the document, mint a signed URL on demand (10-minute default) so the PII is never sitting behind a permanent public link. If a dispute later requires evidence, the same stored file can be referenced in your dispute workflow without re-collecting it from the user.

Keep the trust boundary clean: the upload should happen server-side, triggered after Stripe confirms the relevant event (a webhook like identity.verification_session.verified or checkout.session.completed), so the files.link API key never ships to the browser. Files are encrypted at rest and in transit; for PII, default to private and rely on signed URLs rather than public CDN delivery.

Because there is no 16 MB ceiling, you can store full-resolution scans and multi-page document bundles that would bounce off the Stripe Files API, and because delivery has no separate egress surcharge, serving evidence back to a reviewer or to Stripe's dispute form doesn't add a metered bandwidth line. files.link handles storage and access control; it is not a KYC/identity-decisioning product — pair it with Stripe Identity or your own review process for the actual verification logic.