# @chargily/chargily-pay 中文文档

规范地址：https://npmcn.com/package/%40chargily/chargily-pay/

版本：2\.1\.0
npm 元数据更新时间：2024-05-28T01:12:53.860Z
中文译文更新时间：2026-11-09T10:47:59.681Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：74.4 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-03-10T21:27:06.543Z
- 最新版本发布：2024-05-28T01:12:53.597Z
- 近 30 天下载量：3965（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

JavaScript 库用于收费付费TM Gateway - V2. 通过Algerie Poste的EDAHABIA和SATIM的CIB将电子支付API纳入你的JS项目中最简单和自由的途径.

## 安装

```sh
npm install @chargily/chargily-pay
```

也可以使用：`pnpm add @chargily/chargily-pay`、`yarn add @chargily/chargily-pay`、`bun add @chargily/chargily-pay`

## README

# 欢迎使用 JavaScript 软件包仓库

# 页:1 [收费](https://chargily.com/business/pay "Chargily Pay")TM网关 - V2.

感谢您对JS Packet of Completely PayTM(一个开放源码项目)的兴趣,这是阿尔及利亚一家专门从事支付解决方案和电子商务便利化的领先的Fintech公司Cheldilly的开源项目,该包通过阿尔及利亚的EDAHABIA(Algerie Post)和CIB(SATIM)等广泛的支付方法,为将电子支付API纳入您的JavaScript/Node.js项目提供了最简单和自由的途径.

此软件包由 **阿卜杜拉乌夫·齐纳(签名)[罗法扎因](https://github.com/rofazayn)(中文(简体) )** 并开放给您这样的开发者贡献.

## 关键特性

-   容易与收费支付电子支付网关进行整合
-   支持Algerie Poste的EDAHABIA和SATIM的CIB
-   客户、产品和价格的综合管理
-   高效处理离职和付款链接
-   与 Node.js 和浏览器环境兼容
-   支持webhooks( 仅服务器侧)

## 安装

要将此库纳入您的项目, 您可以使用 npm 或 纱线 :

```shell
npm install @chargily/chargily-pay
```

或者说

```shell
yarn add @chargily/chargily-pay

```

## 开始

在使用库前, 您必须先配置它 [充电 API 密钥](https://dev.chargily.com/pay-v2/api-keys) 并指定模式(测试或活式)。 这里有一个开始的例子:

```ts
import { ChargilyClient } from '@chargily/chargily-pay';

const client = new ChargilyClient({
  api_key: 'YOUR_API_KEY_HERE',
  mode: 'test', // Change to 'live' when deploying your application
});
```

这初始化了收费客户端,准备与收费付费API通信.

## 网络攻击通知

**重要通知 :**

使用webhooks只适合后端环境.

Webhooks 允许您的应用程序通过接收带有 JSON 有效载荷的 HTTP 请求来应对来自 Co收费付费的事件 。 要安全地设置和处理webhooks,您必须在服务器侧环境上执行. 这可确保适当核查和处理网游事件,而不会暴露敏感信息或危及安全问题.

执行网络选择时:

1.  **验证签名 :** 确保请求是正当的,没有附带条件.
2.  **识别事件:** 使用事件类型来确定动作 .
3.  **处理事件:** 根据事件类型执行必要的行动.
4.  **响应200:** 确认收到网签.

### 示例 Webhook 终点

我们将用快件来做这个例子, 所以首先让我们安装一些依赖.

```shell
npm install express body-parser
```

然后安装快取所需的类型

```shell
npm i @types/express --save-dev
```

现在,这里,你可以如何设置一个安全的网络hook端点 使用快讯:

```ts
import bodyParser from 'body-parser';
import express, { Request, Response } from 'express';
import { verifySignature } from '@chargily/chargily-pay';

const API_SECRET_KEY = 'test_secret_key_here';

const app = express();
const port = 4000;

// Middleware to capture raw body as Buffer
app.use(
  bodyParser.json({
    verify: (req: Request, res: Response, buf: Buffer) => {
      (req as any).rawBody = buf;
    },
  })
);

app.post('/webhook', (req: Request, res: Response) => {
  const signature = req.get('signature') || '';
  const payload = (req as any).rawBody;

  if (!signature) {
    console.log('Signature header is missing');
    res.sendStatus(400);
    return;
  }

  try {
    if (!verifySignature(payload, signature, API_SECRET_KEY)) {
      console.log('Signature is invalid');
      res.sendStatus(403);
      return;
    }
  } catch (error) {
    console.log(
      'Something happened while trying to process the request to the webhook'
    );
    res.sendStatus(403);
    return;
  }

  const event = req.body;
  // You can use the event.type here to implement your own logic
  console.log(event);

  res.sendStatus(200);
});

app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`);
});
```

还有一件事,如果你想测试你的本地网页, 我们建议使用这样的工具 [韩国](https://ngrok.com/)。 。 。 .

您可以使用此命令运行 ngrok 为本地机器打开隧道

```shell
ngrok http 4000 # or the port you are using
```

然后,Ngrok会返回一个公开的终点,你可以添加到Chowry的仪表板上,通过去 [这里](https://pay.chargily.com/test/dashboard/developers-corner) 并粘贴您的端点 在 Webhook 端点字段中。 还有,别忘了加 `/webhook` 或者你用来粘贴的URL的 URL 扩展.

## 创建客户

要创建客户,你可以使用 `createCustomer` 方法 :

```ts
const customerData = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  phone: '+213xxxxxxxx',
  address: {
    country: 'DZ',
    state: 'Algiers',
    address: '123 Main St',
  },
  metadata: {
    notes: 'Important customer',
  },
};

