> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomadpay.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
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 `` or body of your website.
**Production URL:**
```text theme={null}
```
### **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.
```text theme={null}
```
### **Step 2: Initialize the Widget**
Call `NomadPayWidget.Connect()` with your configuration.
```text theme={null}
// 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:**
```text theme={null}
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` | 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:**
```text theme={null}
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. |