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

All four are required on the initial POST.

How template variables work

Every template is one you build and publish in SendPulse. When the platform sends a message it passes a fixed set of merge variables into that template — reference them in your SendPulse content as {{otp}}, {{amount}}, and so on. The subject line is set by the platform, not your template, so design for the body only. Variable names are case-sensitive and exactly as listed below (note Status is capitalised). Any variable your template doesn't reference is simply ignored; referencing one that wasn't passed renders empty.

Authentication & OTP

Delivered to the end user. Every code email carries the same otp variable; withdrawal and transfer codes add context so the user can verify what they're approving.

User money notifications

Delivered to the end user. All optional — configure the ones matching features you expose.

Card funding

Delivered to the end user when a card top-up changes state.

Card creation & cardholder verification

Delivered to the end user. "Custom" = the applicant submitted their own cardholder identity; "default" = the simplified fast-path using a shared default holder.

Account verification (KYC)

Delivered to the end user as their account-level KYC submission is reviewed.

Referral

Ops notifications (to your team)

Delivered to your configured admin email addresses, not to end users. Use them for internal monitoring and manual-review queues.

Affiliate portal

Example: initial setup call

// headers: x-api-key: <your-whitelabel-id>, Authorization: Bearer <admin-access-token>
{
  "apiUserId": "sp_user_xxx",
  "apiSecret": "sp_secret_xxx",
  "sendPulseEmail": "noreply@yourbrand.com",
  "supportName": "YourBrand Support",

  // required templates
  "registrationTemplateId": 100001,
  "loginOtpTemplateId": 100002,
  "forgetPasswordOtpTemplateId": 100003,
  "profileUpdateOtpTemplateId": 100004,
  "withdrawalRequestOtpTemplateId": 100005,
  "referralSignUpTemplateId": 100006,
  "adminDepositNotificationTemplateId": 100007,
  "adminWithdrawalNotificationTemplateId": 100008,
  "adminCardCreationNotificationTemplateId": 100009,

  // optional — add the ones you use
  "depositProcessingTemplateId": 100012,
  "depositConfirmedTemplateId": 100013,
  "withdrawalSuccessNotificationTemplateId": 100014,
  "cardFundingPendingTemplateId": 100015,
  "cardFundingConfirmedTemplateId": 100016
}

To change anything later, PUT the same path with only the fields you're updating — the call is validated as a partial, and untouched fields keep their stored values. Sending null for an optional id is rejected; omit the key instead.

Once the setup call returns success, verify with GET /admin/whitelabel/email-templates, then 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.

Overriding the 2FA method per call

Login, password reset, and every step-up action that accepts an otp also accept an optional otpMethod field ("email" or "authenticator") in the same request body. When present, it tells that one call which kind of code to verify against, regardless of the account's stored default — useful for a user who has an authenticator app set up but wants to fall back to an emailed code for a specific action (or vice versa). Omit it to use the account's stored twoFactorAuthMethod.

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.

The KYC gate

Separate from account KYC submission and cardholder verification, a white label can turn on a blanket identity-verification requirement for every money-moving and account-management action. If your tenant has this on, build it into your onboarding flow deliberately — don't treat it as an edge case.

{ "error": "KYC verification required before you can perform this action", "kycStatus": "not-submitted" }

kycStatus is one of not-submitted, pending, under-review, approved, or rejected, letting you route the user straight to the right screen — a KYC form, a "we're reviewing it" message, or a rejection reason — instead of showing a generic error. Treat any 403 with this shape as a signal to redirect into the KYC submission flow, not as a fatal error.

Whether this gate is active at all is a per-tenant setting controlled by your platform admin; a small number of individual accounts can also be exempted from it directly. Not every white label has it on — check with your onboarding contact, or simply detect it live via the 403 shape above.

Password management

Changing email

Changing the email on an account is a three-step flow: confirm the user still controls the current email (via a code sent to it, or an authenticator code), then confirm they control the new one. This can't be done through PUT /users.

1. Request a code for the current email. Call POST /auth/otp with purpose: "verify-email" (skip this if the user authenticates with otpMethod: "authenticator" instead).
2. Verify ownership of the current email. Call POST /users/email/verify with the code. This unlocks the next step but doesn't change anything yet.
3. Request a code for the new email. Call POST /auth/otp with purpose: "change-email" and the candidate new address.
4. Submit the change. Call PUT /users/email with the new email and that code.

Authenticator app 2FA

Beyond switching the stored 2FA method via PUT /users, dedicated endpoints manage the authenticator app itself — setting it up, confirming it, and removing it.

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 account KYC and cardholder verification forms. 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.

What GET /users actually returns

Beyond the stored profile columns, the response is enriched server-side on every call — don't assume it's a flat mirror of the database row:

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

Token swaps

Separate from a plain external withdrawal, a user can swap one supported token for another and withdraw the result. A swap is tracked as its own record with a lifecycle you drive explicitly — it doesn't start moving funds until you call the start endpoint.

GET /users/dex-transactions/:id/start and .../withdraw both 404 if the transaction doesn't belong to the caller, so there's no need to filter by user yourself beyond passing the right id.

Cashback

Some card BINs carry a cashback rate on deposit volume. Use this endpoint to show a user what they're eligible for before they commit to a top-up.

Statements

Generate a downloadable activity statement, either for the user's whole account or for one card.

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).

Subscription-priced cards

Some tenants price card creation through subscription packages rather than a flat per-BIN fee. Check subscriptionEnabled on GET /users before assuming either model — the two are mutually exclusive for a given tenant.

Use the package's id from GET /cards/subscriptions as packageId when calling POST /cards — pick packages scoped to the target binId only.

Cardholder 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. This verifies a specific cardholder identity for card issuance — it's separate from the account-level KYC submission some tenants require just to use the platform at all.

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.

Account KYC submission

This is the account-level verification checked by the KYC gate — it's distinct from cardholder verification, which is scoped to a specific card product. Only relevant for tenants that have the KYC gate enabled.

Card lifecycle

Revealing card details

As an alternative to GET /cards/info/:cardId — where the full PAN and CVV travel straight into your own frontend's memory — this flow hands you a short-lived, one-time link to a hosted page that displays the sensitive details itself. Embed that link in an iframe rather than parsing the data out of your own API response.

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.

Your own back office

Beyond the email-template setup covered earlier, a set of /admin/* endpoints is available to an account with admin rights on your own tenant — useful for building an internal ops dashboard for your own team, scoped to your own users. Everything here requires POST /auth/admin/login first; use the resulting access token as the bearer token, same as the email-template setup call.

Two kinds of access control

Every call below needs a bearer token from an admin account on your tenant. Some additionally require that account to hold a specific permission, or to be flagged as your tenant's super-admin:

• Permission-gated — the account needs a specific permission key (listed per endpoint below) assigned to it, unless it's the super-admin. GET /permissions lists every valid key; GET /roles / POST /roles / PUT /roles/:roleId let you define roles bundling permission keys and assign them to your team's accounts.
• Super-admin only — the account must be flagged as your tenant's super-admin specifically; holding every individual permission key isn't equivalent. A super-admin automatically passes every permission check too.

Deposits & transactions

Users

Cards

Referrals & KYC review

Tenant settings

Card products & subscription packages

Manage your tenant's own pricing on top of the platform's card products — see Card issuance overview and Subscription-priced cards for how these surface to end users.

Coupons

Coupons let you override pricing and referral eligibility for a specific group of users on your tenant — see the couponId references in card creation and subscriptions for how a coupon affects what an end user is actually charged.

Admin roles & permissions

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

Statements

Portal (affiliate accounts only)