Wen Open Lab · 开放集成

第 4 阶段:支付桥链接已验证

English · Italiano · 中文 · 한국어

由 Wen 与 AI 一起从英文译出。以英文页面为准;欢迎指正。

Wen 支付方式设计
一种向所有人开放的新支付方式

银行卡收单为商店做三件事:收款、确认、通知商店系统。这个模型在 Solana 上用开放的 Solana Pay 标准做同样的事:每笔订单一个支付链接或二维码,一个通过唯一参考号找到付款的监听器,一套严格的校验,以及发往商店的 webhook。

任务

让网店在 Solana 上收款,并自动把订单标记为已付款,可靠程度与商店对银行卡收单机构的期望相同。

模型

  1. 创建。商店为每笔订单生成一个 Solana Pay 链接,包含收款方、金额、代币、一个唯一的随机 reference 地址、一个标签和备注 order:ID。链接会变成按钮或二维码。
  2. 支付。顾客在任意支持 Solana Pay 的钱包中打开并确认。
  3. 查找。商店服务器向链查询包含该参考地址的交易。
  4. 校验。检查收款方、金额、代币、参考号和备注。任何不对都会抛出错误。
  5. 通知。把 {orderId, status: "paid", signature} 发送到商店的 webhook。订单系统随即发货。
银行卡收单这座桥
确认数秒内授权,数天后到账数秒内确认,约 13 秒最终确定
费用按比例收费,外加每笔固定费用网络费,不到一美分,外加可能的兑换成本
拒付有:保护买家,商店承担风险没有:退款是商店发起的一笔新付款
监管由持牌收单机构处理视国家而定;可能需要持牌合作方

代码

文件:lab/code/src/04-solana-pay-bridge.ts · Apache-2.0

// Model 4: a payment bridge for e-commerce. The shop creates a Solana Pay link/QR for an order,
// watches the chain for the payment by its unique reference, validates amount and token,
// then notifies its own order system (the same role a card acquirer's callback plays).
// License: Apache-2.0. Example code, not audited. Devnet first. Built on @solana/pay + @solana/kit.
import { encodeURL, findReference, validateTransfer, FindReferenceError } from '@solana/pay';
import { address, createSolanaRpc, generateKeyPairSigner, type Address } from '@solana/kit';

/** Tokens a shop may accept. USDC for stable prices; $WEN as an optional community payment. */
export const ACCEPTED = {
  USDC_MAINNET: address('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
  WEN_MAINNET: address('WENWENvqqNya429ubCdR81ZmD69brwQaaBYY6p3LCpk'),
} as const;

export interface PaymentRequest {
  orderId: string;
  recipient: Address;      // the shop's wallet
  amount: number;          // in token units, e.g. 24.99
  splToken?: Address;      // omit for SOL
  reference: Address;      // unique per order: how the shop finds the payment
  url: string;             // solana: URL to show as a link or QR
}

export async function createPaymentRequest(orderId: string, recipient: Address, amount: number, splToken?: Address): Promise<PaymentRequest> {
  const reference = (await generateKeyPairSigner()).address;   // random, never reused
  const url = encodeURL({
    recipient, amount, splToken, reference,
    label: 'Wen Open Lab demo shop',
    message: `Order ${orderId}`,
    memo: `order:${orderId}`,
  });
  return { orderId, recipient, amount, splToken, reference, url: url.toString() };
}

/** Poll until the payment appears, then validate it and call the shop's webhook. */
export async function waitForPayment(req: PaymentRequest, opts: { rpcUrl: string; webhook: string; timeoutMs?: number }) {
  const rpc = createSolanaRpc(opts.rpcUrl);
  const deadline = Date.now() + (opts.timeoutMs ?? 5 * 60_000);
  while (Date.now() < deadline) {
    try {
      const found = await findReference(rpc, req.reference, { commitment: 'confirmed' });
      // Throws if recipient, amount, token, reference or memo do not match the request.
      await validateTransfer(rpc, found.signature, {
        recipient: req.recipient, amount: req.amount, splToken: req.splToken, reference: req.reference, memo: `order:${req.orderId}`,
      }, { commitment: 'confirmed' });
      await fetch(opts.webhook, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ orderId: req.orderId, status: 'paid', signature: found.signature }),
      });
      return found.signature;
    } catch (e) {
      if (!(e instanceof FindReferenceError)) throw e;   // not found yet: keep waiting
      await new Promise(r => setTimeout(r, 1500));
    }
  }
  throw new Error(`Order ${req.orderId}: payment not found before timeout`);
}

