Payment links - Hypermid

Server-side only. Payment-link functions send your secret key and throw if window exists. Never put an sk_ key in browser code.

A payment link stores a fixed checkout configuration behind a stable id. Build the hosted URL from that id and share it with your customer:

import { createPaymentLink } from "@hypermid/sdk/payment-links";

const link = await createPaymentLink(
  {
    chain: 8453,
    token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    recipient: "0xYourTreasury…",
    amount: "10000000", // 10 USDC at 6 decimals
    successUrl: "https://shop.example/thanks",
    cancelUrl: "https://shop.example/cart",
  },
  { secretKey: process.env.HYPERMID_SECRET_KEY! },
);

const url = `https://pay.hypermid.io/link/${encodeURIComponent(link.id)}`;

Opening the link mints a fresh checkout session. The link is reusable unless you set singleUse: true.

Functions

Function	Wire request	Returns
`createPaymentLink(req, opts)`	`POST /v1/payments/links`	`PaymentLink`
`listPaymentLinks(opts)`	`GET /v1/payments/links`	`PaymentLinkList`
`getPaymentLink(id, opts)`	`GET /v1/payments/links/:id`	`PaymentLink`
`updatePaymentLink(id, changes, opts)`	`PATCH /v1/payments/links/:id`	`PaymentLinkMutation`
`revokePaymentLink(id, opts)`	`DELETE /v1/payments/links/:id`	`PaymentLinkMutation`

All operations are scoped to the secret key’s merchant and environment. The key is sent as Authorization: Bearer, not as x-api-key.

function createPaymentLink(
  req: CreatePaymentLinkRequest,
  opts: PaymentLinksClientOptions,
): Promise<PaymentLink>;
function listPaymentLinks(
  opts: PaymentLinksClientOptions,
): Promise<PaymentLinkList>;
function getPaymentLink(
  id: string,
  opts: PaymentLinksClientOptions,
): Promise<PaymentLink>;
function updatePaymentLink(
  id: string,
  changes: UpdatePaymentLinkRequest,
  opts: PaymentLinksClientOptions,
): Promise<PaymentLinkMutation>;
function revokePaymentLink(
  id: string,
  opts: PaymentLinksClientOptions,
): Promise<PaymentLinkMutation>;

Create fields

interface CreatePaymentLinkRequest {
  chain: number;
  token: string;
  recipient: string;
  amount: string;
  singleUse?: boolean;
  metadata?: Record<string, unknown>;
  successUrl?: string;
  cancelUrl?: string;
  expiresAt?: string;
}

amount is required and is a positive integer in destination-token base units. Payment links do not support open amounts. expiresAt, when present, must be a future ISO 8601 timestamp. singleUse defaults to false. The update type is Partial<CreatePaymentLinkRequest>:

type UpdatePaymentLinkRequest = Partial<CreatePaymentLinkRequest>;

Link lifecycle semantics

These operations have effects beyond changing the returned fields:

Single-use is consumed by the first confirmed payment. Opening the link does not consume it. Until a payment is confirmed, it can mint sessions; after confirmation, further redemptions are refused.
Editing versions the link. A PATCH cancels every unpaid session minted from the previous version. cancelledSessions tells you how many sessions were canceled, and a payer who opened the old version but has not paid must start again.
Revoking is a soft delete. DELETE retains the row, sets revokedAt, cancels unpaid sessions already minted from the link, and never reuses its id. Call it revokePaymentLink in application code even though the wire verb is DELETE.
De-allowlisting is permanent. Removing a payout address from the merchant’s allowlist permanently revokes every link that uses it. Adding the address again does not revive those links.

consumedBySessionId identifies the session that consumed a single-use link; it is not payment proof by itself. Check the session status or your dashboard before fulfilling an order.

Manage links

import {
  getPaymentLink,
  listPaymentLinks,
  revokePaymentLink,
  updatePaymentLink,
} from "@hypermid/sdk/payment-links";

const opts = { secretKey: process.env.HYPERMID_SECRET_KEY! };
const { links } = await listPaymentLinks(opts);
const current = await getPaymentLink(link.id, opts);

const revised = await updatePaymentLink(
  link.id,
  { amount: "12000000" },
  opts,
);
console.log(revised.version, revised.cancelledSessions);

const revoked = await revokePaymentLink(link.id, opts);
console.log(revoked.revokedAt, revoked.cancelledSessions);

Options and response

interface PaymentLinksClientOptions {
  secretKey: string;       // sk_live_… or sk_test_…
  apiBase?: string;        // defaults to https://server.hypermid.io
  signal?: AbortSignal;
}

PaymentLink includes the stable id, version, environment, destination (chain, token, recipient), fixed amount, singleUse, metadata, redirects, expiresAt, revokedAt, consumedBySessionId, and creation/update timestamps. PaymentLinkMutation includes all of those fields plus cancelledSessions.

​Functions

​Create fields

​Link lifecycle semantics

​Manage links

​Options and response

Functions

Create fields

Link lifecycle semantics

Manage links

Options and response