Theming

The widget’s look is driven by CSS custom properties (tokens). A theme is a set of values for those tokens, stored on your account as a style. Your account can hold several styles. One of them is the default, and you can pick a different one for each session. The widget applies the style at runtime, with no rebuild and no per-partner deploy.

How it works

Send your Ripio contact the values you want to change, or manage your styles yourself. Anything you leave out keeps its default. A minimal theme is small:

{
  "tokens": {
    "--ripio-color-primary": "#EC0000",
    "--ripio-btn-border-radius": "24px",
    "--ripio-font-family": "\"Ubuntu\""
  }
}

The widget receives the theme when it starts. It writes the tokens as custom properties on :root, and they inherit into its Shadow DOM.

Styles live on your account, and your server picks one per session with the style field of POST /auth. There’s no query parameter for it, so an end user can’t switch it from the browser. You can also override tokens yourself at the document level; see Overriding tokens from your page.

Several styles on one account

Use several styles when one account opens the widget from more than one place that needs its own look. For example, a web home banking and a mobile app that each carry their own brand. Every style shares the same account: the same users, balances, limits, currency and webhooks. Only the look changes. Each style has a slug: 1 to 50 lowercase letters, digits or hyphens, starting with a letter or digit. One style can be the default.

Picking a style. Send its slug as style when you request the session code:

{
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "external_ref": "<your-user-id>",
  "kyc_submission": {...},
  "style": "mobile-app"
}

No style. The session uses your default style. If your account has no style at all, the widget uses Ripio’s default theme.
Unknown slug. POST /auth answers 400 with code 20014 and starts no session, so a typo shows up during your integration instead of in front of your users.
Style deleted mid-session. If you delete a style while sessions that picked it are still open, those sessions switch to your default style. They don’t end.

Managing your styles through the API

Your server can create, update and delete your styles itself, server-to-server. These endpoints use a partner token instead of a session. 1. Request a partner token with your credentials. Writing needs the styles:write scope; a token without it can only read. Endpoint: https://b2b-crypto-widget-api.sandbox.ripio.com/api/v1/partner/token Method: POST · Content-Type: application/json

curl \
  --location --request POST 'https://b2b-crypto-widget-api.sandbox.ripio.com/api/v1/partner/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<client_id>",
    "client_secret": "<client_secret>",
    "scope": "styles:write"
  }'

{
  "access_token": "<partner-token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "partner:read styles:write"
}

Send it as Authorization: Bearer <partner-token> on the calls below. It lasts 15 minutes. Like client_secret, it must never reach the browser. 2. Call the styles endpoints:

Method	Path	Scope	What it does
`GET`	`/api/v1/partner/styles`	any	Lists your styles.
`GET`	`/api/v1/partner/styles/{slug}`	any	Returns one style.
`PUT`	`/api/v1/partner/styles/{slug}`	`styles:write`	Creates the style (`201`) or replaces it (`200`).
`DELETE`	`/api/v1/partner/styles/{slug}`	`styles:write`	Deletes the style (`204`).

The PUT body:

Field	Type	Description
`theme`	object	The theme, as `{"tokens": {...}}` with the supported tokens. It replaces the style’s whole theme: a token you leave out goes back to its default.
`name`	string (optional)	A label for your own reference, up to 100 characters. The widget never shows it.
`is_default`	boolean (optional)	`true` makes this style your default and unsets the previous one. Leave it out to keep what the style already was.

curl \
  --location --request PUT 'https://b2b-crypto-widget-api.sandbox.ripio.com/api/v1/partner/styles/mobile-app' \
  --header 'Authorization: Bearer <partner-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Mobile app",
    "theme": {"tokens": {"--ripio-color-primary": "#0DD6A8", "--ripio-btn-text-color-primary": "#1E1E1E"}}
  }'

Every endpoint answers a style, or a list of them, in this shape:

{
  "slug": "mobile-app",
  "name": "Mobile app",
  "is_default": false,
  "theme": {"tokens": {"--ripio-color-primary": "#0DD6A8", "--ripio-btn-text-color-primary": "#1E1E1E"}},
  "updated_at": "2026-10-16T14:02:11.418Z"
}

Idempotent. Repeating a PUT or a DELETE has the same effect, so you can retry either one safely.
Validated. A token outside the supported list, or a value outside its accepted kind, answers 400 with code 20000 and one message per invalid token. Nothing is saved.
Default protected. Your default style can’t be deleted or switched off directly (400, code 20015). To change it, make another style the default with PUT … {"is_default": true}.
Limited. An account can hold up to 20 styles (400, code 20016 for a new one past the limit).
Scope required. A write with a token that lacks styles:write answers 403, code 40012.
Takes effect on new sessions. A change applies the next time the widget starts with a new session code. Open sessions keep the style they started with until they renew.

Supported tokens

These are the tokens your account theme can set. Any other name is rejected when the theme is loaded, so a theme built on these keeps working as the widget’s internals change. Brand

