Hey there! Let's walk through how to handle both of these Stripe receipt and invoice download scenarios for your custom website—these are common flows, and Stripe's API makes it pretty straightforward.

1. Downloading Receipts & Invoices Directly from Stripe via Your Website #

First off, quick clarification: receipts are tied to individual payments, while invoices are tied to billing records. Depending on your use case, you might need one or both. Here's how to pull them into your site:

• Step 1: Store key Stripe IDs in your database
  When a payment or invoice is created, make sure to save the payment_id (for receipts) and invoice_id (for invoices) in your own system. You'll need these IDs to fetch the corresponding files later.

• Step 2: Fetch download URLs via Stripe API (server-side only!)
  Never expose your Stripe secret key to the client—all API calls should happen on your backend. Use the Stripe SDK for your language to retrieve the necessary details:

  • For receipts: Call GET /v1/payments/{payment_id}. The receipt URL lives in the receipt_url field of the returned payment object.
  • For invoices: Call GET /v1/invoices/{invoice_id}. You’ll get two useful URLs here: invoice_pdf (the full invoice PDF) and receipt_url (the receipt for the associated payment, if the invoice is paid).

• Step 3: Add download options to your website
  Once you have the URLs, render them as buttons or links on your user's dashboard, order history, or relevant page. If you want to keep Stripe's URLs hidden or add access checks, you can proxy the download through your server (fetch the file backend-side and serve it to the user directly).

Here’s a quick Node.js example using the Stripe SDK:

const stripe = require('stripe')('your-stripe-secret-key');

// Fetch receipt URL for a specific payment
async function getReceiptUrl(paymentId) {
  const payment = await stripe.payments.retrieve(paymentId);
  return payment.receipt_url;
}

// Fetch invoice PDF and associated receipt URLs
async function getInvoiceFiles(invoiceId) {
  const invoice = await stripe.invoices.retrieve(invoiceId);
  return {
    invoicePdfUrl: invoice.invoice_pdf,
    receiptUrl: invoice.receipt_url
  };
}

2. Downloading Receipts & Invoices Using an Invoice ID from Your Website #

If you already have an invoice_id (stored in your DB or provided by the user), you can use it to pull both the invoice PDF and receipt in one flow:

• Step 1: Retrieve the invoice object via API
  Use the GET /v1/invoices/{invoice_id} endpoint (server-side) to fetch the full invoice details.

• Step 2: Extract and validate the URLs
  The invoice object includes invoice_pdf (always available once the invoice is generated) and receipt_url (only available if the invoice has been paid). Make sure to handle edge cases—like if the invoice is unpaid, receipt_url will be null, so you should show a message to the user instead of a broken link.

• Step 3: Serve the download to the user
  Render buttons/links on your site pointing to these URLs. Proxying through your server is a good idea if you want to restrict access (e.g., only let the user who owns the invoice download the files).

Example of a backend endpoint (Node.js/Express) to handle this:

app.get('/download-invoice/:invoiceId', async (req, res) => {
  const { invoiceId } = req.params;
  // Add authentication here to ensure the user has access to this invoice

  try {
    const invoice = await stripe.invoices.retrieve(invoiceId);
    
    if (!invoice.invoice_pdf) {
      return res.status(404).send('Invoice PDF is not available');
    }

    // Option 1: Redirect directly to Stripe's PDF URL
    res.redirect(invoice.invoice_pdf);

    // Option 2: Proxy the file to hide Stripe's URL
    // const pdfResponse = await fetch(invoice.invoice_pdf);
    // res.setHeader('Content-Type', 'application/pdf');
    // res.setHeader('Content-Disposition', `attachment; filename="invoice-${invoiceId}.pdf"`);
    // pdfResponse.body.pipe(res);
  } catch (error) {
    res.status(500).send('Failed to retrieve invoice details');
  }
});

Quick Pro Tips #

• Permissions: Ensure your Stripe API key has at minimum the read_invoices and read_payments scopes.
• Error Handling: Always add checks for invalid IDs, unpaid invoices, or API failures to avoid confusing your users.
• Client-Side Safety: Never include your Stripe secret key in frontend code—keep all API logic on your server.

内容的提问来源于stack exchange，提问作者suresh