client
  .createCustomer(customerData)
  .then((customer) => console.log(customer))
  .catch((error) => console.error(error));
```

这种方法与创建的客户对象返回承诺 .

## 更新客户

为了更新现有客户,请使用 `updateCustomer` 使用客户身份和您想要更新的数据的方法:

```ts
const updateData = {
  email: 'new.email@example.com',
  metadata: { notes: 'Updated customer info' },
};

client
  .updateCustomer('customer_id_here', updateData)
  .then((customer) => console.log(customer))
  .catch((error) => console.error(error));
```

这将更新客户的指定字段并返回更新的客户对象.

## 创建产品

要创建新产品,您可以使用 `createProduct` 方法。 以下是如何创造出一种名为"超级产品"的产品:

```ts
const productData = {
  name: 'Super Product',
  description: 'An amazing product that does everything!',
  images: ['http://example.com/image1.jpg', 'http://example.com/image2.jpg'],
  metadata: { category: 'electronics' },
};

client
  .createProduct(productData)
  .then((product) => console.log(product))
  .catch((error) => console.error(error));
```

这种方法要求 `name` 选择接受 `description`,以 `images`,以及 `metadata`。 。 。 .

## 删除客户

要删除收费付费系统中的客户,您可以使用 `deleteCustomer` 使用客户身份证明的方法:

```ts
client
  .deleteCustomer('customer_id_here')
  .then((response) => console.log(response))
  .catch((error) => console.error(error));
```

这种方法将返回一个表示删除是否成功的答复 .

## 列出客户名单

您可以使用 : `listCustomers` 方法。 使用 `per_page` 参数 :

```ts
client
  .listCustomers(20) // List 20 customers per page
  .then((customersList) => console.log(customersList))
  .catch((error) => console.error(error));
