支付概览

ONE SDK（@one_deploy/sdk v1.1.0）提供了一套完整的支付层，涵盖用户所需的所有价值转移场景：使用法币购买加密货币、将加密货币兑换回法币、在代币之间进行兑换、发送点对点转账、为电子钱包充值以及支付账单。

支付流程

                         +------------------+
                         |    Your User     |
                         +--------+---------+
                                  |
            +---------------------+---------------------+
            |          |          |          |           |
            v          v          v          v           v
       +---------+ +--------+ +------+ +--------+ +---------+
       | On-ramp | |Off-ramp| | Swap | |Transfer| | Top-up  |
       | (Buy)   | | (Sell) | |      | | (P2P)  | | / Bills |
       +---------+ +--------+ +------+ +--------+ +---------+
            |          |          |          |           |
            v          v          v          v           v
       +---------------------------------------------------+
       |           @one_deploy/sdk  Payments API            |
       |                                                    |
       |   Widgets (Web)    |    OneEngineClient (All)      |
       +---------------------------------------------------+
            |          |          |          |           |
            v          v          v          v           v
       +---------------------------------------------------+
       |              ONE Engine API (engine.one23.io)      |
       +---------------------------------------------------+
            |                    |                   |
            v                    v                   v
     Fiat Payment          Blockchain           Local Payment
     Processors            Networks             Providers

支付功能

功能	描述	Widget（Web）	API（全平台）
入金	使用法币购买加密货币（银行卡、银行转账、移动支付）	OneOnrampWidget	getOnrampQuote, createOnrampSession
出金	将加密货币兑换为法币（银行转账、移动支付）	OneOfframpWidget	getOfframpQuote, createOfframpTransaction
兑换	代币间兑换，支持同链或跨链	OneSwapWidget	getSwapQuote, executeSwap
点对点转账	向任意钱包地址发送代币	OneSendWidget	sendTransaction
充值	通过本地支付方式为电子钱包充值	OnePayWidget	createTopup
账单支付	支付水电费、话费、订阅服务	--（即将推出）	payBill, getBillProviders

Widget 与 API

ONE SDK 提供了两种互补的支付接口：

Web Widget（仅限 React DOM）

预构建的 React 组件，处理完整的 UI 流程 -- 输入字段、报价展示、确认和状态追踪。可直接嵌入任何 React DOM 应用。

import { OneOnrampWidget, OneSwapWidget, OnePayWidget } from '@one_deploy/sdk';

仅限 Web 端

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

API 方法（全平台）

每个支付操作都可以通过 OneEngineClient 上的方法来调用。适用于 React Native、Node.js 后端，或需要完全控制 UI 的场景。

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

const engine = new OneEngineClient({
  apiKey: process.env.ONE_API_KEY!,
  projectId: process.env.ONE_PROJECT_ID!,
});

// Works on Web, React Native, and Node.js
const quote = await engine.getOnrampQuote('USD', 100, 'USDT');
const swapQuote = await engine.getSwapQuote({ fromToken: 'ETH', toToken: 'USDC', amount: '1.0' });

支持的链

支付方法在以下网络上可用（根据功能有所不同）：

链	入金	出金	兑换	转账
Ethereum	Yes	Yes	Yes	Yes
Polygon	Yes	Yes	Yes	Yes
Arbitrum	Yes	Yes	Yes	Yes
Optimism	Yes	--	Yes	Yes
Base	Yes	--	Yes	Yes
BSC	Yes	Yes	Yes	Yes
Avalanche	Yes	--	Yes	Yes

通用类型

以下类型在各支付 API 之间共享：

/** Identifies a token across chains */
interface TokenIdentifier {
  symbol: string;
  chainId: number;
  address?: string; // native tokens omit address
}

/** Fiat currency reference */
interface FiatCurrency {
  code: string;        // ISO 4217 -- "USD", "EUR", "NGN"
  name: string;
  symbol: string;      // "$", "€", "₦"
  decimals: number;
}

/** Generic payment status used across all flows */
type PaymentStatus =
  | 'pending'
  | 'processing'
  | 'completed'
  | 'failed'
  | 'expired'
  | 'refunded';

/** Callback shape used by all payment widgets */
interface PaymentCallbacks {
  onSuccess?: (result: { transactionId: string; status: PaymentStatus }) => void;
  onError?: (error: { code: string; message: string }) => void;
  onClose?: () => void;
}

下一步

• 入金（购买加密货币） -- 让用户使用法币购买加密货币。
• 出金（出售加密货币） -- 让用户将加密货币兑换为法币。
• 代币兑换 -- 同链或跨链代币兑换。
• 点对点转账 -- 向任意地址发送代币。
• 电子钱包充值 -- 通过本地支付方式为钱包充值。
• 账单支付 -- 使用加密货币支付账单（即将推出）。
• Pay Widget -- 支持多种模式的统一支付组件。