Fiat Onramp

📄 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:

  1. Create a session via API, including all necessary transaction and user details
  2. 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.

Create session

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

Endpoint
Sandboxhttps://partner-sandbox.wert.io/api/external/hpp/create-session
Productionhttps://partner.wert.io/api/external/hpp/create-session

You will need your API key, which is only provided to you by Wert when we welcome you on board. You will need to make sure to keep this safely in your backend. Your API key should never be shared; if you suspect your key may have been compromised, please let us know so we can issue you a new one.

Parameters

Property Required Description Data Type Default value Possible values

flow_type

Yes

Determines widget behaviour and available functions for the user.
Simple: Users choose
simple_full_restrict: Partner defined options

string

simple_full_restrict

simple
simple_full_restrict

phone

No

User’s phone number in international format (E. 164 standard). The ‘+’ is optional.

string

-

+11014321111

userID

No

The User ID for the associated profile

string

-

01KQWHEJNSY

commodity

On simple_full_restrict flow

Default crypto asset that will be selected in the module.

string

BTC

See Supported coins and blockchains

network

On simple_full_restrict flow

Network for the default crypto asset.

string

bitcoin

See Supported coins and blockchains

wallet_address

On simple_full_restrict flow

User’s wallet address. It is validated based on the chosen commodity. If the address is invalid, this option is ignored. BTC address format is used as default.

string

BTC

commodity_amount

On simple_full_restrict flow

The default crypto amount that will be pre-filled in the module. This option is ignored if currency_amount is set.

numeric

-

-

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

currency

On simple_full_restrict flow

Your choice of fiat currency. EUR is not available in sandbox environment.

string

-

USD, EUR

currency_amount

On simple_full_restrict flow

The default amount, in fiat, which will be pre-filled in the module.
The minimum value is $1 except for BTC which is $30

numeric

-

-

extra

No

Passing multiple wallet addresses to the widget

string

-

See Multiple addresses

⚠️

You can only provide either the 'phone' parameter or the 'userID' parameter, but not both. Similarly, you can specify either 'commodity_amount' or 'currency_amount', but not both simultaneously.

Examples

Simple

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
}'

simple_full_restrict

 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_full_restrict",
  "phone": "+12024561111",
  "wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "currency": "USD",
  "commodity": "TT",
  "network": "amoy",
  "currency_amount": 100.50
}'

In sandbox, please use only USD and sandbox commodities

ℹ️

If you use phone parameter, it must be a valid phone number, even in sandbox.


Responses

Response Code Response Message Response Body

200

OK

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

400

Missing required fields

{
"message": "Invalid request: wallet_address and either commodity_amount or currency_amount must be specified."
}

401

Unauthorized request

{
"message": "Unauthorized: API key is missing or invalid."
}

❗️

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


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. Can be used to help you reconcile the order on your side.

string

click_id

uuid_v4()Can be anything but try to avoid using special characters like % or pass them encoded to avoid parsing issues.

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

listeners

No

You can use this if you want to listen to some module events and react to them.

object

-

See the listeners object.

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

-

Main street 1

Property Required Description Data Type Default value Possible values

lang

No

Language of the widget.

string

en

en - for English
fr - for French
ja - for Japanese
es - for Spanish
ko - for Korean
zh - for Chinese

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