Token	Default	Controls
`--ripio-color-primary`	`#7839ee`	Brand color: primary buttons, links, focus, selection, charts
`--ripio-bg-brand-solid-hover`	primary, 15 % darker	Primary button hover
`--ripio-btn-text-color-primary`	`--ripio-color-base`	Text on primary buttons
`--ripio-color-primary-light`	primary at 7 % over the base color	Tinted brand backgrounds: tertiary buttons, selected options

Setting --ripio-color-primary alone is enough for a coherent theme: the hover and the tinted backgrounds are derived from it. Set them explicitly only when your brand guide defines them. Surfaces and text

Token	Default	Controls
`--ripio-color-base`	`#ffffff`	Base surface color
`--ripio-bg-secondary`	gray 50	Secondary surfaces: action tiles, segmented controls
`--ripio-border-primary`	gray 200	Borders of cards, inputs and the widget’s frame
`--ripio-text-primary`	`--ripio-color-text`	Main text
`--ripio-text-secondary`	gray 700	Secondary text and inactive tabs
`--ripio-color-text`	gray 900	Default text color
`--ripio-widget-bg-color`	`--ripio-color-base`	Widget container background
`--ripio-widget-border-color`	`--ripio-border-primary`	Widget container border

Status and neutrals

Token	Default	Controls
`--ripio-color-success`	success 600	Success states
`--ripio-color-warning`	warning 600	Warning states
`--ripio-color-error`	error 600	Error states
`--ripio-color-info`	gray 200	Neutral informational states
`--ripio-color-disabled`	gray 100	Disabled backgrounds
`--ripio-color-neutral`, `--ripio-color-neutral-10/20/50/80/100/120`	gray scale	Neutral ramp used across surfaces and secondary text

Shapes and spacing

Token	Default	Controls
`--ripio-btn-border-radius`	fully rounded	Buttons
`--ripio-card-border-radius-base`	`12px`	Cards and lists (your assets, activity, market)
`--ripio-input-border-radius`	`8px`	Inputs and menu options
`--ripio-chip-border-radius`	fully rounded	Chips and badges
`--ripio-widget-border-radius`	`16px`	Widget container corners
`--ripio-widget-padding`	`24px`	Widget container padding
`--ripio-widget-gap`	`16px`	Spacing between the widget’s sections

Typography

Token	Default	Controls
`--ripio-font-family`	`"Lato"`	Typeface for the whole widget

Accepted values

Each token accepts one kind of value. Anything else is rejected, including CSS functions, url(), @import, comments and anything that isn’t a plain value.

Kind	Accepted	Examples
Color	`#RGB`, `#RRGGBB`, `#RRGGBBAA`, `rgb(r, g, b)`, `rgba(r, g, b, a)`	`#EC0000`, `rgba(0, 0, 0, 0.5)`
Length (radius, padding, gap)	`0`, or a non-negative number in `px`, `rem` or `%`	`8px`, `999px`, `1.5rem`
Font	One of the supported fonts, as a quoted CSS string	`"Nunito Sans"`

Fonts

The widget ships and serves its own fonts, so you don’t load anything and your page’s CSP doesn’t need a third-party font host. --ripio-font-family accepts one of:

Font	Weights
`"Lato"` (default)	400, 700
`"Libre Franklin"`	400, 700
`"Ubuntu"`	400, 700
`"Nunito Sans"`	400, 700
`"Source Sans 3"`	400, 700

The widget only downloads the family it’s using. If your brand needs a typeface that isn’t on the list, talk to your Ripio contact: fonts are added to the widget, never loaded from your side.

Overriding tokens from your page

You can also set tokens yourself with CSS custom properties on your page’s :root. The order of precedence is:

The widget’s defaults.
Your page’s :root, which overrides the defaults.
The session’s style, which overrides both.

:root {
  --ripio-color-primary: #034cf5;
  --ripio-widget-border-radius: 16px;
}

From your page you can reach the design system’s other tokens as well: per-component tokens such as --ripio-btn-*, --ripio-input-*, --ripio-card-*, --ripio-chip-*, --ripio-toast-* and --ripio-overlay-*, and the radius, shadow and type scales. They belong to the design system and may be renamed as it evolves, so prefer the supported tokens where they’re enough.

What not to override

The design-system primitives (--violet-*, --gray-*, --error-*, --warning-*, --success-*) and the transaction status-chip tokens --st-* are internal. They’re the raw palette the semantic tokens are built from, they aren’t part of the contract, and they can change without notice. Override the semantic layer instead.

Theming only repaints the widget. It can’t reposition, resize or hide anything inside it. The widget’s own classes, such as .btn-primary, live inside its Shadow DOM and your page’s selectors can’t reach them: use the tokens.

Overview

Crypto Widget

API Integration

How it works

Several styles on one account

Managing your styles through the API

Supported tokens

Accepted values

Fonts

Overriding tokens from your page

What not to override

Before and after

​How it works

​Several styles on one account

​Managing your styles through the API

​Supported tokens

​Accepted values

​Fonts

​Overriding tokens from your page

​What not to override

​Before and after

How it works

Several styles on one account

Managing your styles through the API

Supported tokens

Accepted values

Fonts

Overriding tokens from your page

What not to override

Before and after