# @ariary/pay 中文文档

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

版本：2\.2\.0
npm 元数据更新时间：2026-03-25T11:35:26.200Z
中文译文更新时间：2026-11-06T18:52:35.628Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：140 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-22T17:31:58.004Z
- 最新版本发布：2026-03-25T11:35:26.069Z
- 近 30 天下载量：2606（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

阿里派支付SDK(ariari.mg)——接受马达加斯加的移动货币支付. 创建支付链接,管理产品,跟踪支付状况,处理webhooks. 支持MVola,Orange Money,Airtel Money. 多功能,TypeScript先行.

## 安装

```sh
npm install @ariary/pay
```

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

## README

# @ 薪金/ 薪金

通过Ariari API为马达加斯加移动货币支付SDK.

> **仅服务器侧** -  `secret` 绝对不能在客户端代码中曝光.

## 安装

```bash
yarn add @ariary/pay
```

## 拿你的证件

1.  签名于 [ariari.mg (意大利语)](https://ariari.mg/)
2.  创建工程
3.  你会得到一个 `secret`

## 设置

```ts
import Ariari from '@ariary/pay'

Ariari.config({
  secret: 'your-secret',
})
```

## 如何运作

1.  您的服务器创建 **付款** 数额(以阿里亚斯为单位)
2.  你把终端用户引向返回的 `payment.url` - ariari.mg上的主页
3.  最终用户通过移动货币将钱寄给阿里耶数字并收到 **票号**
4.  最终用户在付款页上输入其票号(或你收集票并打电话) `.pay()` 从后端)
5.  可在 **多个步骤** ——应用的每个出票码都是部分付款
6.  全部支付后, 便会呼叫和/ 或重定向用户

## 创建付款

`Ariari.create()` 接受以下字段:

| 外地 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `amount` | 编号 | 是(无) `productId`(中文(简体) ) | Ariary的付款额 |
| `productId` | 字符串 | 没有 | 产品标识——解决 `amount`, (中文(简体) ), `name`, (中文(简体) ), `imgUrl` 自动 |
| `name` | 字符串 | 没有 | 支付页面上显示的支付标签 |
| `imgUrl` | 字符串 | 没有 | 支付页面上显示的图像 URL |
| `hooks.redirectSuccess` | 字符串 | 没有 | URL 用户在成功时重定向到 |
| `hooks.redirectFailure` | 字符串 | 没有 | URL 用户在失败时被重定向到 |
| `hooks.silentSuccess` | 字符串 | 没有 | 支付全部完成时呼叫 Webhook |
| `hooks.silentProgress` | 字符串 | 没有 | Webhook 调用每笔部分付款 |
| `hooks.silentFailure` | 字符串 | 没有 | Webhook 呼叫付款失败 |

```ts
// with amount only
const payment = await Ariari.create({ amount: 5000 })
console.log(payment.url) // https://pay.ariari.mg/abc123encrypted

// with product (amount, name, imgUrl resolved automatically)
const payment = await Ariari.create({ productId: product.id })

// with product + override amount
const payment = await Ariari.create({ productId: product.id, amount: 3000 })

// with hooks
const payment = await Ariari.create({
  amount: 10000,
  name: 'T-shirt bleu',
  imgUrl: 'https://example.com/img.png',
  hooks: {
    redirectSuccess: 'https://yoursite.com/payment/success',
    redirectFailure: 'https://yoursite.com/payment/failure',
    silentSuccess: 'https://yoursite.com/api/webhook/payment-success',
    silentProgress: 'https://yoursite.com/api/webhook/payment-progress',
    silentFailure: 'https://yoursite.com/api/webhook/payment-failure',
  },
})
```

### 钩子

**`redirect*`** 钩子是浏览器-侧重定向. 在用户完成或失败支付页面后,他们的浏览器会浏览给定的URL. 当支付页面取代当前页面(同为tab导航)时最合适. 如果您在新标签中打开支付页面( N)`target="_blank"`),重定向钩对母页没有任何影响——取而代之的是使用无声钩.

**`silent*`** 钩子是服务器对服务器的webhooks由Ariari后端直接调用. 它们必须是具有有效域名(例如. `https://yoursite.com/api/webhook`) (中文(简体) ). `localhost` 或当地实施伙伴将不起作用——使用ngrok这样的隧道服务促进发展.

