Sign in with HEVN

Sign in with HEVN is a HEVN-hosted popup. In it your customer links a HEVN account to your integrator account, approves a payout, or verifies their identity. Create a session with POST /dapi/v1/connect/sessions and open its url in the popup. The holder signs in with Google or a one-time email code. The window shows no separate consent screen and no HEVN product screens.

Configure the window

In the HEVN app, open Settings → Partner program → Developer. In the Sign-in window card, Allowed sites lists the origins the window may return to.

An origin is https://host, or http://localhost:<port> and http://127.0.0.1:<port> in development, with no path or query.
The list holds up to 20 origins. An empty list allows no session.
Removing an origin stops the sessions already issued for it.
HEVN sets the title, logo, colours and theme on request. The API and the session URL cannot change them.

Serve one static callback page from an allowed origin. Until HEVN activates your integrator account, POST /dapi/v1/connect/sessions and POST /dapi/v1/clients/link return 403 client_creation_not_enabled.

Link an account

Open an empty window in the click handler, before any await, then navigate it to the session url. Browsers block a popup opened later.

Browser

button.addEventListener("click", async () => {
  const popup = window.open("about:blank", "hevn-connect", "popup,width=460,height=720");
  if (!popup) return showError("Allow pop-ups for this site to sign in.");

  const { url } = await (await fetch("/hevn/link/start", { method: "POST" })).json();
  const result = await hevnResult(url, popup);
  if (result.error) return showError(result.error);

  await fetch("/hevn/link/finish", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ code: result.code, state: result.state }),
  });
});

2. Create a session

Call POST /dapi/v1/connect/sessions from your server with your access token, without X-Hevn-Account. The action values and field rules are in Create a sign-in window session.

curl -X POST "$HEVN_API/connect/sessions" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"link","redirectUri":"https://app.example.com/hevn/callback"}'

session = hevn.post("/connect/sessions", {
    "action": "link",
    "redirectUri": "https://app.example.com/hevn/callback",
})

const session = await hevn.post("/connect/sessions", {
  action: "link",
  redirectUri: "https://app.example.com/hevn/callback",
});

session, err := api.Post("/connect/sessions", hevn.Body{
	"action":      "link",
	"redirectUri": "https://app.example.com/hevn/callback",
})

Response 201

{
  "url": "https://sandbox.gethevn.com/connect?session=eyJhbGciOiJFUzI1NiIs…",
  "state": "pQ8v2Zr0cJ3mX7tLkN1wA5yHs9dE4fBq",
  "expiresAt": "2026-09-17T10:14:11Z"
}

HEVN signs url and binds it to your integrator account, the action, the payout or client, and redirectUri. It also binds a one-time nonce, returned as state.

3. Bind the session to this browser

Store state in an HttpOnly cookie when you create the session. Accept a code only when the browser returns the same state with that cookie.

Node

app.post("/hevn/link/start", async (req, res) => {
  const session = await hevn.post("/connect/sessions", {
    action: "link",
    redirectUri: "https://app.example.com/hevn/callback",
  });
  res.cookie("hevn_link", sign({ state: session.state }), {
    httpOnly: true, secure: true, sameSite: "lax", path: "/hevn/link", maxAge: 10 * 60_000,
  });
  res.json({ url: session.url });
});

4. Exchange the code

Exchange the returned code from your server with POST /dapi/v1/clients/link. Its validity and retry rules are in Connect an existing account.

curl -X POST "$HEVN_API/clients/link" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"eyJhbGciOiJFUzI1NiIs…"}'

client = hevn.post("/clients/link", {"code": code})

app.post("/hevn/link/finish", async (req, res) => {
  const attempt = verify(req.cookies.hevn_link);
  res.clearCookie("hevn_link", { path: "/hevn/link" });
  if (!attempt || !timingSafeEqual(attempt.state, req.body.state)) {
    return res.status(400).json({ code: "state_mismatch" });
  }
  const client = await hevn.post("/clients/link", { code: req.body.code });
  req.session.clientId = client.id;
  res.json({ signedIn: true });
});

client, err := api.Post("/clients/link", hevn.Body{"code": code})

Response 200

{ "id": "cl_7YQ2Kf3mN8", "status": "ready", … }

The response is the client record. Store id on your server and send it in X-Hevn-Account. Do not accept it from the browser. On 400 link_code_invalid or 410 link_code_expired, start a new sign-in. Do not retry 409 client_already_linked.

Pass a known email

To sign the holder in with an email you hold, add login_hint to the session URL. Do it before you navigate the popup.

Browser

const opened = new URL(url);
opened.searchParams.set("login_hint", "[email protected]");
popup.location.href = opened.toString();

The window sends a one-time code to that address, and the holder cannot change it. login_hint is not signed and does not prove who signed in. POST /dapi/v1/clients/link returns the account that did.

The callback page

The window finishes by navigating to redirectUri with state and the result in the query string.

Session	Query parameters
`link`	`code`
`sign`	`status`, `payout`, `reference`
`verify`	`status`
Refused	`error`

The callback page posts the query to the opener over a BroadcastChannel, because window.opener is null after Google sign-in.

callback.html

<!doctype html>
<meta charset="utf-8">
<title>Signing in…</title>
<script>
  const result = Object.fromEntries(new URLSearchParams(location.search));
  if (result.state) {
    const channel = new BroadcastChannel("hevn-connect");
    channel.postMessage({ state: result.state, result });
    channel.close();
    window.close();
  }
</script>

The opener resolves on the result whose state matches its session.

