Payment Link

📖 Overview

internal/api/v1/billing/services/payment-link.service.js creates Stripe-hosted invoices for CRM contacts and returns short URLs that can be shared with customers. It handles contact lookup, on-demand Stripe customer creation, note linking, and line-item validation, all while respecting connected-account tokens.

Primary Controller: payment-link.controller.js

🗄️ Collections & Models

• shared/models/contact.js – Locates CRM contacts and persists Stripe linkage metadata.

🔗 External Dependencies

• Stripe – Customers API, Invoices API, Invoice Items API.
• DashClicks Router (API_BASE_URL) – Proxies customer creation via internal billing endpoint.
• Short URL Utility – shared/utilities/short-url generates branded short links.
• Customer Service – Links contacts to newly created Stripe customers.
• Logger Utility – Captures failures when generating short URLs.

🔄 Data Flow

flowchart TD
    UI[Billing UI] -->|POST /payment-links| Controller
    Controller --> Service
    Service --> Contact[(CRM Contact)]
    Service --> stripe[Stripe API]
    Service --> Shortener
    stripe --> HostedInvoice[Hosted Invoice URL]
    Shortener --> HostedInvoice

🧩 Functions

_findOrCreateCustomer({ contact, stripe_billing, stripe_config, account_id, req })

Private helper that ensures a Stripe customer exists and is linked to the contact.

1. Builds a Stripe search query combining contact email and phone.
2. Executes stripe.customers.search with connected account context.
3. When no match is found:
   • Calls internal /v1/billing/customer endpoint to create a Stripe customer via Router.
   • Invokes customerService.linkContact to sync DashClicks CRM with newly created Stripe metadata.
4. Returns Stripe customer object for downstream invoicing.

Edge Cases

• Search query gracefully handles missing email or phone.
• Address fields are mapped only when provided on the contact.

create({ req, contact_id, account_id, stripe_billing, stripe_config, currency, line_items, due_date })

Main entry point invoked by the controller.

1. Loads contact by ID; throws notFound when missing.
2. Resolves Stripe customer via _findOrCreateCustomer.
3. Creates a draft invoice with collection_method = 'send_invoice', auto_advance = false, and human-readable description.
4. Iterates line items to create invoice items (supporting custom amount, quantity, or saved price_id).
5. Finalises the invoice without sending to allow UI to orchestrate delivery.
6. Attempts to shorten the hosted invoice URL; falls back to original on failure.
7. Returns enriched invoice payload (with short_url when available).

Guards & Error Handling

• Cleans up on partial failure: deletes draft invoice if any line item creation fails.
• Converts Stripe due_date parameter errors into actionable badRequest responses.
• Logs but does not block when short URL creation fails.

🧪 Testing Notes

• Add fixture line items covering both price_id and custom amount scenarios when extending functionality.
• Error handling can be unit tested by mocking Stripe errors to confirm invoice deletion fallback.

⚠️ Operational Considerations

• Ensure the request includes OAuth headers when relaying to Router; service forwards req.headers.
• Short URL creation depends on downstream infrastructure; failures degrade gracefully to long URLs.

🔗 Related Docs

• Customer
• Billing Module Overview
• Charge