# @buckaroo/buckaroo\_sdk 中文文档

规范地址：https://npmcn.com/package/%40buckaroo/buckaroo_sdk/

版本：1\.14\.0
npm 元数据更新时间：2026-11-05T14:03:24.793Z
中文译文更新时间：2026-11-08T18:02:00.815Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40buckaroo/buckaroo_sdk
原文对照：https://npmcn.com/package/%40buckaroo/buckaroo_sdk/?lang=original
项目主页：https://github.com/buckaroo-it/BuckarooSDK_Node#readme
源码仓库：https://github.com/buckaroo-it/BuckarooSDK_Node

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

- 包体积（解压后）：538 kB，415 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=6\.14
- 运行依赖：4 个
- 首次发布：2023-04-20T08:45:54.313Z
- 最新版本发布：2026-11-05T14:03:23.654Z
- 近 30 天下载量：9123（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 10 个）

## 中文简介

袋鼠支付 SDK

## 安装

```sh
npm install @buckaroo/buckaroo_sdk
```

也可以使用：`pnpm add @buckaroo/buckaroo_sdk`、`yarn add @buckaroo/buckaroo_sdk`、`bun add @buckaroo/buckaroo_sdk`

## README

[![Buckaroo — Node SDK](https://raw.githubusercontent.com/buckaroo-it/Media/main/Buckaroo/README.md%20Headers/buckaroo-node-sdk-header-rounded.png)](https://www.buckaroo.nl/)

# 白鼠节点 SDK

[![Latest release](https://img.shields.io/npm/v/@buckaroo/buckaroo_sdk.svg?label=release)](https://www.npmjs.com/package/@buckaroo/buckaroo_sdk) [![Node version](https://img.shields.io/node/v/@buckaroo/buckaroo_sdk.svg?label=node)](https://www.npmjs.com/package/@buckaroo/buckaroo_sdk) [![Documentation](https://img.shields.io/badge/docs-docs.buckaroo.io-1a1a4b.svg)](https://docs.buckaroo.io/docs/node-sdk) [![Download from npm](https://img.shields.io/badge/npm-download-cb3837.svg)](https://www.npmjs.com/package/@buckaroo/buckaroo_sdk)

[关于](https://npmcn.com/package/%40buckaroo/buckaroo_sdk/#readme-about) • 妇女 [所需资源](https://npmcn.com/package/%40buckaroo/buckaroo_sdk/#readme-requirements) • 妇女 [安装](https://npmcn.com/package/%40buckaroo/buckaroo_sdk/#readme-installation) • 妇女 [开始](https://npmcn.com/package/%40buckaroo/buckaroo_sdk/#readme-getting-started) • 妇女 [只使用服务器侧](https://npmcn.com/package/%40buckaroo/buckaroo_sdk/#readme-server-side-use-only) • 妇女 [测试](https://npmcn.com/package/%40buckaroo/buckaroo_sdk/#readme-testing) • 妇女 [支助](https://npmcn.com/package/%40buckaroo/buckaroo_sdk/#readme-support) • 妇女 [贡献](https://npmcn.com/package/%40buckaroo/buckaroo_sdk/#readme-contribute)

* * *

## 关于

Buckaroo是荷兰支付服务供应商。 超过54 000个组织依靠Buckaroo平台处理付款、订阅和未付发票.

这是Buckaroo的官方节点SDK:一个现代开放源代码库,将JavaScript或TypeScript应用程序连接到Buckaroo API. 它搭载了CommonJS和ES模块与TypeScript声明一起构建,因此在任一模块系统中工作,没有额外的配置.

[关于docs.buckaroo.io的完整SDK文档](https://docs.buckaroo.io/docs/node-sdk),则 [API 参考](https://docs.buckaroo.io/reference) 用于请求参数和服务代码.

* * *

## 所需资源

| 所需经费 | 支持的版本 |
| --- | --- |
| 节点.js | 6.14 或更高 |

你还需要一个Buckaroo账户。 还没有吗? [请求账户](https://www.buckaroo.nl/start)。 。 。 .

* * *

## 安装

```bash
npm install @buckaroo/buckaroo_sdk
```

或用纱线:

```bash
yarn add @buckaroo/buckaroo_sdk
```

* * *

## 开始

### 配置客户端

您可以在下面找到您的 Store 密钥和密钥 [Buckaroo广场的API证书](https://plaza.buckaroo.nl/Configuration/Merchant/ApiKeys)设置 `mode` 改为 `TEST` 开发并进入 `LIVE` 在生产中.

```javascript
import Buckaroo from '@buckaroo/buckaroo_sdk';

const buckarooClient = Buckaroo.InitializeClient(
    {
        websiteKey: 'YOUR_STORE_KEY',
        secretKey: 'YOUR_SECRET_KEY',
    },
    {
        mode: 'TEST', // or 'LIVE'
        currency: 'EUR',
        returnURL: 'https://example.com/return',
        pushURL: 'https://example.com/push',
    }
);
```

> \[注\] 这个 `websiteKey` 选项选择您的 Store 密钥。 Store 密钥之前称为 Website 密钥,该选项名称被保留为后向兼容.

> \[TIP\] 让您的密钥脱离版本控制 。 从环境变量中装入两把钥匙,而存储器则装入 [`.env.example`](https://github.com/buckaroo-it/BuckarooSDK_Node/blob/master/.env.example) 开始.

### 创建付款

每一种支付方法都使用稍有不同的有效载荷. 本例收费为 Mastercard :

```javascript
const payment = await buckarooClient
    .method('mastercard')
    .pay({
        amountDebit: 100,
    })
    .request();
```

交换 `mastercard` 用于任何其他服务代码使用不同的支付方法。 服务代码及其参数列于 [API 参考](https://docs.buckaroo.io/reference)。 。 。 .

### 获取交易信息

一旦交易存在,您可按要求查询:

```javascript
const transaction = buckarooClient.transaction(payment.getTransactionKey());

await transaction.status();     // transaction status
await transaction.refundInfo(); // refund info
await transaction.cancelInfo(); // cancellation info
```

### 正在验证按下消息

把原始请求体传递给 `ReplyHandler` 作为弦. 从 `data()`而不是从你自己的身体. `data()` 只在通过验证后返回字段.

```javascript
import { ReplyHandler } from '@buckaroo/buckaroo_sdk';

// HTTP post push: the raw application/x-www-form-urlencoded body
const reply = new ReplyHandler(buckarooClient.credentials, rawBody).validate();

// JSON push: also pass the Authorization header and the full push URL
// const reply = new ReplyHandler(buckarooClient.credentials, rawBody, req.headers.authorization, pushUrl).validate();

if (reply.isValid()) {
    const push = reply.data();
    // push.brq_statuscode, push.brq_invoicenumber, ...
}
```

更多可运行的例子在 [`example/`](https://github.com/buckaroo-it/BuckarooSDK_Node/tree/master/example)。 。 。 .

* * *

## 只使用服务器侧

> \[尖叫声\] 只使用您服务器上的此库 。 永远不要将其捆绑到网站或移动应用程序中.

这个库用JavaScript来写出,因此技术上可以将其收录到前端代码中——但这样做会让装入页面的每个人暴露出你的"秘密"密钥. 任何持有钥匙的人都可以代表你行事.

在预定的设置中,你的服务器持有"秘密"密钥,并通过这个SDK呼叫"白鼠"API. 浏览器上没有任何敏感内容 .

* * *

## 测试

```bash
npm install
npm test
```

测试运行于 [欢乐](https://jestjs.io/)。格式由 Pretier 处理 :

```bash
npm run prettier
```

与白鼠测试环境交谈的测试需要证明,所以复制 `.env.example` 改为 `.env` 并先填写您的测试 Store 密钥和密钥.

* * *

## 支助

有麻烦吗? 通过这份清单,然后联系:

1.  检查 [SDK 文档](https://docs.buckaroo.io/docs/node-sdk) 编辑 [API 参考](https://docs.buckaroo.io/reference)。 。 。 .
2.  确认你正在 [最新发布](https://www.npmjs.com/package/@buckaroo/buckaroo_sdk)。 。 。 .
3.  重新提出这个问题: `mode: 'TEST'` 并检查完整的响应,包括状态子代码和消息.
4.  校验您的推力 URL 从您的网络外部可以到达 。 Buckaroo从固定的IP地址和端口发送推推消息,所以确保这些消息在您的允许列表中. 见 [推动消息](https://docs.buckaroo.io/docs/integration-push-messages) 用于当前列表.

还卡住? 联系我们,并包括您的Node.js版本, SDK版本, 您调用的服务和动作, 错误消息和交易密钥 .

-   **错误报告和特性请求 :** [打开一个问题](https://github.com/buckaroo-it/BuckarooSDK_Node/issues)
-   **技术支持:** [支持@ buckaroo.nl](mailto:support@buckaroo.nl)
-   **电话:** +31(0)30 711 50 50
-   **网关状态 :** [(原始内容存档于2017-10-21). status.buckaroo.io](https://status.buckaroo.io/)

* * *

## 贡献

当开发者帮助改进 Buckaroo SDK 时,我们真的很感激。 请读我们的 [贡献准则](https://github.com/buckaroo-it/BuckarooSDK_Node/blob/master/CONTRIBUTING.md) 在打开拉出请求之前,并瞄准 `master` 树枝.

找到安全问题了吗? 请私下报到 [支持@ buckaroo.nl](mailto:support@buckaroo.nl) 而不是公开讨论.

* * *

## 版本

我们遵循语义化的版本(`MAJOR.MINOR.PATCH`:

-   **大师** ——打破需要额外测试和谨慎的变动.
-   **毛里塔尼亚** ——影响有限的新功能.
-   **帕齐** ——只修复错误和热修.

所有更改均记录在 [更改日志](https://github.com/buckaroo-it/BuckarooSDK_Node/blob/master/CHANGELOG.md) 报告 [页 次](https://github.com/buckaroo-it/BuckarooSDK_Node/releases)。 。 。 .

* * *

## 许可证

此 SDK 是开源软件, 许可使用 [麻省理工学院许可证](https://github.com/buckaroo-it/BuckarooSDK_Node/blob/master/LICENSE)。 。 。 .

* * *

由我小心地制作 由我负责制作 [白鲸](https://www.buckaroo.nl/)。 。 。 .  
此文档可能更改; 类型和语言错误是可能的.

## 常见问题

### @buckaroo/buckaroo\_sdk 是什么？

袋鼠支付 SDK

### 如何安装 @buckaroo/buckaroo\_sdk？

在项目目录运行 npm install @buckaroo/buckaroo\_sdk，或使用 pnpm add / yarn add / bun add。

### @buckaroo/buckaroo\_sdk 支持 TypeScript 吗？

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

### @buckaroo/buckaroo\_sdk 支持 ESM 还是 CommonJS？

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

### @buckaroo/buckaroo\_sdk 需要什么版本的 Node\.js？

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

### @buckaroo/buckaroo\_sdk 可以商用吗？

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

### @buckaroo/buckaroo\_sdk 的下载量有多少？

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

### @buckaroo/buckaroo\_sdk 还在维护吗？

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