Building a frontend on the white-label wallet API

How the white-label system works

The platform is multi-tenant: every partner's data — users, balances, cards, fee configuration — is fully isolated from every other partner's. Your tenant is called a white label, and it is identified by a single string that the platform issues to you at onboarding.

The tenant header

Every request, authenticated or not, must include your tenant identifier in the x-api-key header:

x-api-key: your-whitelabel-id

This header is what scopes every query on the backend: it determines which pool of users a login checks against, which fee schedule applies to a deposit, and which card price list a BIN resolves to. Two different partners can have two different users registered under the same email address, because the account is namespaced by tenant, not globally unique.

What varies per tenant

• Fees — deposit, withdrawal, and card-creation fee percentages are configured per white label (with a platform-wide fallback). You never calculate or submit a fee: every endpoint that touches money returns the net amount after the applicable fee has already been resolved server-side.
• Card pricing — the price and top-up fee for a given card BIN can be overridden per white label, so the same BIN may be priced differently for you than for another partner.
• Branding — every transactional email (OTP codes, deposit/withdrawal/card confirmations, etc.) is sent from templates you design and register yourself in SendPulse — see Set up email templates, the first thing to do before going live.

What does not vary per tenant: supported blockchain networks and tokens are global infrastructure — every partner sees the same active set (see Networks & tokens).

Set up your email templates first

Do this before writing a single line of integration code. Every OTP and account notification described in this guide — registration codes, login codes, password resets, deposit/withdrawal/card confirmations — is delivered through email templates that you design and own in SendPulse, not a shared platform template. Until these are built and submitted, no email in your tenant can be sent — which means no user can complete registration, login, or any OTP-gated action.

1. Create a SendPulse account for your brand (or use an existing one) and verify the sender email address you want your notifications to come from.
2. Generate API credentials. In SendPulse, open the API section of your account settings and generate an API User ID and API Secret — these authorize the platform to send mail through your account on your users' behalf.
3. Build each template below in the SendPulse template editor, using your own branding, copy, and layout. Publish each one and record its numeric template ID.
4. Log in as an admin. Call POST /auth/admin/login with the email/password of a user on your tenant that has admin rights, to get an access token.
5. Submit your configuration. Call POST /admin/whitelabel/:whiteLabelId/email-templates with the admin access token, your SendPulse credentials, and every template ID from the tables below. This is what actually enables POST /auth/otp to deliver mail for your tenant.

Account-level fields

Required templates

The setup call is rejected if any of these are missing:

Recommended templates

Optional — skip only if the related feature won't be exposed in your product. Field names follow the same pattern as the required table above (e.g. depositProcessingTemplateId); if you're ever unsure of an exact key, the setup call's validation error names it for you:

Once POST /admin/whitelabel/:whiteLabelId/email-templates returns success, move on to Authentication model to start integrating.

Authentication model

Two independent credentials travel on every authenticated request: the tenant header described above, and a bearer token that identifies the end user.

The access token is a signed JWT returned by /auth/login. It encodes the user's identity and tenant scope, and is valid for 24 hours. There is no separate session store to check — the token itself is the credential, so treat it like one: keep it in memory or secure storage, never in a location readable by third-party scripts (i.e. avoid localStorage if you can use an httpOnly cookie proxied through your own backend instead).

Alongside the access token, login also returns a longer-lived refresh token (30 days) used solely to mint new access tokens without asking the user to log in again — see Sessions & tokens.

Registration

New accounts are created in two calls: request a one-time code by email, then submit the registration form together with that code. This confirms the email address belongs to the person registering before any account exists.

1. Request an OTP. Call POST /auth/otp with purpose: "register" and the candidate email. The backend checks the email isn't already registered under your tenant and emails a one-time code.
2. Submit registration. Call POST /auth/register with the user's details and the code they received. On success, the account is created — the user still needs to log in afterward; registration does not return a session token.

// 1. Request a one-time code by email
await fetch(`${BASE_URL}/auth/otp`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({ purpose: "register", email })
});

