Payment Links

A payment link is a shareable URL that opens a hosted pay page where a customer can complete a one-off payment without any integration on the merchant’s side. MVS Pay does not build its own hosted checkout for this — the URL is minted by Hyperswitch’s native payment-link feature, and MVS keeps a thin sidecar row (PaymentLinkExtension) for the dashboard-only fields that Hyperswitch doesn’t model (nickname, amount type, lifecycle state, expiry, tipping, tags).

This split is a direct application of ADR-007 · Native-Hyperswitch bias: let Hyperswitch own anything it already does well (here, the hosted pay page and the payment intent), and have MVS own only the gaps.

How it fits together

There are three layers in front of every payment-link operation, and they all appear in the source listed at the bottom of this section:

The extensions service is mounted at /v1/payment-links (see apps/mvs-pay-extensions/src/app.ts, where api.route("/payment-links", paymentLinkRoutes) is registered and an idempotency() middleware is attached to the same prefix). It is not a Next.js API route — orchestration lives in the standalone EKS service per ADR-006. See the Extensions Service and SDK surface pages for the broader picture.

The PaymentLinkExtension model

The sidecar is a Prisma model in packages/mvs-pay/prisma/schema.prisma (mapped to table payment_link_extension). Per the schema’s own comment, the extension sidecars are keyed by an opaque Hyperswitch ID string — there is no foreign key into Hyperswitch’s database, which is separate. The “join” back to Hyperswitch happens at the application layer through the SDK.

The view shape vs. the row

Routes never return the raw Prisma row. toView() in payment-links.ts maps a PaymentLinkExtension to a merged PaymentLinkView — Hyperswitch holds amount/currency/description on the intent, MVS holds everything else — and the SDK commits to that view (PaymentLinkRow in packages/mvs-pay-sdk/src/types.ts) rather than the database row. Notable renames the new owner should know:

• hyperswitchMerchantId is surfaced as merchantId.
• expiresAt and createdAt are serialized to ISO strings (null when unset).
• metadata, organizationId, and hyperswitchPaymentId are not in the view — they never leave the extensions service.

Create / list / send flow

Creating a link

POST /api/payment-links (dashboard) → client.paymentLinks.create → POST /v1/payment-links (extensions). The extensions handler does two writes in sequence:

The create body (CreatePaymentLinkInput):

1
interface CreatePaymentLinkInput {
2
  merchantId?: string;
3
  amountType?: string;        // defaults to "FIXED"
4
  amount?: number;            // cents; defaults to 0 on the intent
5
  currency?: string;          // defaults to "USD"
6
  nickname?: string;
7
  description?: string;
8
  expiresAt?: string;
9
  allowTipping?: boolean;
10
  tags?: string[];
11
  customerEmail?: string;          // forwarded to the Hyperswitch intent
12
  payment_link_config?: Record<string, unknown>; // passthrough to Hyperswitch
13
}

Listing and reading

A few specifics worth knowing:

• List filter. The dashboard forwards an optional merchant_id query param straight through; the extensions handler adds hyperswitchMerchantId to the where-clause when present. Results are ordered createdAt desc and returned as { data: [...] }, which the dashboard reshapes to { paymentLinks }.
• Org scoping is the security boundary. Every read/write is filtered by organizationId from the request context. A link another org owns surfaces as a plain 404, not a 403. There is no cross-org read path.
• Update is a whitelist. PATCH strips organizationId, hyperswitchPaymentId, and id so a caller cannot mass-assign tenancy or identity columns, then applies only nickname, description, expiresAt, allowTipping, and state. The dashboard uses the PUT verb; it maps to the SDK’s update method (and the extensions service’s PATCH).
• Cancel. Both the dedicated SDK cancel() (POST .../:id/cancel) and an update with state: "CANCELED" set the sidecar state to CANCELED. As noted above, this is a DB-only state change today.

Sending a link by email

This is the one piece of payment-link behaviour that lives entirely in the Next.js app, not the extensions service or the SDK namespace. The route is POST /api/payment-links/[id]/send (apps/mvs-pay/app/api/payment-links/[id]/send/route.ts).

What the route does, in order:

1. Auth + scope. Requires payment_links:write.
2. Config guard. If process.env.RESEND_API_KEY is unset it returns a 503 with an honest message — "Email is not configured (RESEND_API_KEY is unset); use Copy Link / Open Link to share this payment link". It does not fake a delivery.
3. Validate input. email is required (400 if missing/blank). message is optional and becomes the template’s personalMessage.
4. Fetch the link via client.paymentLinks.get(id) (org-scoped — a not-owned link 404s here).
5. Require a URL. If link.linkUrl is null it returns 422 (“This payment link has no shareable URL”).
6. Format the amount. link.amount is in cents; it is divided by 100 and formatted with Intl.NumberFormat in the link’s currency. When amount is null (e.g. CUSTOMER_CHOOSES) it renders the literal string "Amount at checkout".
7. Send via @mvs/mail’s sendEmail with templateId: "paymentLinkRequest". The merchantName falls back through link.nickname → auth.context.orgSlug → "MVS Pay". expiresAt is formatted as a long US date. tenantBrand is defaultTenantBrand.
8. Map the result. sendEmail returns a boolean; false → 502, true → 200 with { sent: true, email }.

The @mvs/mail delivery path

sendEmail (packages/mail/src/util/send.ts) is shared platform mail infrastructure, not payment-link-specific. For a payment-link send the relevant behaviours are:

• Idempotency. It builds a SHA-256 idempotency key from to | templateId | subject | dayBucket and short-circuits (return true, logged as a skip) if the same email was already sent that calendar day. This means a second send of the same link to the same recipient on the same day is silently de-duplicated and still reports success.
• Retries. Up to two retries with exponential backoff, but only for network-shaped errors (ECONNREFUSED, ENOTFOUND, EAI_AGAIN, DNS, network). Other failures fail fast.
• Clinical DLQ does not apply here. paymentLinkRequest is not in the clinical template set, so failed sends are logged and return false (no dead-letter enqueue).
• Provider. packages/mail/src/provider/index.ts re-exports only ./resend, so the active provider is Resend. send() resolves config with precedence cached DB settings → env (RESEND_API_KEY, config.mails.from, RESEND_REPLY_TO_EMAIL) → defaults, then POSTs to https://api.resend.com/emails. Mailgun/Postmark/Paubox/Plunk/Nodemailer/ console providers exist in the directory but are not wired through the index.

The email template

packages/mail/src/templates/billing/PaymentLinkRequest.tsx is a react-email template rendered through PatientEmailLayout. The route passes this context (PaymentLinkRequestProps):

The rendered email shows a centered “Payment Request from {merchantName}”, a prominent amount card, the optional personal message, a “Pay Now” button, and a footer noting the link is secure and (if set) when it expires.

Endpoint reference (summary)

Scopes are defined in apps/mvs-pay/lib/api-auth.ts (payment_links:read = “View payment links”, payment_links:write = “Create payment links”). See Authentication & Tenancy for how scopes are resolved from API keys vs. session.

Known gaps and honest caveats

Related pages