Pay Widget

OnePayWidget 是一个统一支付组件，将多种支付流程整合到单个可配置的 widget 中。它支持三种模式，并附带常见用例的专用预设。ONE SDK（@one_deploy/sdk v1.1.0）将其作为仅限 Web 的 React DOM 组件提供。

仅限 Web 端

OnePayWidget 及其所有预设均渲染至 DOM，需要浏览器环境。它们在 React Native 或 Node.js 中不可用。请在这些平台上直接使用 OneEngineClient API 方法。

模式

模式	描述	使用场景
fund_wallet	使用法币通过本地支付方式为加密钱包充值	钱包充值、新用户入门
direct_payment	直接向商户或收款方付款（法币或加密货币）	结账流程、账单、捐款
transaction	带支付 UI 的任意链上交易执行	智能合约交互、NFT 购买

OnePayWidget 组件

import { OnePayWidget } from '@one_deploy/sdk';

OnePayWidgetProps

interface OnePayWidgetProps {
  /** 支付模式 */
  mode: 'fund_wallet' | 'direct_payment' | 'transaction';

  // --- 通用属性（所有模式） ---

  /** 已连接的钱包地址 */
  walletAddress: string;
  /** 链 ID */
  chainId?: number;
  /** Widget 颜色主题 */
  theme?: 'light' | 'dark' | 'auto';
  /** 覆盖 CSS 类名 */
  className?: string;
  /** 支付成功时调用 */
  onSuccess?: (result: PayWidgetResult) => void;
  /** 发生错误时调用 */
  onError?: (error: { code: string; message: string }) => void;
  /** 用户关闭 widget 时调用 */
  onClose?: () => void;

  // --- fund_wallet 模式属性 ---

  /** 默认充值的法币金额 */
  defaultAmount?: number;
  /** 默认法币币种（ISO 4217） */
  defaultFiatCurrency?: string;
  /** 存入钱包的加密代币 */
  targetToken?: string;
  /** 用户所在国家，用于本地支付提供商 */
  country?: string;
  /** 限制支付方式 */
  allowedPaymentMethods?: string[];

  // --- direct_payment 模式属性 ---

  /** 收款方钱包地址（商户 / 收款人） */
  recipientAddress?: string;
  /** 固定支付金额（禁止用户编辑） */
  fixedAmount?: number;
  /** 固定法币币种 */
  fixedFiatCurrency?: string;
  /** 固定加密代币 */
  fixedCryptoToken?: string;
  /** 接受法币支付 */
  acceptFiat?: boolean;
  /** 接受加密货币支付 */
  acceptCrypto?: boolean;
  /** 向用户显示的订单 / 发票参考号 */
  orderReference?: string;
  /** widget 中显示的商户名称 */
  merchantName?: string;

  // --- transaction 模式属性 ---

  /** 目标合约地址 */
  contractAddress?: string;
  /** 编码后的交易数据 */
  transactionData?: string;
  /** 随交易发送的原生代币价值 */
  transactionValue?: string;
  /** 人类可读的交易描述 */
  transactionDescription?: string;
  /** 执行所需的代币（如果用户余额不足，可在 widget 内购买） */
  requiredToken?: {
    symbol: string;
    address: string;
    amount: string;
  };
}

interface PayWidgetResult {
  /** 使用的支付模式 */
  mode: 'fund_wallet' | 'direct_payment' | 'transaction';
  /** 交易标识符 */
  transactionId: string;
  /** 链上交易哈希 */
  txHash?: string;
  /** 支付状态 */
  status: PaymentStatus;
  /** 支付的金额（法币，如适用） */
  fiatAmount?: number;
  /** 法币币种 */
  fiatCurrency?: string;
  /** 加密货币金额 */
  cryptoAmount?: string;
  /** 加密代币 */
  cryptoCurrency?: string;
  /** 收款方地址 */
  recipientAddress?: string;
  /** ISO 8601 时间戳 */
  completedAt: string;
}

type PaymentStatus =
  | 'pending'
  | 'processing'
  | 'completed'
  | 'failed'
  | 'expired'
  | 'refunded';

模式 1：fund_wallet

使用本地法币支付方式为用户的加密钱包充值。这与电子钱包充值中描述的流程相同，封装在统一的 Pay Widget 中。

import { OnePayWidget } from '@one_deploy/sdk';

function FundWalletExample() {
  return (
    <OnePayWidget
      mode="fund_wallet"
      walletAddress="0xUserWallet..."
      chainId={137}
      defaultAmount={50}
      defaultFiatCurrency="NGN"
      targetToken="USDT"
      country="NG"
      onSuccess={(result) => {
        console.log('Wallet funded!');
        console.log(`Received: ${result.cryptoAmount} ${result.cryptoCurrency}`);
      }}
      onError={(error) => console.error(error.message)}
      theme="light"
    />
  );
}

OneFundWalletWidget 预设

import { OneFundWalletWidget } from '@one_deploy/sdk';

function FundWalletPreset() {
  return (
    <OneFundWalletWidget
      walletAddress="0xAbc..."
      chainId={137}
      defaultFiatCurrency="KES"
      targetToken="USDC"
      country="KE"
      defaultAmount={5000}
      onSuccess={(result) => console.log('Funded:', result)}
    />
  );
}

模式 2：direct_payment

从用户向商户或收款方收取付款。支持法币和加密货币两种支付路径。Widget 处理货币选择、金额输入（或显示固定金额），并路由支付。

import { OnePayWidget } from '@one_deploy/sdk';