// 2. User enters the code they received, then submit registration
const res = await fetch(`${BASE_URL}/auth/register`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({ firstName, lastName, email, password, otp })
});
const { newUser } = await res.json();
// Registration does not log the user in — send them to the login screen next.

Login & two-factor authentication

Every account has 2FA on by default. A user authenticates with email + password, then confirms a second factor — either a code emailed to them, or a code from an authenticator app, depending on what they've configured.

Recommended UX

1. Collect credentials, check them silently. Call POST /auth/check-credentials with email + password. This validates the password without starting a session, so you can show a real-time error before asking for a second factor.
2. Check whether a code is required. Call POST /auth/login-otp-required with the email. Nearly every account has this on, but it lets you skip the extra field for the rare account that doesn't.
3. Request the code, if needed. Call POST /auth/otp with purpose: "login". If the account uses email 2FA, a code is sent; if it uses an authenticator app, nothing is sent — the user reads the code from their app instead.
4. Submit the full login. Call POST /auth/login with email, password, and the code. On success you receive an access token, a refresh token, and the user's profile.

const headers = { "Content-Type": "application/json", "x-api-key": API_KEY };

// Step 1 — validate credentials before asking for a 2FA code
const check = await fetch(`${BASE_URL}/auth/check-credentials`, {
  method: "POST", headers, body: JSON.stringify({ email, password })
});
if (!check.ok) throw new Error("Invalid email or password");

// Step 2 — send the OTP (no-op email if the account uses an authenticator app)
await fetch(`${BASE_URL}/auth/otp`, {
  method: "POST", headers, body: JSON.stringify({ purpose: "login", email })
});

// Step 3 — complete login once the user has entered their code
const res = await fetch(`${BASE_URL}/auth/login`, {
  method: "POST", headers, body: JSON.stringify({ email, password, otp })
});
const { accessToken, refreshToken, userData } = await res.json();

Choosing a second factor

A logged-in user can switch their 2FA method via PUT /users by setting twoFactorAuthMethod to "email" or "authenticator". When switching to an authenticator app, the user's profile carries the secret needed to render a QR code (or manual entry key) for enrolling in an authenticator app such as Google Authenticator or Authy — display it once during setup and let the user scan it.

The OTP system

A single endpoint, POST /auth/otp, issues one-time codes for every purpose in the product. The purpose field determines what's validated and whether the call requires a bearer token.

Codes are short-lived and delivered by email for accounts on email-based 2FA. Accounts using an authenticator app never receive an emailed code for any purpose above except password reset — always read the current code from the app instead.

Step-up authentication for sensitive actions

A valid bearer token alone is not enough to move money or change security-relevant profile fields. Withdrawals, internal transfers, password changes, and general profile updates all require a fresh OTP submitted with the request itself, on top of the existing session.

Build this into your UI as a deliberate last step rather than an afterthought:

1. User reviews the action (e.g. "Withdraw 100 USDT to 0xabc...").
2. Request the OTP for the relevant purpose (withdrawal, update, or internal-transfer) — this call needs the bearer token.
3. User confirms with the code, and you submit the action endpoint with otp included in the body.

Endpoints that follow this pattern: POST /users/transfer, POST /users/internal-transfer, PUT /users, PUT /users/password.

Password management

Sessions & tokens

Access tokens are short-lived by design (24 hours) so that a stolen token has a bounded blast radius. Refresh tokens exist to renew a session silently in the background.

async function authorizedFetch(path, options = {}) {
  let res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: { ...options.headers, "x-api-key": API_KEY, "Authorization": `Bearer ${accessToken}` }
  });

  if (res.status === 401) {
    const refreshed = await fetch(`${BASE_URL}/auth/refresh-token`, {
      method: "POST",
      headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
      body: JSON.stringify({ refreshToken })
    });
    if (!refreshed.ok) throw new Error("SESSION_EXPIRED");

    ({ accessToken, refreshToken } = await refreshed.json());
    res = await fetch(`${BASE_URL}${path}`, {
      ...options,
      headers: { ...options.headers, "x-api-key": API_KEY, "Authorization": `Bearer ${accessToken}` }
    });
  }
  return res;
}

