Widget Integration

This section details the “Low-Code” integration path using the embeddable Nomad Pay Widget.

Overview

The Nomad Pay Widget allows you to securely embed a crypto wallet connection and payment flow directly into your website. It supports two primary functions via a single SDK:

Payment Mode: Handle the entire checkout flow using a payment ID.
Connect Mode: Connect a user’s wallet and request a signature (e.g., for login or verification).

Installation

Option A: CDN (Script Tag)

Add the following script to the <head> or body of your website. Production URL:

<script defer async src="[https://widget.nomadpay.io/index.js](https://widget.nomadpay.io/index.js)"></script>

Option B: NPM/Yarn

Package details coming soon.

Basic Usage: Payment

This is the standard flow to collect a payment. Prerequisite: You must first call the backend API (POST /v1/payments) to generate an integration ID (also known as payment_id).

Step 1: Prepare a Container

Create a DOM element where the widget will be mounted.

<div id="nomad-pay-container"></div>

Call NomadPayWidget.Connect() with your configuration.

// Ensure the script is loaded before calling
if (window.NomadPayWidget) {
    NomadPayWidget.Connect({
      // 1. Required: The Payment ID from your backend
      integration: 'b817c5e2-d6de-40b3-aefc-176d7a49ed4b',
    
      // 2. Required: Mount point
      container: document.getElementById('nomad-pay-container'),
    
      // 3. Environment: Set to true for Sandbox/Test mode
      isDev: false, 
      
      // 4. Callbacks
      onSuccessCallback: (data) => {
        console.log('Payment Success!', data);
        // e.g., redirect to your success page
      },
      onErrorCallback: (error) => {
        console.error('Payment Error:', error);
      },
      closed: () => {
        console.log('Widget modal was closed.');
      }
    });
}

Usage: Connect Wallet & Sign

If you only want to connect a user’s wallet and get a signature (without creating a payment order), initialize the widget without the integration parameter and set autoSignOnConnect to true.

Example:

NomadPayWidget.Connect({
  container: document.getElementById('nomad-pay-container'),
  
  // Set to true to request a signature after connection
  autoSignOnConnect: true, 
  
  // Optional: Restrict chains for connection
  supportedChains: ['ethereum', 'solana'],

  onSuccessCallback: (data) => {
    // 'data' will contain the wallet address and signature
    console.log('Connect & Sign Success!', data);
  },
  closed: () => {
     console.log('Connect modal closed.');
  }
});

Configuration Parameters

You can customize the behavior and look of the widget using the following parameters.

Core Parameters

Parameter	Type	Required	Description
`integration`	`string`	Payment Mode	The Payment ID returned by the Nomad Pay server. Required for payment flow.
`container`	`HTMLElement`	Yes	The DOM element to mount the widget.
`isDev`	`boolean`	No	Default `false`. Set to `true` to connect to the Test Environment.
`document`	`Document`	No	The document object, useful if working inside iframes.
`closeable`	`boolean`	No	Default `true`. Whether the widget can be closed by the user.
`showPrice`	`boolean`	No	Default `true`. Whether to display the order price header.
`autoSignOnConnect`	`boolean`	No	Connect Mode Only. If `true`, the widget will request a signature after connecting. Default `false`.

Chain Customization

Use these only if you need to restrict chains or use custom RPC endpoints.

Parameter	Type	Description
`supportedChains`	`Array<string>`	A list of chains to support. Default includes all: `['ethereum', 'solana', 'ton', 'tron', 'bsc', 'polygon', 'arbitrum', 'optimism', 'base', 'avalanche', 'unichain', 'plasma']`.
`customEvmEndpoints`	`object`	Custom RPC URLs for EVM chains. Example: `{ ethereum: 'https://...' }`
`customSolanaEndpoint`	`string`	Custom RPC URL for Solana.
`customTonApiUrl`	`string`	Custom API URL for TON network.
`customTonManifestUrl`	`string`	Required if using TON. URL to your DApp’s `manifest.json`.
`projectId`	`string`	Required for WalletConnect. Your WalletConnect Cloud Project ID.

Internationalization

Parameter	Type	Description
`i18nConfig`	`object`	Configuration object for languages.
`i18nConfig.initialLocal`	`string`	Initial language (e.g., `'en'`, `'zh'`). Default `'en'`.
`i18nConfig.fallbackLocale`	`string`	Fallback language if translation is missing.
`i18nConfig.customTranslations`	`object`	Custom translation strings.

Callbacks & Response Data

onSuccessCallback

Triggered when the payment or connection is successful. The data object contains details about the connected wallet and signature. Data Structure:

onSuccessCallback: (data) => {
  // Example Data
  // {
  //   blockchainType: 'evm', // 'evm' | 'solana' | 'ton' | 'tron'
  //   wallet: { ... },       // Wallet provider details
  //   accountData: {
  //     address: "0x123...", // Connected wallet address
  //     chainId: 1,
  //     signature: "0xabc...", // Cryptographic signature
  //     message: "Sign this message...",
  //     // Chain-specific fields (e.g., for TON/Solana)
  //     publicKey: "...", 
  //     friendlyAddress: "...",
  //   },
  //   disconnectWallet: Function // Helper to disconnect
  // }
}

Other Callbacks

Callback	Description
`onErrorCallback`	`(error) => void`. Triggered when an error occurs.
`onCloseCallback`	`() => void`. Triggered when the modal is closed.

Welcome

Merchant User Guide

Developer Documentation

Widget Integration

Overview

Installation

Option A: CDN (Script Tag)

Option B: NPM/Yarn

Basic Usage: Payment

Step 1: Prepare a Container

Step 2: Initialize the Widget

Usage: Connect Wallet & Sign

Example:

Configuration Parameters

Core Parameters

Chain Customization

Internationalization

Callbacks & Response Data

onSuccessCallback

Other Callbacks

​Overview

​Installation

​Option A: CDN (Script Tag)

​Option B: NPM/Yarn

​Basic Usage: Payment

​Step 1: Prepare a Container

​Step 2: Initialize the Widget

​Usage: Connect Wallet & Sign

​Example:

​Configuration Parameters

​Core Parameters

​Chain Customization

​Internationalization

​Callbacks & Response Data

​onSuccessCallback

​Other Callbacks

Overview

Installation

Option A: CDN (Script Tag)

Option B: NPM/Yarn

Basic Usage: Payment

Step 1: Prepare a Container

Step 2: Initialize the Widget

Usage: Connect Wallet & Sign

Example:

Configuration Parameters

Core Parameters

Chain Customization

Internationalization

Callbacks & Response Data

onSuccessCallback

Other Callbacks