function CheckoutExample() {
  return (
    <OnePayWidget
      mode="direct_payment"
      walletAddress="0xCustomerWallet..."
      chainId={1}
      recipientAddress="0xMerchantWallet..."
      fixedAmount={29.99}
      fixedFiatCurrency="USD"
      acceptFiat={true}
      acceptCrypto={true}
      orderReference="ORDER-12345"
      merchantName="Example Store"
      onSuccess={(result) => {
        console.log('Payment received!');
        console.log(`Order: ORDER-12345, tx: ${result.txHash}`);
      }}
      onError={(error) => console.error(error.message)}
      theme="dark"
    />
  );
}

仅加密货币的直接支付

import { OnePayWidget } from '@one_deploy/sdk';

function CryptoPaymentExample() {
  return (
    <OnePayWidget
      mode="direct_payment"
      walletAddress="0xCustomerWallet..."
      chainId={137}
      recipientAddress="0xMerchantWallet..."
      fixedCryptoToken="USDC"
      fixedAmount={50}
      acceptFiat={false}
      acceptCrypto={true}
      merchantName="Crypto Cafe"
      onSuccess={(result) => console.log('Paid with USDC:', result.txHash)}
    />
  );
}

OneDirectPayWidget 预设

mode="direct_payment" 的快捷方式，同时启用法币和加密货币：

import { OneDirectPayWidget } from '@one_deploy/sdk';

function DirectPayPreset() {
  return (
    <OneDirectPayWidget
      walletAddress="0xCustomer..."
      recipientAddress="0xMerchant..."
      fixedAmount={100}
      fixedFiatCurrency="USD"
      merchantName="Acme Corp"
      orderReference="INV-9876"
      onSuccess={(result) => console.log('Paid:', result)}
    />
  );
}

OneCryptoOnlyPayWidget 预设

将 widget 限制为仅加密货币支付：

import { OneCryptoOnlyPayWidget } from '@one_deploy/sdk';

function CryptoOnlyPreset() {
  return (
    <OneCryptoOnlyPayWidget
      walletAddress="0xCustomer..."
      chainId={1}
      recipientAddress="0xMerchant..."
      fixedCryptoToken="ETH"
      onSuccess={(result) => console.log('Crypto payment:', result.txHash)}
    />
  );
}

OneFiatOnlyPayWidget 预设

将 widget 限制为仅法币支付（入金 + 转账至收款方）：

import { OneFiatOnlyPayWidget } from '@one_deploy/sdk';

function FiatOnlyPreset() {
  return (
    <OneFiatOnlyPayWidget
      walletAddress="0xCustomer..."
      recipientAddress="0xMerchant..."
      fixedAmount={75}
      fixedFiatCurrency="EUR"
      merchantName="EU Store"
      onSuccess={(result) => console.log('Fiat payment:', result)}
    />
  );
}

模式 3：transaction

带支付 UI 层执行任意链上交易。当用户需要与智能合约交互但可能需要先获取代币时，此模式非常有用。

import { OnePayWidget } from '@one_deploy/sdk';

function NFTPurchaseExample() {
  return (
    <OnePayWidget
      mode="transaction"
      walletAddress="0xBuyerWallet..."
      chainId={1}
      contractAddress="0xNFTContractAddress..."
      transactionData="0xa0712d680000000000000000000000000000000000000000000000000000000000000001"
      transactionValue="0.08"
      transactionDescription="Mint 1 NFT from Cool Collection"
      requiredToken={{
        symbol: 'ETH',
        address: '0x0000000000000000000000000000000000000000',
        amount: '0.08',
      }}
      onSuccess={(result) => {
        console.log('NFT minted!');
        console.log(`Tx: ${result.txHash}`);
      }}
      onError={(error) => console.error('Mint failed:', error.message)}
      theme="light"
    />
  );
}

代币门控交易

当用户没有足够的所需代币时，widget 会提供先购买或兑换的选项，然后执行交易：

function TokenGatedExample() {
  return (
    <OnePayWidget
      mode="transaction"
      walletAddress="0xUserWallet..."
      chainId={137}
      contractAddress="0xStakingContract..."
      transactionData="0x..."
      transactionDescription="Stake 1000 USDC in the yield pool"
      requiredToken={{
        symbol: 'USDC',
        address: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
        amount: '1000',
      }}
      onSuccess={(result) => {
        console.log('Staked successfully:', result.txHash);
      }}
    />
  );
}

代币门控交易的 widget 流程：

  1. Check user balance   2. If insufficient,     3. Execute the
     for required token      offer buy/swap  -->     target transaction
         |                   in-widget
         v
     Sufficient? ----yes---> Execute immediately

样式

所有 OnePayWidget 变体都接受 theme 和 className 属性：

<OnePayWidget
  mode="direct_payment"
  walletAddress="0x..."
  recipientAddress="0x..."
  theme="dark"
  className="my-custom-pay-widget"
  // ...
/>

使用 className 和 CSS 自定义属性覆盖内部样式：

.my-custom-pay-widget {
  --one-pay-primary: #6c5ce7;
  --one-pay-background: #1a1a2e;
  --one-pay-text: #eaeaea;
  --one-pay-border-radius: 12px;
  --one-pay-font-family: 'Inter', sans-serif;
  max-width: 420px;
}

预设汇总

预设	模式	法币	加密货币	描述
OneFundWalletWidget	fund_wallet	Yes	--	通过本地支付方式为钱包充值
OneDirectPayWidget	direct_payment	Yes	Yes	接受法币和加密货币支付
OneCryptoOnlyPayWidget	direct_payment	--	Yes	仅接受加密货币支付
OneFiatOnlyPayWidget	direct_payment	Yes	--	仅接受法币支付

参见

• 支付概览
• 入金（购买加密货币）
• 出金（出售加密货币）
• 代币兑换
• 点对点转账
• 电子钱包充值
• 账单支付