# @coherentx/coherent 中文文档

规范地址：https://npmcn.com/package/%40coherentx/coherent/

版本：0\.0\.61
npm 元数据更新时间：2026-07-20T13:24:49.023Z
中文译文更新时间：2026-11-10T10:13:35.017Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：67.4 kB，36 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2024-06-16T20:47:04.864Z
- 最新版本发布：2026-07-20T13:24:48.837Z
- 近 30 天下载量：11517（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 8 个）

## 中文简介

连贯支付网关客户端库

## 安装

```sh
npm install @coherentx/coherent
```

也可以使用：`pnpm add @coherentx/coherent`、`yarn add @coherentx/coherent`、`bun add @coherentx/coherent`

## README

# 协调 API

-   [协调 API](https://npmcn.com/package/%40coherentx/coherent/#readme-coherent-api)
    -   [安装](https://npmcn.com/package/%40coherentx/coherent/#readme-installation)
    -   [使用量](https://npmcn.com/package/%40coherentx/coherent/#readme-usage)
        -   [付款](https://npmcn.com/package/%40coherentx/coherent/#readme-payments)
            -   [创建交易( 自动支付)](https://npmcn.com/package/%40coherentx/coherent/#readme-create-a-transaction-aka-payment)
            -   [退款](https://npmcn.com/package/%40coherentx/coherent/#readme-refunds)
            -   [终端](https://npmcn.com/package/%40coherentx/coherent/#readme-terminals)
            -   [交易状态 Webhooks](https://npmcn.com/package/%40coherentx/coherent/#readme-transaction-status-webhooks)
        -   [经常性付款(预付付款计划)](https://npmcn.com/package/%40coherentx/coherent/#readme-recurring-payments-aka-payment-plans)
            -   [将支付计划与交易链接](https://npmcn.com/package/%40coherentx/coherent/#readme-link-payment-plan-to-transactions)
        -   [合伙人商业管理](https://npmcn.com/package/%40coherentx/coherent/#readme-partner-merchant-management)
            -   [API 密钥管理](https://npmcn.com/package/%40coherentx/coherent/#readme-api-key-management)
            -   [Webhook URL 管理器](https://npmcn.com/package/%40coherentx/coherent/#readme-webhook-url-management)

## 安装

使用以下命令安装 API

```sh
npm install coherent
```

添加 `--save` 如果建造一个可部署的.

## 使用量

导入和关闭连接

```js
import {Coherent} from "coherent";

const coherent = new Coherent({
    environment: "TEST", // or "PRODUCTION"
    token: process.env.COHERENT_TOKEN
})
```

### 付款

#### 创建交易( 自动支付)

创建支付链接, 选择通知电子邮件或电话号码

```js
const transaction = await coherent.transactions.create({
    amount: 1000, // The amount in the smallest regular unit, e.g. pennies (£10 = 1000)
    name: `John Smith`, // The name of the patient,
    note: "A test", //optional, what this transaction involves
    email: "support@coherenthealthcare.com", //optional
    emailNotify: true, //optional, `email` receives payment request notification
    patientNote: "Thanks for your payment", //optional, a note visible to the patient during payment
    phone: "+44...", //optional
    smsNotify: true, //optional, `phone` receives SMS payment request notification
    successUrl: "https://example.com/success", //optional, where to redirect to after successful payment
    failureUrl: "https://example.com/failure", //optional, where to redirect to after rejected payment
})

console.log(transaction.uuid)
console.log(transaction.status)
console.log(transaction.paymentUrl)
```

拿到钱

```js
const transaction = await coherent.transactions.get(
    transaction.uuid
)
```

预留付款

````
await coherent.transactions.updateStatus(
    transaction.uuid,
    'void'
)

#### Refunds

```js
await coherent.transactions.refund({
    transactionUuid: transaction.uuid,
    amount: 100,
    reason: 'Anything'
})
````

#### 终端

列出终端

```js
await coherent.terminals.list()
```

命名终端

```js
await coherent.terminals.rename({
    terminalId: '<TYPE>-123455678',
    name: 'The Trusty Terminal'
})
```

发送付款

```js
await coherent.terminals.setTransaction({
    terminalId: '<TYPE>-123455678',
    transactionUuid: 'abcd-1234'
})
```

清除终端

```js
await coherent.terminals.clearTransaction({
    terminalId: '<TYPE>-123455678'
})
```

#### 交易状态 Webhooks

见 [主要文档中的 Webhooks 状态](https://coherenthealthcare.notion.site/coherent-payments-api#626f7331e3964af18bae2949240dd4cc)

### 经常性付款和持有(预付付款计划)

制定付款计划,目前限于每月的经常性付款,或因按要求收费而暂停付款

```js
const plan = await coherent.paymentPlans.create({
    amount: 1000, // The amount in the smallest regular unit, e.g. pennies (£10 = 1000)
    name: `John Smith`, // The name of the patient,
    note: "A test", //optional, what this transaction involves
    startDate: new Date("2025-01-01"), //required except if creating an on_demand plan
    endDate: new Date("2025-03-01"), //optional, the date of the last payment occurrence
    transactionReference: "Invoice123456", //optional, but recommended, and unique per clinic. Transactions relating to this payment plan will have this set
    email: "support@coherenthealthcare.com", //optional
    emailNotify: true, //optional, defaults to true if email is provided
    phone: "+44...", //optional
    smsNotify: true, //optional, defaults to true if phone is provided
    type: "recurring", //optional, defaults to recurring, can be on_demand
    method: "direct_debit", //optional, defaults to direct_debit, can be card
    successUrl: "https://app.coherenthealthcare.com/receipt?token=example", //optional, where the user is sent after successful payment. NOTE: only supported for type = card
})

console.log(plan.uuid)
console.log(plan.status)
console.log(plan.paymentUrl)
```

拿到付款计划

```js
const plan = await coherent.paymentPlans.get(
    plan.uuid
)
```

暂停或取消付款计划

```js
await coherent.paymentPlans.setStatus(
    plan.uuid,
    PaymentPlanStatus.Void 
    // OR PaymentPlanStatus.Paused
    // OR PaymentPlanStatus.Resumed
)
```

> 您可以将第二个参数设置为:
> 
> -   Void: 取消付款计划和相关时间表
> -   暂停: 暂停支付计划的时间表, 计划暂停时的意外事件会被永远跳过
> -   复会:恢复支付计划时间表,恢复到停发或误发前的状态.

重新发送通知

```js
await coherent.paymentPlans.notify(
    plan.uuid
)
```

按需付费计划

```js
await coherent.paymentPlans.charge(
    plan.uuid,
    { amount: 2000, reference: "INVOICE-1234" } // optional
)
```

收回一项直接调试计划,该计划因资金不足而未能收款(`PaymentPlanStatus.InsufficientFunds`() 恢复计划,并立即向本批付款发出一次呼吁:

```js
const { transactionUuid } = await coherent.paymentPlans.resumeAndCharge(
    plan.uuid
)
```

#### 将支付计划与交易链接

每一次重复一次付款计划,就会产生交易,然后会像往常一样触发交易网.

为了将产生的交易与付款计划联系起来,设置 `transactionReference` 支付计划的制定.

您在收到 Webhook 时不会有与给定的 UUID 交易的记录, 但当您收到交易时, 它应该包含较早时设定的引用 `{}.paymentPlan.transactionReference`。 。 。 .

### 合伙人商业管理

合作伙伴可以管理他们的商家,包括列出商家,管理API密钥,并配置webhook URL.

> **说明:** API 键和webhook URL在入职时自动创建( )`startOnboarding`) (中文(简体) ). 只有在登入后想要旋转密钥或更改webhook URL时,才需要下面的终点.

列出属于此伙伴的所有商家

```js
const merchants = await coherent.merchants.listMerchants()
// Returns: [{ uuid, name, email, phone?, onboarded }]
```

#### API 密钥管理

为商家创建新的 API 密钥

```js
const result = await coherent.merchants.createApiKey('merchant-uuid')
console.log(result.apiKey) // Store this securely — it cannot be retrieved again
```

列出商家现有的 API 密钥

```js
const keys = await coherent.merchants.listApiKeys('merchant-uuid')
// Returns: [{ uuid, createdTime }]
```

#### Webhook URL 管理器

获取当前商家的 Webhook URL

```js
const webhook = await coherent.merchants.getWebhookUrl('merchant-uuid')
console.log(webhook.webhookUrl) // null if not set
```

更新商家的网络浏览 URL

```js
await coherent.merchants.updateWebhookUrl('merchant-uuid', 'https://example.com/webhook')
```

## 常见问题

### @coherentx/coherent 是什么？

连贯支付网关客户端库

### 如何安装 @coherentx/coherent？

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

### @coherentx/coherent 支持 TypeScript 吗？

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

### @coherentx/coherent 支持 ESM 还是 CommonJS？

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

### @coherentx/coherent 可以商用吗？

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

### @coherentx/coherent 的下载量有多少？

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

### @coherentx/coherent 还在维护吗？

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