两者可以一起使用——例如重定向用户并同时通知您的服务器.

## 跟踪支付

`Ariari.create()` 返回 a `Payment` 具有两种方法的对象:

-   `payment.status()` ——从服务器获取全额支付细节(见下表)
-   `payment.pay(ticketCode)` ——应用后端的出票码(付款页的替代)

```ts
const payment = await Ariari.create({ amount: 5000 })

// fetch payment details
const info = await payment.status()
// info.status → the payment's current state (see below)
// info.rest   → remaining amount to pay
// info.parts  → list of partial payments applied so far

// apply a ticket code from your backend
const result = await payment.pay('Y-1234')
```

### 这个 `status` 字段

这个 `info.status` 字段(不与 `.status()` )表示付款的当前状态:

| 数值 | 说明 |
| --- | --- |
| `Status.PENDING` | 创建付款, 尚未应用出票码 |
| `Status.INCOMPLETE` | 至少适用一个票号,剩余金额 > 0 |
| `Status.PAID` | 全额支付 |
| `Status.FAILED` | 服务器侧出错( 在正常情况下不应发生) |

```ts
import { Status } from '@ariary/pay'

if (info.status === Status.PAID) { ... }
```

## 获取现有付款

存储 `payment.id` 待会再拿回来 `.getPayment()`调用 `.status()` 返回全额支付细节 :

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `id` | 字符串 | 支付身份 |
| `amount` | 编号 | Ariary合计 |
| `rest` | 编号 | 剩余数额 |
| `productId` | 绳子? | 链接产品标识 |
| `name` | 绳子? | 付款标签 |
| `imgUrl` | 绳子? | 图像 URL |
| `status` | 状态 | `PENDING` | `INCOMPLETE` | `PAID` | `FAILED` |
| `parts` | 付款部分 | 部分缴款清单 |
| `createdAt` | 字符串 | 创建日期 |
| `updatedAt` | 字符串 | 上次更新日期 |
| `url` | 字符串 | 支付页面 URL |

```ts
const payment = await Ariari.create({ amount: 5000 })
const paymentId = payment.id // save this

// later
const payment = Ariari.getPayment(paymentId)
const info = await payment.status()
```

## 产品

产品是一个可重复使用的模板,所以你不必发送同样的 `name`, (中文(简体) ), `price`,以及 `imgUrl` 每次你创造报酬。 当你通过一个 `productId` 改为 `Ariari.create()`,产品的数据自动应用于支付.

```ts
// create
const product = await Ariari.products.create({ name: 'Forfait Premium', price: 5000, imgUrl: 'https://example.com/img.png' })

// list all
const products = await Ariari.products.list()

// update
const updated = await Ariari.products.update(product.id, { name: 'Forfait Gold', price: 8000 })

// delete
await Ariari.products.delete(product.id)
```

## 多个实例

使用 `name` 管理不同证书的 Ariari 实例. `Ariari.config()` 直接返回实例.

```ts
const shop = Ariari.config({
  name: 'shop',
  secret: 'secret-a',
})

const billing = Ariari.config({
  name: 'billing',
  secret: 'secret-b',
})

await shop.create({ amount: 5000 })
await billing.create({ productId: 'prod-123' })
```

您也可以稍后检索一个命名实例 `Ariari.get()`。 。 。 .

```ts
const shop = Ariari.get('shop')
```

无 `name`,实例默认为 `"main"` 并采用静态方法(`Ariari.create`, (中文(简体) ), `Ariari.products`, (中文(简体) ), `Ariari.getPayment`) (中文(简体) ).

## 常见问题

### @ariary/pay 是什么？

阿里派支付SDK\(ariari\.mg\)——接受马达加斯加的移动货币支付\. 创建支付链接,管理产品,跟踪支付状况,处理webhooks\. 支持MVola,Orange Money,Airtel Money\. 多功能,TypeScript先行\.

### 如何安装 @ariary/pay？

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

### @ariary/pay 支持 TypeScript 吗？

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

### @ariary/pay 支持 ESM 还是 CommonJS？

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

### @ariary/pay 可以商用吗？

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

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

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

### @ariary/pay 还在维护吗？

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