Payments - Hypermid

Server-side only. These functions send your secret key and throw if window exists. Create the session on your server and hand the browser the returned id or url.

Create a session

import { createCheckout } from "@hypermid/sdk";

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

// Hand this to the browser.
return { url: session.url, id: session.id };

createDeposit and createWithdrawal take the same request shape.

Function	Product
`createCheckout`	Checkout — fixed amount
`createDeposit`	Deposit — often open-amount
`createWithdrawal`	Withdrawal — funds out
`getPayment`	Read a session you created

Request fields

Beyond chain / token / recipient, the create call accepts:

Field	Type	Notes
`amount`	`string`	Base units (`"10000000"` = 10 USDC at 6 decimals). Omit for an open amount — the payer names it. Fixed for a checkout, usually open for a deposit.
`minAmount` / `maxAmount`	`string`	Bounds on an open-amount session. Ignored when `amount` is fixed.
`orderId`	`string`	Your id, and the idempotency key (see below).
`metadata`	`object`	Arbitrary JSON. Echoed back on session reads and on every webhook; never shown to the payer. Keep it small — an oversized object is a `413`.
`expiresIn`	`number`	Session lifetime in seconds. Defaults to the server’s configured TTL. After it elapses the session is `expired`.
`successUrl` / `cancelUrl`	`string`	Where the hosted page sends the payer afterwards.

For a session that offers the payer more than one destination, see multi-destination deposits (destinations / destinationRecipients) — those replace the top-level chain / token / recipient.

For a checkout, recipient must be on your payout allowlist. An un-allowlisted recipient is refused with 403 RECIPIENT_NOT_ALLOWLISTED — add it in the partner portal first. Deposits and withdrawals are not allowlist-checked this way (a deposit lands in the payer’s own wallet).

Idempotency

Creation is idempotent on orderId. Replaying the same orderId while a session is still open returns the existing session rather than opening a second one:

const again = await createCheckout({ orderId: "order-8842", /* … */ }, opts);
// again.id === session.id

So a retry after a network timeout is safe — it cannot double-charge. Use your own order identifier and this property comes for free.

Reading a session

import { getPayment } from "@hypermid/sdk";

const session = await getPayment(id, { secretKey: process.env.HYPERMID_SECRET_KEY! });
if (session.status === "completed") { /* fulfil */ }

Prefer a webhook over polling. The webhook fires as soon as funds land; polling adds latency and load for the same answer. Read the session to confirm what a webhook told you, not to discover it.

Sandbox

Pass an sk_test_… key. Nothing else changes — same functions, same host, same payloads, testnets only. See Environments.

const opts = {
  secretKey: process.env.NODE_ENV === "production"
    ? process.env.HYPERMID_SECRET_KEY_LIVE!
    : process.env.HYPERMID_SECRET_KEY_TEST!,
};

Options

interface PaymentsClientOptions {
  secretKey: string;      // sk_live_… or sk_test_…
  apiBase?: string;       // defaults to https://server.hypermid.io
  signal?: AbortSignal;   // for timeouts and cancellation
}

​Create a session

​Request fields

​Idempotency

​Reading a session

​Sandbox

​Options

Create a session

Request fields

Idempotency

Reading a session

Sandbox

Options