Skip to main content
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:
  1. Payment Mode: Handle the entire checkout flow using a payment ID.
  2. 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>

​
Step 2: Initialize the Widget

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

ParameterTypeRequiredDescription
integrationstringPayment ModeThe Payment ID returned by the Nomad Pay server. Required for payment flow.
containerHTMLElementYesThe DOM element to mount the widget.
isDevbooleanNoDefault false. Set to true to connect to the Test Environment.
documentDocumentNoThe document object, useful if working inside iframes.
closeablebooleanNoDefault true. Whether the widget can be closed by the user.
showPricebooleanNoDefault true. Whether to display the order price header.
autoSignOnConnectbooleanNoConnect 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.
ParameterTypeDescription
supportedChainsArray<string>A list of chains to support. Default includes all: ['ethereum', 'solana', 'ton', 'tron', 'bsc', 'polygon', 'arbitrum', 'optimism', 'base', 'avalanche', 'unichain'].
customEvmEndpointsobjectCustom RPC URLs for EVM chains. Example: { ethereum: 'https://...' }
customSolanaEndpointstringCustom RPC URL for Solana.
customTonApiUrlstringCustom API URL for TON network.
customTonManifestUrlstringRequired if using TON. URL to your DApp’s manifest.json.
projectIdstringRequired for WalletConnect. Your WalletConnect Cloud Project ID.

​
Internationalization

ParameterTypeDescription
i18nConfigobjectConfiguration object for languages.
i18nConfig.initialLocalstringInitial language (e.g., 'en', 'zh'). Default 'en'.
i18nConfig.fallbackLocalestringFallback language if translation is missing.
i18nConfig.customTranslationsobjectCustom 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

CallbackDescription
onCancelCallback() => void. Triggered when the user actively cancels the payment.
onErrorCallback(error) => void. Triggered when an error occurs.
onCloseCallback() => void. Triggered when the modal is closed.