# @faiber/faiber-payment 中文文档

规范地址：https://npmcn.com/package/%40faiber/faiber-payment/

版本：2\.8\.0
npm 元数据更新时间：2026-11-14T09:45:50.351Z
中文译文更新时间：2026-11-14T09:12:17.168Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40faiber/faiber-payment
原文对照：https://npmcn.com/package/%40faiber/faiber-payment/?lang=original

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

- 包体积（解压后）：200 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-18T14:29:41.597Z
- 最新版本发布：2026-11-14T09:45:50.142Z
- 近 30 天下载量：3802（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 66 个）

## 中文简介

网关管理,支付创建,交易查询,每日收入,浏览器回调,支付状况页面.

## 安装

```sh
npm install @faiber/faiber-payment
```

也可以使用：`pnpm add @faiber/faiber-payment`、`yarn add @faiber/faiber-payment`、`bun add @faiber/faiber-payment`

## README

# @faiber/faiber-付费

网关管理,支付创建,交易查询,每日收入,浏览器回调,支付状况页面.

## 安装

```bash
npm install @faiber/faiber-payment
```

## 配置

```ts
import { FaiberClient, MemoryTokenProvider } from "@faiber/sdk-core";
import { PaymentApi } from "@faiber/faiber-payment";

const tokens = new MemoryTokenProvider();
const client = new FaiberClient("payment", {
  domains: { payment: process.env.FAIBER_PAYMENT_URL! },
  tokenProvider: tokens,
  axios: { timeout: 15_000, withCredentials: true },
});
const api = new PaymentApi(client);

const gateways = await api.gateways.list();
const payment = await api.createPayment({
  amount: 4900,
  service_name: "my-service",
  service_model: "order",
  service_id: "order-42",
  queue_name: "my_service_queue",
  callback_url: "https://merchant.example/payment-result",
  idempotency_key: "my-service:order-42",
});
```

## 完全能力

这个软件包从支付服务中暴露出36个注册业务. 通用工作流程有简洁的方法 `api`;每个已注册后端路由在 `api.operations`。生成的操作输入、查询、响应、路径、动词和许可合同从 `operations.types`。 。 。 .

