📄 Session-Based Integration

Wert’s fiat onramp is initialised through a session-based integration flow, designed to give you full control over the transaction experience.

This flow consists of two simple steps:

Create a session via API, including all necessary transaction and user details
Initialise the widget using the session_id returned from the API

This allows you to tailor how the onramp behaves — from fully user-driven to fully preconfigured — depending on your use case.

1. Create session

📘
Please click on the dropdown below to see how to create session_id from our API.

Create Session Instruction

To start the widget, you must create a new session via our Partner API. The available endpoints for this are:

Environment	URL	Method
`Sandbox`	`https://partner-sandbox.wert.io/api/external/hpp/create-session`	`POST`
`Production`	`https://partner.wert.io/api/external/hpp/create-session`	`POST`

API Keys

⚠️
Your API Key carries many privileges, so be sure to keep it secure!
Your API key is provided exclusively by Wert during onboarding. Store this safely in your backend.
Never share your key; if you suspect a compromise, contact us immediately to issue a new one.
Note: Sandbox and Production keys are unique to their respective environments and are not interchangeable.

Parameters

💡
flow_type: simple_full_restrict ensures all parameters are locked and cannot be edited by users.

Property	Required	Description	Data Type	Default value	Possible values
flow_type	Yes	Determines widget behaviour. simple: Users choose. simple_full_restrict: Partner defined options.	string	simple	simple, simple_full_restrict
user_id	No	The User ID for the associated profile	string	-	01KQWHEJNSY
commodity	*	Default crypto asset selected.	string	BTC	See docs
commodity_amount	*	Pre-filled crypto amount (ignored if currency_amount set).	numeric	-	-
network	*	Network for the default asset.	string	bitcoin	See docs
wallet_address	*	User’s wallet address. Validated based on commodity.	string	-	-
currency	*	Fiat currency (required if currency_amount used). `EUR` is not available in sandbox.	string	-	USD, EUR
currency_amount	*	Pre-filled fiat amount ($1 min / $30 min for BTC).	numeric	-	-

(*) Requirement: All properties marked with an asterisk are required when flow_type is set to simple_full_restrict.
Use either commodity_amount or currency_amount, but not both.

Examples

curl -X POST "https://partner-sandbox.wert.io/api/external/hpp/create-session" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"flow_type": "simple", // flow_type is always required
}'

In sandbox, please use only USD and sandbox commodities

Responses

{
  "sessionId": "string",
  "requestId": "string"
}

❗
The sessionId is valid for 30 seconds after being created and can only be used once.

2. Initialise the widget

You can integrate the Wert Widget into your web app using our SDK, this is the recommended way to initialise the widget. For React projects, we provide this wrapper.

You can find examples of the integration on GitHub.

Once the SDK is installed, you can use the following code snippet to initialize the payment module:

// Import the SDK
import WertWidget from '@wert-io/widget-initializer';
import type { Options } from '@wert-io/widget-initializer/types';

// Initialize the payment module
const options: Options = {
partner_id: 'YourPartnerID',
session_id: 'SessionID', // session id recieved from partner.wert.io/api/
origin: 'https://sandbox.wert.io', // this option needed only in sandbox
}
  
const wertWidget = new WertWidget(options);

wertWidget.open();

// Further code to handle widget events and interactions

Options

Here are the options you can pass to the widget.

General options

Property	Required	Description	Data Type	Default value	Possible values
partner_id	Yes	Provided when you register as a partner.	string	-	-
session_id	Yes	session_id returned from the API	string	-	-
origin	In sandbox	Initializes the module in a sandbox/production environment.	string	https://widget.wert.io	https://sandbox.wert.io
click_id	No	A unique identifier created by you to be used for logging purposes	string	click_id	`uuid_v4()`Can be anything but try to avoid using special characters like % or pass them encoded to avoid parsing issues.
phone	No	User’s phone number in international format (E. 164 standard). The ‘+’ is optional.	string	-	+11014321111
redirect_url	No	It includes a button 'Back to {Partner Name}' on the widget (not available in iFrame mode). It also redirects users from KYC emails to proceed with payment.	Full URL string (with protocol)	-	https://origin.us/item_id
support_url	No	Full url string (with protocol). This link will be used for helping users with failed orders.	Full URL string (with protocol)	-	https://partner.com/support
listeners	No	You can use this if you want to listen to some module events and react to them.	object	-	See the listeners object.
commodities	No	Crypto assets that will be available in the module as a stringified JSON of an array of objects with the commodity and network options.	string	By default, all assets will be displayed.	See Limiting assets on the widget
extra	No	Passing multiple wallet addresses to the widget	string	-	See Multiple addresses
payment_method	No	If set, this method will be pre-selected and shown first in the list of available methods. Other methods will still be available unless payment_method_restriction is used.	string	card	card apple-pay google-pay sepa
payment_method_restriction	No	If true, the widget will show only the method specified in payment_method (if it’s available). If that method isn’t available, the widget will fall back to showing all available methods.	boolean	false	true false
display_currency	No	ISO currency code to display an estimated approximate amount in that currency next to the order amount. Must differ from the currencies supported in the widget.	string	-	AUD, SGD, HKD, THB, MYR, VND
hide_fee_breakdown	No	Hides fee details for all payment methods and only the fee value is shown.	boolean	false	true false

Pre-filled user data

Property	Required	Description	Data Type	Default value	Possible values
country_of_residence	No	User’s country of residence.	string	-	alpha2 code of the country
state_of_residence	No	User’s state of residence (for USA).	string	-	alpha2 code of USA state
date_of_birth	No	User’s date of birth.	string	-	`DD/MM/YYYY` `MM/DD/YYYY` (USA)
email	No	User’s email address.	string	-	[email protected]
full_name	No	The user’s first and last name.	string	-	min 3, max 69 letters; `RegExp(/(\w+\s)\w+/)`
card_country_code	No	card billing address alpha2 country code	string	-	US
card_city	No	card billing address city	string	-	Los Angeles
card_state_code	No	card billing address alpha2 state code (For US)	string	-	CA
card_post_code	No	card billing address postal code	string	-	12345
card_street	No	card billing address street	string	card	Main street 1

Appearance and restrictions

Property	Required	Description	Data Type	Default value	Possible values
lang	No	Language of the widget.	string	en	en - English fr - French ja - Japanese es - Spanish ko - Korean zh - Chinese tr - Turkish
skip_init_navigation	No	By default, the module suggests the nearest purchase route based on given parameters. Setting to ‘true’ skips this logic.	boolean	undefined	true
theme	No	Module’s theme color.	string	undefined	dark
brand_color	No	Custom brand color that affects the following components: primary buttons, tooltips, steppers, tabs, checkboxes, toasts, pie countdowns.	string	-	`#FF0000`