# @x-money/checkout 中文文档

规范地址：https://npmcn.com/package/%40x-money/checkout/

版本：0\.2\.0
npm 元数据更新时间：2026-11-02T22:13:48.007Z
中文译文更新时间：2026-11-02T22:39:34.453Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40x-money/checkout
原文对照：https://npmcn.com/package/%40x-money/checkout/?lang=original
项目主页：https://xmoney.mintlify.site/docs/checkout/add-to-your-page

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：109 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-10-02T22:07:08.877Z
- 最新版本发布：2026-10-29T19:33:39.064Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

支付与X结帐按钮的浏览器

## 安装

```sh
npm install @x-money/checkout
```

也可以使用：`pnpm add @x-money/checkout`、`yarn add @x-money/checkout`、`bun add @x-money/checkout`

## README

# @x-money /结帐

X Money SDK的浏览器部分：Pay with X按钮，以及它背后的弹出式结帐流程。

零运行时依赖，不需要框架。

```bash
npm install @x-money/checkout
```

## 快速启动

会话是用您的秘钥创建的，因此该部分保留在您的服务器上。按钮调用端点并从那里获取它。

```js
import { Checkout } from "@x-money/checkout";

const checkout = Checkout();

checkout
  .button({
    intent: "checkout",
    size: "lg",
    session: () =>
      fetch("/api/checkout", { method: "POST" })
        .then((r) => r.json())
        .then((s) => s.url),
    onSuccess: ({ sessionId }) => showPendingState(sessionId),
    onCancel: () => {},
    onError: (error) => handleError(error),
  })
  .mount(document.querySelector("#pay"));
```

使用 [@x-money /核心](https://www.npmjs.com/package/@x-money/core) 在服务器上创建会话。

`onSuccess` 表示客户完成结账，而不是表示您已经付款。履行职责 `checkout_session_completed` Webhook和treat `onSuccess` 作为显示待处理状态的提示。

## 这个按钮

`button()` 返回一个句柄 `mount(target)`， `update(props)`, `unmount()`。选项全部记录在下面 [道具](https://xmoney.mintlify.site/docs/checkout/props)； 简单地说, `intent` 从一套封闭的十六张中挑选一份， `locale` 选择其语言（默认情况下为买方的浏览器语言），并且 `shape`， `size`， `theme`， `border`, `width` 是独立的外观轴。

按钮呈现为一个阴影根，因此页面CSS不能重新设置它的样式。它集 `state` 来 `"loading"` 当结帐正在进行时，这也会阻止点击，因此第二次点击无法打开第二个弹出窗口。

`unmount()` 停止SDK监听，但故意不关闭客户仍在付费的弹出窗口。

## 它自己的流动

如果你想要没有按钮的付款方式， `checkout.start()` 是没有UI的相同流。

```js
import { Checkout } from "@x-money/checkout";

const checkout = Checkout();

const handle = checkout.start({
  session: () => createSessionOnMyServer(),
  onSuccess: ({ sessionId }) => showPendingState(sessionId),
  onCancel: () => resetMyButton(),
  onError: (error) => handleError(error),
});

handle.cancel(); // stop observing, without closing the popup
```

在点击处理程序中直接调用它。它在等待任何东西之前同步打开弹出窗口，这就是阻止弹出窗口拦截器杀死它的原因。

## 错误

`onError` 收到一个 `XMoneyCheckoutError`． 它的 `code` 是其中之一 `no_browser` （在服务器渲染期间调用）， `session_failed` (你的 `session` 回调拒绝;拒绝是对的 `cause`),或 `invalid_session_url` （回调解析为弹出窗口无法导航到的内容）。它们都不意味着付款失败：拒绝的付款将停留在弹出窗口中，供客户重试，而放弃的付款将作为 `onCancel`.

该包附带了一个嵌入了TypeScript源代码的源代码映射，因此浏览器devtools会根据原始源代码显示堆栈跟踪。如果你的打包器发布了它自己的源映射，让它也读取你的依赖项中的源映射（webpack需要） `source-map-loader` )。

## 账户往来

`session` 也接受帐户交换 `url`，当客户授权未来的费用，而不是现在支付。 `onSuccess` 然后接收 `{ exchangeId }` 而不是 `{ sessionId }`，拒绝的顾客关闭弹出窗口，弹出窗口到达时为 `onCancel`。读一读 `customer_id` 和 `account_ids` 从 `account_exchange_setup_succeeded` webhook。

## 弹出模式要求

当您的页面被服务时，弹出窗口只能向您的页面报告 `https` 它的起源（模式、主机和端口）与会话的起源完全匹配 `success_url` 或者 `failure_url`。否则付款仍然完成，但弹出重定向到 `success_url`， `onSuccess` 永远不要开火，并关闭弹出式呼叫 `onCancel`． 一个 `Cross-Origin-Opener-Policy: same-origin` 页眉也有同样的效果。

通过 `debug: true` 当您集成以获得控制台警告时，前缀 `[XMoney]`，用于SDK可以检测的情况。默认情况下，它是关闭的，因此SDK不会在未请求的情况下写入您的控制台。

## 它能处理什么

-   **弹出阻滞剂。** 浏览器会阻止在 `await`，这正是创建点击会话所需要的。该窗口以空白方式同步打开，然后在URL到达时导航。
-   **移动。** 重定向而不是打开一个弹出窗口，所以 `/i/money/checkout` 通用链接可以打开X应用程序。
-   **阻止了弹出窗口。** 退回到整页重定向。
-   **取消。** 关闭弹出窗口的客户不会发送任何信号，因此关闭的窗口将被监视并报告为取消。
-   **结果验证。** 只接受签出原点的结果，只接受打开的窗口的结果，并且只接受带有预期标记的结果。 `onSuccess` 只放一次火。

## 主题

`theme="auto"` 在明亮的表面上渲染黑暗，在黑暗的表面上渲染光明，如下 `prefers-color-scheme` 默认情况下。基于chrome的浏览器将遵循 `.dark` 祖先类，而不是存在的地方；Safari和Firefox没有实现实现这个功能的选择器，所以它们保持在操作系统首选项上。

这种差异是可见的，而不仅仅是不受支持：一个按类别设置为亮模式的网站，在设置为暗模式的机器上观看，在这些浏览器中会得到暗按钮。通过 `theme="light"` 或者 `theme="dark"` 当音调需要保证的时候。

## 文档

完整的指南，每一个意图和变化，和一个现场操场下面 [结账](https://xmoney.mintlify.site/docs/checkout/add-to-your-page) 在X Money文档中。

让AI编码代理使用此包收集付款：

```bash
npx skills add https://xmoney.mintlify.site/docs
```

## 支持

报告错误并提出问题 [X帮助中心](https://help.x.com/en/forms)。安全问题也是如此；请不要公开发布。

## 许可证

麻省理工学院。全文在包中作为 `LICENSE`.

## 常见问题

### @x-money/checkout 是什么？

支付与X结帐按钮的浏览器

### 如何安装 @x-money/checkout？

在项目目录运行 npm install @x-money/checkout，或使用 pnpm add / yarn add / bun add。

### @x-money/checkout 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @x-money/checkout 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @x-money/checkout 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @x-money/checkout 可以商用吗？

@x-money/checkout 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @x-money/checkout 还在维护吗？

最新版本 0\.2\.0 发布于 2026/10/30（4 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/10/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。