Stripe Invoicing + E-Signatures: Auto-Attach Signed Agreements (2026)

import { NextRequest, NextResponse } from "next/server";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-06-20",
});

const STRIPE_WEBHOOK_SECRET = process.env.STRIPE_WEBHOOK_SECRET!;
const SIGNBEE_API_KEY = process.env.SIGNBEE_API_KEY!;
const HIGH_VALUE_THRESHOLD_CENTS = 250000; // $2,500.00

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get("stripe-signature");

  if (!signature) {
    return NextResponse.json({ error: "Missing stripe-signature header" }, { status: 400 });
  }

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, signature, STRIPE_WEBHOOK_SECRET);
  } catch (err: any) {
    console.error(`Webhook signature verification failed: ${err.message}`);
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

  // Handle invoice creation
  if (event.type === "invoice.created" || event.type === "invoice.finalized") {
    const invoice = event.data.object as Stripe.Invoice;

    // Check if contract is required based on amount or metadata tag
    const requiresContract =
      invoice.metadata?.requires_contract === "true" ||
      (invoice.amount_due && invoice.amount_due >= HIGH_VALUE_THRESHOLD_CENTS);

    // Skip if already attached or does not qualify
    if (!requiresContract || invoice.metadata?.signbee_doc_id) {
      return NextResponse.json({ received: true, skipped: true });
    }

    const customerEmail = invoice.customer_email || "";
    const customerName = invoice.customer_name || "Valued Client";

    // Format line items into Markdown table
    const lineItemRows = (invoice.lines?.data || [])
      .map(
        (item) =>
          `| ${item.description || "Service"} | ${item.quantity || 1} | $${((item.unit_amount_excluding_tax || item.amount) / 100).toFixed(2)} | $${(item.amount / 100).toFixed(2)} |`
      )
      .join("\n");

    const totalFormatted = (invoice.amount_due / 100).toFixed(2);
    const invoiceNumber = invoice.number || invoice.id;

    // Compile dynamic Markdown agreement
    const markdownAgreement = `
# Master Services Agreement & Order Form

**Agreement Reference:** ${invoiceNumber}  
**Effective Date:** ${new Date().toISOString().split("T")[0]}  
**Provider:** Acme Solutions Inc.  
**Client Organization:** ${customerName}  
**Signer Email:** ${customerEmail}  

---

## 1. Statement of Work & Deliverables

The parties agree to the scope and line items detailed below, corresponding directly to Stripe Invoice `${invoice.id}`:

| Service Description | Quantity | Rate | Total Due |
| :--- | :--- | :--- | :--- |
${lineItemRows}

**Total Contract Value:** $${totalFormatted} ${invoice.currency.toUpperCase()}

---

## 2. Payment Terms & Automatic Collection

1. **Authorization:** By signing below, Client certifies that they are an authorized representative with authority to execute contracts and authorize payment.
2. **Immediate Settlement:** Client acknowledges that execution of this agreement authorizes Acme Solutions Inc. to process payment for Invoice `${invoiceNumber}` immediately upon signature.
3. **Dispute Waiver:** Client agrees that services outlined herein constitute authorized deliverables, and waives claims of unauthorized card-not-present processing once delivery is initiated.

---

## 3. Execution & Cryptographic Authentication

By signing below, the parties agree to be legally bound by this Master Services Agreement under the ESIGN Act (15 U.S.C. § 7001) and UETA regulations.
`;

    // Dispatch agreement via Signbee API
    const signbeeRes = await fetch("https://signb.ee/api/v1/send", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${SIGNBEE_API_KEY}`,
      },
      body: JSON.stringify({
        markdown: markdownAgreement,
        recipient_name: customerName,
        recipient_email: customerEmail,
        subject: `Action Required: Sign Agreement for Invoice ${invoiceNumber}`,
        metadata: {
          stripe_invoice_id: invoice.id,
          stripe_customer_id: typeof invoice.customer === "string" ? invoice.customer : invoice.customer?.id,
          total_cents: invoice.amount_due,
        },
      }),
    });

    if (!signbeeRes.ok) {
      const errText = await signbeeRes.text();
      console.error("Failed to send contract via Signbee:", errText);
      return NextResponse.json({ error: "Signbee dispatch failed" }, { status: 500 });
    }

    const { id: signbeeDocId } = await signbeeRes.json();

    // Update Stripe Invoice metadata to record the pending contract state
    await stripe.invoices.update(invoice.id, {
      metadata: {
        signbee_doc_id: signbeeDocId,
        contract_status: "sent_for_signing",
        contract_dispatched_at: new Date().toISOString(),
      },
      auto_advance: false, // Pause auto-collection until signed
    });

    return NextResponse.json({ received: true, signbeeDocId });
  }

  return NextResponse.json({ received: true });
}

import { NextRequest, NextResponse } from "next/server";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-06-20",
});

export async function POST(req: NextRequest) {
  const payload = await req.json();

  // Validate event type
  if (payload.event !== "document.signed") {
    return NextResponse.json({ received: true, ignored: true });
  }

  const {
    document_id: signbeeDocId,
    sha256_hash: sha256Hash,
    signed_pdf_url: signedPdfUrl,
    metadata,
  } = payload;

  const stripeInvoiceId = metadata?.stripe_invoice_id;
  if (!stripeInvoiceId) {
    console.error("Signbee callback missing stripe_invoice_id metadata");
    return NextResponse.json({ error: "Missing invoice reference" }, { status: 400 });
  }

  try {
    // 1. Fetch the signed PDF certificate from Signbee
    const pdfResponse = await fetch(signedPdfUrl);
    if (!pdfResponse.ok) {
      throw new Error(`Failed to download signed PDF: ${pdfResponse.statusText}`);
    }
    const pdfBuffer = Buffer.from(await pdfResponse.arrayBuffer());

    // 2. Upload the signed PDF directly to Stripe Files API
    const stripeFile = await stripe.files.create({
      purpose: "invoice_attachment",
      file: {
        data: pdfBuffer,
        name: `signed_agreement_${signbeeDocId}.pdf`,
        type: "application/pdf",
      },
    });

    // 3. Attach file to Invoice and update metadata with SHA-256 hash
    await stripe.invoices.update(stripeInvoiceId, {
      invoice_attachments: [stripeFile.id],
      metadata: {
        contract_status: "signed",
        signbee_audit_hash: sha256Hash,
        signbee_signed_file_id: stripeFile.id,
        signed_at: new Date().toISOString(),
      },
      auto_advance: true, // Resume automated lifecycle
    });

    // 4. Optionally capture payment immediately if auto-charge is configured
    const invoice = await stripe.invoices.retrieve(stripeInvoiceId);
    if (invoice.status === "open" && invoice.collection_method === "charge_automatically") {
      await stripe.invoices.pay(stripeInvoiceId);
      console.log(`Successfully paid invoice ${stripeInvoiceId} following signature.`);
    }

    return NextResponse.json({
      success: true,
      stripeFileId: stripeFile.id,
      sha256Hash,
    });
  } catch (error: any) {
    console.error("Error executing post-signing Stripe handshake:", error);
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
}

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function submitContractDisputeEvidence(disputeId: string) {
  const dispute = await stripe.disputes.retrieve(disputeId);
  const chargeId = typeof dispute.charge === "string" ? dispute.charge : dispute.charge.id;

  // Retrieve charge and linked invoice
  const charge = await stripe.charges.retrieve(chargeId);
  const invoiceId = typeof charge.invoice === "string" ? charge.invoice : charge.invoice?.id;

  if (!invoiceId) {
    throw new Error("No linked invoice found for disputed charge.");
  }

  const invoice = await stripe.invoices.retrieve(invoiceId);
  const fileId = invoice.metadata?.signbee_signed_file_id;
  const auditHash = invoice.metadata?.signbee_audit_hash;
  const signedAt = invoice.metadata?.signed_at;

  // Submit definitive compelling evidence to card networks
  const updatedDispute = await stripe.disputes.update(disputeId, {
    evidence: {
      customer_communication: fileId, // Signed PDF from Stripe Files API
      customer_signature: fileId,
      service_documentation: fileId,
      uncategorized_text: `Customer executed legally binding Master Services Agreement on ${signedAt}. Cryptographic Document Checksum: SHA-256 ${auditHash}. IP and identity confirmed under ESIGN/eIDAS compliance.`,
    },
    submit: true, // Submit directly to issuing bank for review
  });

  return updatedDispute;
}