```

答复将包括一份列明的客户名单以及标签细节.

## 更新客户

要更新现有客户,你需要客户的身份证:

```ts
const updatedCustomer = await client.updateCustomer('CUSTOMER_ID', {
  name: 'Jane Doe',
  email: 'jane.doe@example.com',
  phone: '987654321',
  address: {
    country: 'DZ',
    state: 'Oran',
    address: '4321 Main St',
  },
  metadata: {
    custom_field_updated: 'new value',
  },
});
```

此呼叫更新指定的客户并返回更新的客户对象.

## 删除客户

要删除客户,请使用其身份:

```ts
const deleteResponse = await client.deleteCustomer('CUSTOMER_ID');
```

这种方法返回一个显示删除是否成功的响应 .

## 创建产品

要在您的目录中添加新产品 :

```ts
const newProduct = await client.createProduct({
  name: 'Awesome Product',
  description: 'A description of your awesome product',
  images: ['https://example.com/image.png'],
  metadata: {
    category: 'Electronics',
  },
});
```

这创造了新产品并返回了产品对象.

## 更新产品

与客户类似,您可以使用他们的ID更新产品:

```ts
const updatedProduct = await client.updateProduct('PRODUCT_ID', {
  name: 'Even More Awesome Product',
  description: 'An updated description',
  images: ['https://example.com/newimage.png'],
  metadata: {
    category: 'Updated Category',
  },
});
```

这更新了产品的细节并返回了更新后的产品对象.

## 创建价格

要创造出产品的价格,你需要产品的ID:

```ts
const newPrice = await client.createPrice({
  amount: 5000,
  currency: 'dzd',
  product_id: 'PRODUCT_ID',
  metadata: {
    size: 'M',
  },
});
```

这为指定的产品创造了新的价格并返回了价格对象.

## 更新价格

您可以以 ID 更新价格元数据 :

```ts
const updatedPrice = await client.updatePrice('PRICE_ID', {
  metadata: {
    size: 'L',
  },
});
```

这更新了价格的元数据,并返回了更新后的价格对象.

## 创建检出

要创建客户付费的退出会话 :

```ts
const checkout = await client.createCheckout({
  items: [
    {
      price: 'PRICE_ID',
      quantity: 1,
    },
  ],
  success_url: 'https://your-website.com/success',
  failure_url: 'https://your-website.com/failure',
  payment_method: 'edahabia', // Optional, defaults to 'edahabia'
  locale: 'en', // Optional, defaults to 'ar'
  pass_fees_to_customer: true, // Optional, defaults to false
  shipping_address: '123 Test St, Test City, DZ', // Optional
  collect_shipping_address: true, // Optional, defaults to false
  metadata: {
    order_id: '123456',
  },
});
```

这将创建一个新的取出会话并返回取出对象,包括 a `checkout_url` 在那里,你可以引导你的客户 完成他们的支付.

## 创建支付链接

支付链接是您可以与客户共享的支付地址 :

```ts
const paymentLink = await client.createPaymentLink({
  name: 'Product Payment',
  items: [
    {
      price: 'PRICE_ID',
      quantity: 1,
      adjustable_quantity: false,
    },
  ],
  after_completion_message: 'Thank you for your purchase!',
  locale: 'en',
  pass_fees_to_customer: true,
  collect_shipping_address: true,
  metadata: {
    campaign: 'Summer Sale',
  },
});
```

这将创建一个新的支付链接并返回支付链接对象,包括您可以与客户共享的URL.

## 处理价格

### 创建价格

要设定产品价格,可以使用产品标识: 1

```ts
const newPrice = await client.createPrice({
  amount: 5000,
  currency: 'dzd',
  product_id: 'PRODUCT_ID',
  metadata: {
    discount: '10%',
  },
});
```

此调用为指定的产品创造了新的价格并返回了价格对象.

### 更新价格

按其身份更新价格 :

```ts
const updatedPrice = await client.updatePrice('PRICE_ID', {
  metadata: {
    discount: '15%',
  },
});
```

这将更新价格的元数据并返回更新后的价格对象.

### 获取价格

要获取产品的所有价格:

```ts
const prices = await client.listPrices();
```

返回所有价格的标定列表 .

## 办理离职手续

### 创建检出

设立离职手续是启动付款程序的一个关键步骤。 通过指定项目清单(产品和数量)或直接指定总量,可以创建出账. 您还需要提供成功的 URL 和可选的失败 URL , 您的客户在支付程序结束后将会被重定向 .

以下是您如何创建出账:

```ts
const newCheckout = await client.createCheckout({
  items: [
    { price: 'PRICE_ID', quantity: 2 },
    { price: 'ANOTHER_PRICE_ID', quantity: 1 },
  ],
  success_url: 'https://yourdomain.com/success',
  failure_url: 'https://yourdomain.com/failure',
  payment_method: 'edahabia',
  customer_id: 'CUSTOMER_ID',
  metadata: { orderId: '123456' },
  locale: 'en',
  pass_fees_to_customer: false,
});
```

此请求创建一个新的退出会话并返回退出对象, 包括 a `checkout_url` 在那里,您应该引导您的客户完成支付.

### 获取退出

获取特定退出会话的细节 :

```ts
const checkoutDetails = await client.getCheckout('CHECKOUT_ID');
```

这将获取指定的退出会话的细节 .

## 管理支付链接

### 创建支付链接

Paying Links 创建了您可以与客户共享的独有的URL,从而提供了一个多功能的支付请求方式. 如何创造一个:

```ts
const paymentLink = await client.createPaymentLink({
  name: 'Subscription Service',
  items: [{ price: 'PRICE_ID', quantity: 1, adjustable_quantity: false }],
  after_completion_message: 'Thank you for your subscription!',
  locale: 'en',
  pass_fees_to_customer: true,
  collect_shipping_address: true,
  metadata: { subscriptionId: 'sub_12345' },
});
```

这将创建一个与指定细节的新支付链接,并返回包括要与客户共享的URL在内的支付链接对象.

### 更新付款链接

要更新现有的支付链接:

```ts
const updatedLink = await client.updatePaymentLink('PAYMENT_LINK_ID', {
  name: 'Updated Subscription Service',
  after_completion_message: 'Thank you for updating your subscription!',
  metadata: { subscriptionId: 'sub_67890' },
});
```

这将更新指定的支付链接并返回更新对象.

### 获取付款链接

获取特定支付链接的细节 :

```ts
const linkDetails = await client.getPaymentLink('PAYMENT_LINK_ID');
```

此呼叫可获取指定支付链接的细节 .

### 列出支付链接

要列出您的支付链接 :

```ts
const allLinks = await client.listPaymentLinks();
```

返回您创建的所有支付链接的 pagized 列表 .

## 关于收费付费TM软件包

收费PayTM软件包/插件是一套由收费公司出版的开源项目集,以利我们的付款网关融入不同的编程语言和框架. 我们的目标是通过提供方便使用的工具来无缝地接受付款来增强开发者和企业的能力.

## API 文档

关于如何与我们的API融合和在您的项目中使用收费付费TM的详细指示,请参见我们 [API 文档](https://dev.chargily.com/pay-v2/introduction)。 。 。 .

## 开发者社区

加入Telegram上的开发者社群 [电报社区](https://chargi.link/PayTelegramCommunity)

## 如何贡献

我们欢迎各种贡献,无论是错误修正、特性增强、文档改进,还是新的插件/包装开发。 接下来,你可以开始:

1.  **叉存储器 :** 点击此页面右上角的"Fork"按钮创建自己的寄存器副本.
    
2.  **仓库克隆 :** 使用以下命令将您的叉子仓库切入本地机器:
    

```bash
git clone https://github.com/Chargily/chargily-pay-javascript.git
```

3.  **更改 :** 给密码库做你想要的修改或添加 确保遵循我们的编码标准和准则.
    
4.  **测试您的更改 :** 彻底测试您的更改以确保它们能如预期的那样工作.
    
5.  **提交拉动请求 :** 一旦对你的修改感到满意,就向主寄存器提交拉出请求. 我们的团队将审查你们的贡献,并在必要时提供反馈.
    

## 上车

有问题或需要帮助吗? 加入我们的开发者社区 [电报](https://chargi.link/PayTelegramCommunity) 与开发商和团队联系.

感谢您对支付电费的关心! 我们能一起创造出惊人的东西.

编码愉快!

## 常见问题

### @chargily/chargily-pay 是什么？

JavaScript 库用于收费付费TM Gateway - V2\. 通过Algerie Poste的EDAHABIA和SATIM的CIB将电子支付API纳入你的JS项目中最简单和自由的途径\.

### 如何安装 @chargily/chargily-pay？

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

### @chargily/chargily-pay 支持 TypeScript 吗？

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

### @chargily/chargily-pay 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @chargily/chargily-pay 可以商用吗？

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

### @chargily/chargily-pay 的下载量有多少？

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

### @chargily/chargily-pay 还在维护吗？

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