Browser

function hevnResult(url, popup, timeoutMs = 10 * 60_000) {
  const token = new URL(url).searchParams.get("session");
  const body = token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/");
  const { nonce } = JSON.parse(atob(body.padEnd(Math.ceil(body.length / 4) * 4, "=")));
  const channel = new BroadcastChannel("hevn-connect");
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => { channel.close(); reject(new Error("timeout")); }, timeoutMs);
    channel.onmessage = ({ data }) => {
      if (data?.state !== nonce) return;
      clearTimeout(timer);
      channel.close();
      resolve(data.result);
    };
    popup.location.href = url;
  });
}

A BroadcastChannel reaches pages of one origin, so serve the callback page from the opener’s origin. Matching state in the browser routes the result and does not authenticate it. The cookie check in step 3 does.

hevn-inc/dapi-sdk has this browser code as HevnConnect. The repository is a reference and is not a supported package.

Who can be linked

An account can be linked only if it was created in the sign-in window. The window signs out any HEVN session in the browser before each link sign-in, so the holder chooses the account.

The person signing in	Result
Has no HEVN account	A new account and a `code`.
Is already linked to you	A new `code` for the same client. Use this to log a returning customer in.
Has a HEVN account not created in the window	Refused with `already_registered`. The window offers to open HEVN.
Is linked to another integrator	Refused with `already_linked`.

The window names your product. It tells the holder that you can see balances, request virtual accounts and prepare transfers. It also says that the holder approves each transfer in the window.

Approve a payout

A payout booked for a linked client returns authorization: "client", and the holder signs it. Create a sign session with the call from step 2 and open the popup as for a link.

POST /dapi/v1/connect/sessions

{
  "action": "sign",
  "payoutId": "po_6d21…",
  "redirectUri": "https://app.example.com/hevn/callback"
}

The route returns 404 payout_not_found when the payout does not belong to a client linked to you. It returns 409 payout_not_awaiting_signature when the payout is no longer awaitingSignature. The holder signs in, or reuses a HEVN session open in that browser. The window shows the amount, the contact’s name and who requested the payout. The holder’s wallet signs the debit. The callback receives status=submitted, payout=po_… and, when the debit was sent, reference. If the payout was no longer waiting when the window opened, nothing is signed. The callback receives its current status. Do not act on the redirect. Read GET /dapi/v1/payouts/{payoutId} with the client in X-Hevn-Account and follow it to settled (Money movement).

Verify an individual

A linked individual verifies their identity in a verify session. HEVN does not issue a verification link to you. A business client verifies through KYB. Create a verify session when a virtual account has the verification_required blocker, and open the popup as for a link.

curl -X POST "$HEVN_API/connect/sessions" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"verify","clientId":"cl_7YQ2Kf3mN8","redirectUri":"https://app.example.com/hevn/callback"}'

session = hevn.post("/connect/sessions", {
    "action": "verify",
    "clientId": client_id,
    "redirectUri": "https://app.example.com/hevn/callback",
})

const session = await hevn.post("/connect/sessions", {
  action: "verify",
  clientId,
  redirectUri: "https://app.example.com/hevn/callback",
});

session, err := api.Post("/connect/sessions", hevn.Body{
	"action":      "verify",
	"clientId":    clientID,
	"redirectUri": "https://app.example.com/hevn/callback",
})

The route returns 404 client_not_found for a client that does not exist or is not linked to you. It returns 409 verification_not_applicable for a business client. For a verified client, the window says so and returns status=approved. The identity check runs in the window. When the holder finishes or closes it, the callback receives status.

`status`	Meaning	Next
`approved`	Verified.	Read the client.
`inReview`	Submitted and under review.	Poll the client.
`actionRequired`	Something is missing.	Open a new `verify` session when the holder is ready.
`rejected`	Refused.	n/a
`notStarted`	The holder left before submitting.	Open a new `verify` session.

A review can finish after the window closes. Poll verifiedAt on GET /dapi/v1/client, or poll GET /dapi/v1/banks/{product}. In the sandbox the window accepts test documents. In automated tests, verify an individual with POST /dapi/v1/sandbox/kyb/status.

Errors

The window returns a refusal as error on the redirect. API errors are in the error reference. A session that is invalid or expired when it opens sends no result. The window shows “This link has expired or is invalid”. Stop waiting at expiresAt and close the popup.

`error`	Cause	Next
`access_denied`	The holder cancelled.	Let them try again.
`already_registered`	The Google account has a HEVN account not created in the window.	Ask the customer to use another Google account.
`already_linked`	The account is linked to another integrator.	Do not retry.
`account_mismatch`	`verify`: the holder signed in to an account other than the session’s client.	Ask the holder to use the linked account.
`not_found`	`sign`: the holder does not hold the payout, or it is not linked to you. Usually the wrong Google account.	Ask the holder to use the linked account.
`unsupported`	The payout cannot be approved in the window.	See Approve the payout.
`expired`	The session expired while the holder was in the window.	Create a new session.
`failed`	Any other failure.	Create a new session.

HEVN Connect

Sign in with HEVN

Configure the window

Link an account

2. Create a session

3. Bind the session to this browser

4. Exchange the code

Pass a known email

The callback page

Who can be linked

Approve a payout

Verify an individual

Errors

Next: Money movement

Configure the window

Link an account

1. Open the popup

2. Create a session

3. Bind the session to this browser

4. Exchange the code

Pass a known email

The callback page

Who can be linked

Approve a payout

Verify an individual

Errors

Next: Money movement