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

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

⚠️

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

❗️

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

Pre-filled user data

Widget customization