Skip to main content
Hypermid has one Payments product with three modes. Choose the mode by where the money is going; choose the integration method by whether you can keep a secret on a server.
Register the price server-side whenever you are charging one — via your backend (sk_) or a payment link. Use the publishable key only when the destination is one the payer has proven they own, or one you have registered (backend or dashboard).

​
Start with the money

These are payment sessions with the same lifecycle and reads. The mode is a business decision, not an integration setting.

​
One fee rule for all three modes

Checkout, Deposit, and Withdrawal resolve the same two fees on the same payer input: Hypermid’s fee plus an optional developer fee. A partner-specific Hypermid override replaces the global rate outright. The developer fee defaults to 0, is limited to 0–100 basis points, and requires a configured recipient when it is positive. The quote’s feeBreakdown reports hypermidBps, partnerBps, and their totalBps. A same-token EVM transfer is the explicit zero fee exception: a plain transfer has no fee-taking route. On the Near deposit-address rail, the provider keeps half of each declared app fee, so it sees twice each net leg. EVM developer earnings are held by Hypermid and settled periodically by manual transfer; Near-rail developer earnings are paid directly by the provider.

​
Then choose how to integrate

Method 1 gives you full control over all three modes. It needs a backend that can keep the secret key. Method 2 needs no merchant backend for its candidateId path, but it needs origin configuration and a server-authored destination-binding artifact. It cannot create Checkout or Withdrawal. Most readers in the last column should start there only if they are funding a user’s balance and the publishable Deposit capability has been enabled. A payment link is the no-backend path for a fixed-price Checkout.
Method 2 is available in production when you configure an allowed origin for the publishable key and Hypermid enables publishable Deposits for the partner. The key-creation flow requires at least one origin, so a new key does not hit 403 ORIGIN_NOT_CONFIGURED; that error is for a legacy key with no origins. After the origin is configured, a partner that Hypermid has not enabled receives 403 PUBLISHABLE_DEPOSIT_NOT_ENABLED. Configure the origin yourself when creating the key, then ask Hypermid to enable the partner. The path fails closed until both conditions hold.

​
A short decision path

  1. Are you selling something? Choose Checkout. If you have no backend, choose a payment link immediately.
  2. Are you funding a user’s own balance? Choose Deposit.
  3. Are you paying a user out? Choose Withdrawal.
  4. Can you keep a secret on a server? Use Method 1 for any mode. If not, the only Method 2 choice is Deposit. You configure the key’s origin; ask Hypermid to enable the partner. Its candidateId path needs no payer signature and no merchant backend at runtime.

​
Method 1: server-created sessions

The server supplies the session’s destination, amount and mode using the secret key. The browser renders the returned session, while the server remains the authority for fulfilment.

​
Checkout

See the Checkout guide and the @hypermid/sdk Payments reference.

​
Deposit

See the Deposit guide.

​
Withdrawal

See the Withdrawal guide.

​
Method 2: publishable-key Deposit

This method is browser-facing and accepts a pk_ key. The browser never names an arbitrary destination. It presents exactly one artifact, and Hypermid resolves the destination from that artifact:
  • candidateId — an opaque, server-authored destination candidate. It needs no payer signature and no merchant backend at runtime.
  • challenge — a payer signature over a server-issued SIWE message. It is EVM-only.
  • grant — a single-use JWS minted by your server. This is not a no-backend path, even though creation is submitted from the browser.
The browser calls createPublishableDeposit; the exact request union and branchable errors are in the publishable-key SDK reference. The publishable-key SDK reference has the exact request types and branchable errors. It returns a session, not proof that money arrived. Payment links are a no-backend path for fixed-price Checkout. They are not a fourth mode and they are not Method 2: a merchant creates or manages the link through the Dashboard or the server SDK, then shares the hosted URL. Read the payment links guide and the payment-links SDK reference for the lifecycle and exact CRUD signatures.

​
Never fulfil from the browser

Never fulfil from onSuccess, a redirect, a session id, a requested amount, or a payer-claimed transaction hash. Use a signed webhook as a prompt and a server-side status read as the authority. A no-backend merchant uses the Dashboard’s payment-confirmed view; an email is only a prompt to check it. The exception states duplicate, late, and out-of-bounds can mean funds moved, but none is a normal payment to fulfil automatically. The SDK’s payments.* API sends a secret key and, when window exists, throws; that runtime boundary is part of the method choice, not just a documentation recommendation.

​
What is not a promise

This is a capability boundary, not a routing statement. The publishable-key path being gated says nothing about which chains Hypermid can route for a server-created session. The rule remains: any wallet provider works on chains where Hypermid supports that wallet’s signing standard.