Optional Features

User Pre-Authorization

This section covers two approaches for authenticating users from your backend. Silent Authentication pre-authorizes users before they open the widget — they skip the login step entirely. API-Based Authentication is used exclusively for the Submit Documents KYC flow and does not authenticate users in the widget.

All requests that register or sign in a user below require the Sdk-Partner-Token header. Contact your integration manager to obtain it.

Silent Authentication

Silent authentication lets your users skip the login step in the widget by passing a short-lived token in the URL. Mercuryo handles the authentication on its end — no user credentials are shared with you.

Before using silent authentication, you must obtain the user's consent to Mercuryo's Terms of Service on your side.

⚠️ Be careful: in the API response the field is called init_type_token, while the widget URL parameter is init_token_type — read the value from init_type_token and pass it to the widget as init_token_type.

Silent Sign-Up

For users who don't have a Mercuryo account yet.

Endpoint: POST /v1.6/sdk-partner/sign-up

Lets you register a new Mercuryo user without sending them through the widget's own sign-up form. Use language_code to pre-set the user's widget locale, and share_token to carry over KYC verification already done on your SumSub instance (see KYC) so the user isn't asked to verify again in the widget.

Steps:

  1. Call POST /v1.6/sdk-partner/sign-up to get init_token and init_type_token.
  2. Pass these as init_token and init_token_type URL parameters when redirecting the user to the widget.
  3. Show your widget.
https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID
  &init_token_type=sdk_partner_authorization
  &init_token=0a25dd714163a9006

Silent Sign-Up + SumSub KYC

For users who already have a verified KYC on your SumSub instance.

Same as Sign-Up but also include share_token in the request body:

POST /v1.6/sdk-partner/sign-up
{
  "email": "user@example.com",
  "accept": true,
  "share_token": "_act-ca0dae00-0ecd-000d-00e0-00d0ca000b0d"
}

Widget URL with both tokens:

https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID
  &init_token_type=sdk_partner_authorization
  &init_token=0a25dd714163a9006
  &share_token=_act-ca0dae00-0ecd-000d-00e0-00d0ca000b0d

Silent Sign-In

For users who already have a Mercuryo account.

Endpoint: POST /v1.6/sdk-partner/login

Identify the user by one of email, phone, or user_uuid4.

Steps:

  1. Call POST /v1.6/sdk-partner/login to get init_token and init_type_token.
  2. Pass them as init_token and init_token_type URL parameters.
  3. Show your widget.
https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID
  &init_token_type=sdk_partner_authorization
  &init_token=0a25dd714163a9006

API-Based Authentication

This approach authorizes the user on your backend, so you can perform actions on their behalf via the API — for example, uploading KYC documents (see Submit Documents via API). Unlike silent authentication, user information is shared with you during the process.

Signing the user in returns an Sdk-User-Token (as bearer_token in the response) — pass it in the header of any subsequent API call made on behalf of that user. It expires in 24 hours in Production and does not expire in Sandbox.

Before signing up, the user must accept the Terms of Service on your frontend. Pass their consent in the accept parameter.

OTP-less Sign-In

For users whose email and identity you've already verified on your side — no additional verification is required.

Endpoint: POST /v1.6/sdk-partner/user/sign-in-no-verify

Steps:

  1. Call POST /v1.6/sdk-partner/user/sign-in-no-verify with the user's email.
  2. Take the bearer_token field from the response and use it as the Sdk-User-Token header value in subsequent requests made on behalf of the user.

Sign-In with OTP Verification

For users who must verify their email via a one-time code.

Endpoints:

Steps:

  1. Call POST /v1.6/sdk-partner/user/sign-in with the user's email. An OTP is sent to the user.
  2. Call POST /v1.6/sdk-partner/user/sign-in/verify with the OTP entered by the user.
    • To resend the OTP: POST /v1.6/sdk-partner/user/sign-in/verify/resend
  3. Take the bearer_token field from the verify response and use it as the Sdk-User-Token header value in subsequent requests made on behalf of the user.

Sign-Out and Session Refresh

Once the user is signed in, you can end their session or refresh it. These endpoints require the Sdk-User-Token header instead of Sdk-Partner-Token:

Previous
Transaction Statuses
Next
KYC & Compliance