Profile & assets

Use these two endpoints to populate country/city dropdowns anywhere you collect an address or nationality — most notably the identity verification form. Always fetch cities with the selected country's regionCode rather than loading the full unscoped list, both for a faster picker and to keep the two fields consistent.

Networks & tokens

Supported blockchain networks and tokens are global — every white label sees the same active set. Use this endpoint to build your asset picker rather than hardcoding a list, since it reflects what's actually enabled server-side.

[
  {
    "id": 1, "symbol": "USDT", "name": "Tether USD",
    "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "decimals": 6, "type": "ERC20", "isActive": true,
    "network": { "id": 1, "name": "Ethereum Mainnet", "symbol": "ETH", "isActive": true }
  }
]

Networks currently live in production:

Test networks (Sepolia, Shasta) are available in non-production environments only.

Deposit addresses

Each user is issued a deposit address per blockchain network — not per token — the first time it's requested. One Ethereum-network address can receive both USDT and USDC, for example; you resolve which network to provision by passing any token id on that network.

const res = await authorizedFetch(`/users/wallet/${usdtTokenId}`);
const { walletAddress } = await res.json();
// Render walletAddress as text + QR code for the user to send funds to.

Deposit lifecycle

Deposits are detected automatically once funds arrive at a user's address — there is no endpoint to "notify" the backend of an incoming transfer. Ethereum-network deposits are typically credited within moments of confirmation; Tron-network deposits go through an additional confirmation step before crediting, so may take a little longer. Poll GET /users/deposits or GET /users/assets to reflect the credited balance in your UI.

Each record has a status of waiting, pending, completed, failed, rejected, or refunded, and a type of deposit, withdrawal, card-topup, card-withdrawal, card-creation, referral-reward, or internal-transfer — use these to render a unified activity feed.

Withdrawals & transfers

Card issuance overview

Prepaid cards are created against a BIN (a card product configuration) — list available BINs first, then create a card against one of them. Not every BIN requires a card holder. Whether one is required is controlled entirely by a single field on the BIN, needCardHolder, from GET /cards/bins — check it per BIN and branch your UI on it, rather than assuming one onboarding path fits every card product:

• needCardHolder: false — no card holder step at all. The cardholder's basic details (name, email, date of birth) are submitted directly in the card creation call, and the BIN can be used with no holderId.
• needCardHolder: true — a card holder must exist for that BIN before a card can be created against it. Either pass an already-approved holderId, or omit holderId entirely to let the backend auto-create a lightweight "default" card holder — a simplified fast path that bypasses full identity verification for BINs that allow it (see below).

Identity verification

Required before issuing a card against a BIN with needCardHolder: true (unless using the "default holder" shortcut above). It's a document-upload plus a data form, reviewed asynchronously.

1. Upload documents. Call POST /users/upload-file three times — for the front of the ID, the back of the ID, and a selfie holding the ID — collecting a fileId each time.
2. Submit the verification record. Call POST /users/card-holder with the applicant's personal details and the three file ids.
3. Poll for approval. Call GET /users/card-holder until the record's status indicates it's ready, then use its id as holderId in POST /cards.

Card lifecycle

Affiliate portal

Separate from the main end-user app: a dashboard for users who have been granted affiliate status, letting them onboard referred users and see referral performance. Gated by isAffiliate on the caller's account — building this is only relevant if your product includes an affiliate program.

Affiliate portal login uses the same OTP mechanism with purpose: "portal-login" against POST /auth/otp, followed by the standard POST /auth/login.

Error handling

Errors follow a consistent shape across the API:

{ "error": "Insufficient balance" }
// or, on validation failures:
{ "error": [ { "path": "email", "message": "Invalid email" } ] }

Note that several success responses return HTTP 200 where you might expect 201 (e.g. registration, card creation) — check the response body rather than assuming a status code convention.

Endpoint index

Every partner-facing endpoint in one table, grouped by area.

Auth

Users

Cards

Portal (affiliate accounts only)