已验证的内容

支付链接经过官方 Solana Pay 解析器往返一次后,收款方、金额、代币、参考号和备注保持不变,每笔订单都获得唯一的参考号。监听和校验使用官方的 findReference 与 validateTransfer,并已通过类型检查;在真实链上运行它们属于 devnet 阶段。

用在哪里

  • 面向全球加密原生顾客的网店。
  • 即时结算很重要的数字商品、门票和订阅。
  • 在银行卡之外探索接受稳定币的支付服务商和银行。

局限与风险

  • 价格波动:用稳定币标价,或在结账时兑换。
  • 兑换成法币(出金)有自己的费用和规则。
  • 没有拒付意味着商店必须提供清晰的退款政策。
  • 生产环境请使用自己的 RPC 端点;公共端点有频率限制。

想知道你店里的数字?试试模拟器。

图说 Wen

Jupiter Mobile 上的 Wen
用手机支付
带 Wen 币的 Solana Seeker
钱包就在口袋里
Wen 加密钱包结账
数秒完成结账
Jupiter 钱包支付
任何代币,一个标准
Wen 生态移动支付
从二维码到确认订单

Wen 在此模型中的位置

商店自己选择接受哪些代币。USDC 让价格保持稳定;WEN 可以作为社区支付选项提供,其合约在代码中写作 ACCEPTED.WEN_MAINNET。接受任何代币之前,先检查是哪个代币程序拥有它的铸币(common.ts 中的辅助函数 detectTokenProgram 可以做到),并在 devnet 上测试完整流程。

Wen 的主线:一个合约,处处可见

实验室的每个模型都免费且开放,并带着同一个签名:$WEN 代币合约。复制它,在你自己的文档中重复它,使用前务必在浏览器上核验。

WENWENvqqNya429ubCdR81ZmD69brwQaaBYY6p3LCpk

核验:Solana Explorer · 如何找到合约 ID

开放使用政策

  • 免费且开放。实验室的全部代码以 Apache License 2.0 发布,与 Wen Program Library 相同。无论是否商用,都可以使用、修改、发布;请保留许可声明。
  • 只用开放工具。基于公开且有文档的工具构建:Solana SPL Token-2022(Token Extensions)、Wen New Standard(WNS)的代币布局、Solana Pay,以及用于本地测试的 LiteSVM。
  • 规则:始终核验你自己的模型。运行测试,从 devnet 开始,阅读官方文档,检查每个账户和金额,并在任何主网使用之前获得独立审计。未经核验的模型不是模型,而是猜测。
  • 未经审计,不构成建议。这些是教学示例,不构成金融、法律或税务建议,也不是持牌的支付或银行产品。在大多数国家,支付、稳定币和收单都是受监管的活动。
  • 安全。切勿把私钥粘贴到任何网站。不要安装 npm 包 @wen-community/wen-new-standard:npm 已因恶意将其移除。请从官方来源构建。

由 Wen 为社区讲述。更多内容见我们的编辑与数据政策。

Wen Open Lab · 路线图 · 全部代码 · GitHub 上的 Wen Program Library

Wen 驾驶星舰穿过深空中的光带
以一个区块的速度支付:每笔订单一个参考号,商店无需猜测就能找到每一笔付款。