| 区域 | 业务 | HTTP 方法 |
| --- | --: | --- |
| `asset-checkout` | 1个 | `GET` |
| `fitness` | 3个 | `GET`, (中文(简体) ), `POST` |
| `gateway` | 第7条 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST` |
| `integration` | 2个 | `GET` |
| `payment` | 1个 | `POST` |
| `payment-web` | 3个 | `GET`, (中文(简体) ), `POST` |
| `product-plans` | 3个 | `GET`, (中文(简体) ), `POST` |
| `router` | 页:1 | `GET` |
| `session` | 1个 | `GET` |
| `settings` | 2个 | `GET`, (中文(简体) ), `PATCH` |
| `shop-checkout` | 3个 | `GET`, (中文(简体) ), `POST` |
| `transaction` | 页:1 | `GET`, (中文(简体) ), `POST` |

浏览器调用和校验路径在 `api.operations`;呼叫者应当保存支付服务返回的提供者查询参数.

## 认证和授权

使用一个 `TokenProvider` 以转发已签名用户的 Bearer 令牌,或启用 `withCredentials` 用于安全的 Http 只有饼干会话。 每个行动的JSDoc都包含从服务路线卫士复制的许可要求. SDK不嵌入 API 密钥,证书,本地主机 URL,沙盒主机,或生产主机.

## 投入、询问、答复和运输

所有方法都返回完整的Axios响应,包括状态,头,以及请求ID. 请求机构和查询对象被命名为导出接口. 网纹页化使用密钥, 如 `page[number]` 财务报告和审定财务报表 `page[size]` 服务需要时。 标准 Axios 请求选项、信头、超时、适配器、拦截器和 `AbortSignal` 取消被支持为最后参数.

一般性的REST资源得到能力保障。 调用未注册的遗留方法 `UnsupportedOperationError` 在发送请求之前, 而不是生成后端 `405`。 。 。 .

## 错误和取消

```ts
try {
  await api.client.get("/health", undefined, { signal: AbortSignal.timeout(5_000) });
} catch (error) {
  // Axios errors retain response.status and the service error body.
}
```

使用 `@faiber/faiber-ts-sdk` 当一个应用程序需要多个具有一个配置的Faiber服务时.

### 核实的离职和准备情况

`operations.gatewaySetupCheckPost()` 执行仅读的现场提供者检查 `admin:gateway:read`产品专用支付业务包括2done、健身和商店前期结账。 内部端点需要他们的产品所信任的服务器证书;仅凭最终用户的代号并不能授权访问.

`operations.assetCheckoutReceiptGet(purchaseId, options)` 接受 `x-asset-payment-token` 结束 `options.headers` 返回 a **原始内容** 已核实的收据 `purchaseId`, (中文(简体) ), `transaction`整数IRR `amount`, (中文(简体) ), `providerVerified` 财务报告和审定财务报表 `status` (单位:千美元)`pending`, (中文(简体) ), `accepted`,或 `rejected`) (中文(简体) ). 其他产品接收业务保留其服务信封. 付费创建使用稳定的产品特异性同位素键;通过检测重新测试是否适合 `fitnessRetryPost` 而不是创建不相关的交易.

### 门户和交易管理

网关标识符为整数. `gateways.list({ status: "active", "page[number]": 1, "page[size]": 20 })` 返回时 `data.data` 财务报告和审定财务报表 `data.meta`。网关创建/更新支持 `sandbox`; 无效的响应字段总是存在的. 这个 `options` 响应是不透明的存储提供者配置,可能包含加密值:不要从中插入可编辑的证书字段或登录它。 删除返回已删除的网关记录, 而不是布尔结果 。 网关呼叫需要相应的 `admin:gateway:read`, (中文(简体) ), `create`, (中文(简体) ), `update`,或 `delete` 允许.

`transactions.list()` 返回已嵌入 `data.transactions` 页面、过滤汇总摘要、服务名称和网关选项。 交易记录使用情况 `uuid`他们宣布不 `currency` 字段. `transactions.show(uuid)` 财务报告和审定财务报表 `transactionStatus(uuid)` 只有返回状态。 行政要求 `admin:transaction:read`,并需要验证/拒绝 `admin:transaction:verify` 加上经认证的核查员。 核查可与付款提供者联系;检查付款提供者 `successful` 计算结果而不是将HTTP 200等同于成功的支付.

`gatewayOptions()` 返回时 `{ providers, statuses }` 标签/值阵列. `dailyIncomeFor({ days: 7 })` 返回 UTC 日期/挂载点,包括零日期;后端将日光窗口夹到1–90。 没有返回计数字段 . `createPayment()` 接受可选选项 `idempotency_key`;可信赖的产品,健身,资产和商店前期购买必须使用其专用的服务器授权的离职合同. 通用创建不是这些采购的授权绕道.

支付导航操作返回文本/HTML,而不是JSON信封. 提供者回调接受 `Authority`, (中文(简体) ), `transid` 或者说 `paymentNumber` 在“获取”和“POST”两个查询中。 回调可返回303,带 `Location` 配置的 HTTPS 源头; 否则它返回支付结果页 。 在节点,通过 `maxRedirects: 0` (单位:千美元) `validateStatus` 接受303检查该答复。 带有HTTP200的结果页可以描述一次失败的付款. 这些路线可能与真正的提供者联系,而不是只读的健康检查.

### 配置的奖励包检查

`rewardCheckouts.create(product, body, options)` 财务报告和审定财务报表 `rewardCheckouts.receipt(product, transactionId, options)` 需要该产品 配置后端 Bearer 证书 。 服务器验证模型,命令, 偶能键和HTTPS回调源. 这些端点创建/ 读取已验证 支付交易; 独立匹配后仅资产贷记钱包 收条 等待或被取消的付款从不发行硬币. 产品设置 属于服务配置,这些证书必须远离客户.

### 资助奖励退款

`PaymentApi.rewardRefunds` 曝光情况 `list`, (中文(简体) ), `show`, (中文(简体) ), `start`, (中文(简体) ), `confirm`,以及 `reopen`。 。 。 . 这些运营商的电话需要境内流离失所者认证和适用交易 允许。 写入额外需要指派到配置的产品 。 付款人无法验证 自己的退款。 保护 `operation_id` 财务报告和审定财务报表 `version` 当重试一个不变时 请求; 已更改的语义或 stale 发回 HTTP 409 。 方法保留 Axios 响应和接受 `RequestOptions`,包括中止信号.

银行行刑在原商贸门户进行. 两个不同的指定 操作人员然后核查向原付款人全额退款。 重开复议 圆从不执行另一银行退款. `rewardCheckout.refund` 是一个信任的 后端集成,需要现有资产代管;永远不披露 服务证书在浏览器代码。 只有准备情况报告配置.

## 常见问题

### @faiber/faiber-payment 是什么？

网关管理,支付创建,交易查询,每日收入,浏览器回调,支付状况页面\.

### 如何安装 @faiber/faiber-payment？

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

### @faiber/faiber-payment 支持 TypeScript 吗？

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

### @faiber/faiber-payment 支持 ESM 还是 CommonJS？

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

### @faiber/faiber-payment 可以商用吗？

@faiber/faiber-payment 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @faiber/faiber-payment 的下载量有多少？

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

### @faiber/faiber-payment 还在维护吗？

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