# @alguna/checkout-sdk 中文文档

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

版本：1\.0\.0
npm 元数据更新时间：2026-10-16T13:43:17.886Z
中文译文更新时间：2026-11-06T12:26:18.528Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40alguna/checkout-sdk
原文对照：https://npmcn.com/package/%40alguna/checkout-sdk/?lang=original
项目主页：https://alguna.com/docs/hosted/embedded-checkout

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

- 包体积（解压后）：115 kB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-08-06T09:58:20.116Z
- 最新版本发布：2026-10-16T13:43:17.656Z
- 近 30 天下载量：3209（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

嵌入阿尔古纳 在您的产品中检出 — 一个可主题, 孤立的检出组件

## 安装

```sh
npm install @alguna/checkout-sdk
```

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

## README

# @alguna/ checkout-sdk (英语)

嵌入 [阿尔古纳](https://alguna.io/) 检查你的产品。 您的服务器薄荷 带有密钥 API 的退出会话; 您的前端挂载 包含返回的 URL 组件; Alguna 处理付款的收集、税收和 账户/订阅创建——与斯德雷克嵌入式相同的信任模式 结出.

从阿尔古纳的原产地运来的iframe 里面有检查结果 这是一个 硬隔离边界:您页面的 CSS 无法访问到检查, 以及 退出无法重写您的页面 。 卡片条目使用Frede 自己的 Iframe(所以您 网站不在PCI范围。 样式取出 **仅限** 通过 `appearance` prop——与"花纹元素"相同的模型. SDK飞船没有 样式表; 没有要导入的内容 .

```sh
npm install @alguna/checkout-sdk
```

## 快速启动

### 0\. 一次性设置(Alguna仪表板)

1.  创建 API 密钥 : **设置 ~ API 密钥** (单位:千美元) `id.secret` — 服务器 秘密,永远不要把它送到浏览器.
2.  至少连接了1个支付处理器(例如:friede),用于法律 实体,你的账单.

### 1\. 决定买方是谁(三种身份模式)

| 你的情况 | 在会话中发送什么 | 退职有什么用 |
| --- | --- | --- |
| 买家是阿尔古纳的客户 | `customer_id` (或 `customer_alias`(中文(简体) ) | 向客户收费;可以显示其保存的卡片(参见 [已保存的牌](https://npmcn.com/package/%40alguna/checkout-sdk/#readme-saved-cards)(中文(简体) ) |
| 购买者已登录 **** 产品 | `customer: { name, email, address? … }` | 从您已经知道的创建 Alguna 客户端 —— 不重制版 |
| 购买者匿名( 公开定价页面) | _(什么都没有)_ | 付款前退出收集电子邮件/ 姓名 |

### 2\. 创建会话( 您的服务器)

```ts
const response = await fetch("https://api.alguna.io/checkout-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ALGUNA_API_KEY}`,
    "Alguna-Version": "2026-04-01", // pin the API version
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer: { name: "Acme Corp", email: "billing@acme.com" }, // mode 2
    plan_id: "plan_...",              // or line_items: [...] / amount
    client_reference_id: "order_1234", // echoed on the webhook
    expires_in_seconds: 3600,
  }),
});
const session = await response.json();
// → { id, url, session_token, amount, currency, expires_at, ... }
```

### 3\. 挂出( 您的前端)

反应 :

```tsx
import { AlgunaCheckout } from "@alguna/checkout-sdk/react";

<AlgunaCheckout
  url={session.url}
  layout="compact"                       // your page provides the context
  appearance={{ accentColor: "#4d68eb" }}
  onComplete={({ checkoutSessionId }) => showSuccess()}
  onError={({ code }) => {
    if (code === "session_expired") refreshSession(); // mint a new one, re-mount
  }}
/>;
```

香草:

```ts
import { AlgunaCheckout } from "@alguna/checkout-sdk";

const checkout = AlgunaCheckout.init({
  url: session.url,
  container: "#checkout",
  onComplete: () => (window.location.href = "/welcome"),
});
// checkout.update({ appearance }); checkout.destroy();
```

`onComplete` 支付成功时点火——替换或卸载 组件并带客户前进; 退出仅显示一个简短 中性确认.

### 4\. 对完成的反应(您的服务器)

订阅 `checkout.session.completed` webhook——它的有效载荷 `accountId`, (中文(简体) ), `subscriptionId`, (中文(简体) ), `paymentId`, (中文(简体) ), `invoiceId`,还有你的 `clientReferenceId` - 或民意调查 `GET /checkout-sessions/{id}` 直至 `payment_id`编号 :`subscription_id` 出现.

## 外观

一切都在你的组织仪表板上进行直播(没有重挂) 品牌:

```ts
appearance={{
  preset: "soft",              // or "minimal" | "sharp" — a curated
                               // starting point; every field below overrides it
  accentColor: "#4f46e5",      // CTAs & highlights
  primaryColor: "#0f0f0f",
  mode: "dark",                // dark canvas
  borderRadius: 12,            // cards, inputs, buttons
  fontFamily: "Georgia, serif",// no font download — use stacks you load
  density: "compact",          // tighter vertical rhythm
  payButtonLabel: "Subscribe for {amount}",
  colors: {                    // fine-grained palette
    surface: "#0b1220", card: "#111a2e", text: "#e7e5e4",
    mutedText: "#a8a29e", border: "#1f2b45", inputBackground: "#0e1626",
    inputBorder: "#2563eb",    // input outlines, separate from `border` (the
                               // frame) — set `border` to the surface color to
                               // flatten the frame while keeping fields outlined
  },
}}
```

组件大小: `layout: "compact"` 放弃退出 页面内嵌入。 iframe 自动调整内容; 通过 `maxHeight` 改为 盖上,窗体会在这个高度以上的组件内滚动.

## 样式

唯一支持的校对方式是 `appearance` 道具——颜色, 边框半径,字体家族,轻/暗模式,以及被整理的预设. 因为 退出在 Iframe 中被隔离, 您页面的 CSS 无法( 也不应该) 目标 这个 这反映了花纹元素和原始元素的样式.

## 自定义支付按钮

调整自己的付款按钮而不是内置的按钮:

```tsx
const ref = useRef<AlgunaCheckoutRef>(null);
const [state, setState] = useState<CheckoutState>();

<AlgunaCheckout
  ref={ref}
  url={session.url}
  hidePayButton
  onCheckoutStateChange={setState}
  onComplete={...}
/>
<button disabled={!state?.canSubmit} onClick={() => ref.current?.submit()}>
  {state?.isProcessing ? "Processing…" : "Pay"}
</button>
```

`hidePayButton` 隐藏我们的按钮( “ 付款是安全的, 加密的 ” 行) 留职); `submit()` (一) 电机触发付款; `onCheckoutStateChange` 报告 `{ canSubmit, isProcessing, isComplete, error }` 这样你就可以按下按钮了.

## 已保存的牌

默认情况下,每个买家——新买或退买——都新鲜地入出出出牌. 让一个 用他们之前用的卡片还客户薪,通过 `showSavedPaymentMethods` (仅对 `customer_id` 编号 : `customer_alias` 我们了解谁是买方:

```tsx
<AlgunaCheckout url={session.url} showSavedPaymentMethods />
```

有了它,一个客户 谁在文件中有一张卡 看到了它的预选,有一个"使用a 输入新卡的选项。 纸牌由您管理 客户端设置, 退出时未编辑内置 .

## 任期

取出时会显示一个术语接受复选框 **必须** 于 买家可以付钱。 它将你的法律实体的服务条件联系起来——同样的条件 在别处为该实体配置(引用、主机检查)——所以不需要 将传递给SDK.

使复选框具有可选性(不是块付款),通过 `requireTermsAcceptance={false}`数字 :

```tsx
<AlgunaCheckout url={session.url} requireTermsAcceptance={false} />
```

## 信任线

支付按钮下"支付安全并加密"行可被隐藏:

```tsx
<AlgunaCheckout url={session.url} hidePaymentSecurityText />
```

## 正在回放以滚动

检查的iframe 大小到它的内容, 所以轮子手势在它上 转发到您的页面(默认滚动)。 要处理滚动自己 例如,在自定义滚动容器内使用 `onScroll`数字 :

```tsx
<AlgunaCheckout url={session.url} onScroll={(deltaY) => myScroller.scrollBy(0, deltaY)} />
```

镜子 `onResize`。 。 。 .

## 会话错误( M)

-   届会到期( E)`expires_in_seconds`,默认为24h,最大为7d). 每个创建一个 检查尝试.
-   `onError` 代码 : `session_expired` (清新会话并重新挂起)和 `load_failed` (重试/支持).

## 安保模式

检查从阿尔古纳的原产地开始,所以你的页面从不触及 敏感数据或检查的 DOM :

-   **会话符号是短寿命和单目的.** 每个都由你做成 服务器(带有您的秘密密钥),用于一次检出,范围为该会话,以及 期满`expires_in_seconds`) (中文(简体) ). 浏览器只持有这个范围标记, 从来没有你的 API 密钥.
-   **卡片数据从不输入你的DOM.** 它被俘获在史崔克的内框里 因此,你的站点留在PCI SAQ-A范围.
-   **您的CSS无法联系到报到,反之亦然.** Iframe是很难的 边框——仅通过样式 `appearance`。 。 。 .
-   **来源允许列入名单.** 兽群可以限制哪些场所可以嵌入它们 退出( 磁盘设置); 嵌入层拒绝在被否决的上渲染 源代码。 SDK通过您的页面源头, 从而可以对每个页面进行校对 后弥陀.

## 常见问题

### @alguna/checkout-sdk 是什么？

嵌入阿尔古纳 在您的产品中检出 — 一个可主题, 孤立的检出组件

### 如何安装 @alguna/checkout-sdk？

在项目目录运行 npm install @alguna/checkout-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react-dom（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alguna/checkout-sdk 支持 TypeScript 吗？

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

### @alguna/checkout-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @alguna/checkout-sdk 可以商用吗？

@alguna/checkout-sdk 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @alguna/checkout-sdk 的下载量有多少？

根据 npm 官方下载统计，@alguna/checkout-sdk 在 2026/10/06 – 2026/11/04 这 30 天内被下载 3,209 次，日均约 107 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alguna/checkout-sdk 还在维护吗？

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