# @a2seven/yoo-checkout 中文文档

规范地址：https://npmcn.com/package/%40a2seven/yoo-checkout/

版本：1\.1\.4
npm 元数据更新时间：2022-09-08T14:48:02.963Z
中文译文更新时间：2026-11-05T22:51:49.344Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：84.7 kB，112 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=12
- 运行依赖：3 个
- 首次发布：2021-02-26T11:18:59.373Z
- 最新版本发布：2022-08-29T13:58:27.554Z
- 近 30 天下载量：10632（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 0 个）

## 中文简介

刘. 检查出 API v3

## 安装

```sh
npm install @a2seven/yoo-checkout
```

也可以使用：`pnpm add @a2seven/yoo-checkout`、`yarn add @a2seven/yoo-checkout`、`bun add @a2seven/yoo-checkout`

## README

# 刘. API SDK( 非官方) 检查

[![A@SEVEN](https://i.ibb.co/my3rNCm/logo1.png)](https://a2seven.com/) [![npm version](https://img.shields.io/npm/v/@a2seven/yoo-checkout.svg)](https://npmcn.com/package/%40a2seven/yoo-checkout/npmjs.com/package/@a2seven/yoo-checkout) [![license](https://img.shields.io/npm/l/@a2seven/yoo-checkout.svg)](https://npmcn.com/package/%40a2seven/yoo-checkout/npmjs.com/package/@a2seven/yoo-checkout) [![npm version](https://img.shields.io/badge/Support%20us-A2Seven-41B883.svg)](https://a2seven.com/) [读取](https://npmcn.com/package/%40a2seven/yoo-checkout/README.ru.md) на русском!

[刘. 离职](https://yookassa.ru/) - 网上付款的普遍解决办法。 刘人. 取出API是建立在REST-原理上,与真实对象合作,具有可预见的行为. 使用此API,您可以发送支付请求,为重复收费保存支付信息(并包括自动支付),进行退款以及更多. API使用HTTP作为主要协议,这意味着它适合在任何可以和HTTP库(例如cURL)合作的编程语言中进行开发. 认证使用 Basic Auth, 这样您就可以直接从浏览器中发出第一个请求 . API支持POST并获取请求. POST 请求使用 JSON 参数,获得请求与查询字符串的工作. API总是以JSON格式返回一个响应,无论请求的类型如何.

## 认证

要认证请求, 您需要使用 HTTP Basic Auth 。 在作为用户名的请求信头中,您需要通过位于YooKassa的商店的ID,作为密码 - 您的秘密密钥( 它必须来自 sms 的密码生成并激活)

带有认证的示例请求

```bash
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -u <shopId>:<secretKey>
```

## 目 录

在API语境下,"一能"指多个请求的处理方式与单一请求相同. 指如果收到重复请求,使用相同的参数,在回复中会得到原始请求的结果. 这种行为有助于避免交易发生不必要的重复. 例如,如果网络出现问题,且连接在支付时被中断,可以安全地重复请求,只要你想要多次. 请求是默认的,因为它们没有不良后果. 使用Idepotence-Key标题(或"idepotence key")来确保POST请求的"一能".

带有一元密钥的查询示例

```bash
curl https://api.yookassa.ru/v3/refunds \
  -X POST \
  -u <shopId>:<secretKey> \
  -H 'Idempotence-Key: <Idempotency key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
      }'
```

如果用相同的数据和相同的密钥重复请求,API会将其作为重复请求处理. 如果请求中的数据是相同的,而"同能"密钥是不同的,则请求作为新请求执行. 您可以在“ 同上”-“关键”标题中将操作中特有的任何价值传递给您。 我们建议使用V4UUID. YooKassa在第一次请求后提供24小时的自首能力,然后将第二次请求作为新的请求处理.

## 同步

YooKassa 立即处理收到的请求并返回处理结果("成功"或"失败"). 如果在30秒内无法给出确切的响应,例如由于收购者一方出现问题,柳克萨会返回HTTP代码500并尝试取消操作. 为了找出请求的最终结果,用相同的数据和相同的同源密钥来重复请求. 建议的重复频率为每分钟一次,直到YooKassa报告HTTP 500以外的响应.

## HTTP 响应代码

如果请求得到成功处理,API会返回HTTP代码200和响应正文. 如果处理过程中发生出错,API会返回出错对象和标准HTTP代码.

| HTTP 代码 | 错误代码 | 解释 |
| --- | --- | --- |
| 400个 | 无效的请求, 不支持 | 请求不正确 。 这种身份往往是由于违反与API互动的规则而发布的. |
| 401 (中文(简体) ) | 无效的证书( c) | \[基本 Auth\] 您的 YooKassa 账户ID 或密钥( 认证用户名和密码) 无效 。 \[OAuth 2. 无效的 OAuth 令牌: 它无效, 过时, 或已被撤销 。 再次请求代号. |
| 403 (韩语) | 禁用内容 | 密钥或 OAuth 令牌正确, 但缺乏完成交易的权限 . |
| 404 (韩语) | 未发现 | 资源未找到 . |
| 429个 | 请求次数太多 | 每个时间单位的请求限额已超过。 尝试降低请求的强度 . |
| 500个 | 内部( s) | 柳卡萨一侧的技术问题. 处理请求的结果不明. 稍后用相同的同能键重复请求. 建议每隔一分钟重复一次请求,直到YooKassa报告业务处理结果. |

示例错误反应机构

```javascript
  {
    "type": "error",
    "id": "ab5a11cd-13cc-4e33-af8b-75a74e18dd09",
    "code": "invalid_request",
    "description": "Idempotence key duplicated",
    "parameter": "Idempotence-Key"
  }
```

SDK 错误反应

```javascript
ErrorResponse {
    "type": "error",
    "id": "ab5a11cd-13cc-4e33-af8b-75a74e18dd09",
    "code": "invalid_request",
    "description": "Idempotence key duplicated",
    "parameter": "Idempotence-Key"
    "errorCode": 401
}
```

## 参考文献

[刘卡萨 API 页面](https://yookassa.ru/developers/api#intro)

## 安装

```bash
npm install @a2seven/yoo-checkout
```

## 开始

```javascript
import { YooCheckout } from '@a2seven/yoo-checkout'; // OR const { YooCheckout } = require('@a2seven/yoo-checkout');

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });
```

## 文档

### [创建付款](https://yookassa.ru/developers/api#create_payment)

```javascript
import { YooCheckout, ICreatePayment  } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';

const createPayload: ICreatePayment = {
    amount: {
        value: '2.00',
        currency: 'RUB'
    },
    payment_method_data: {
        type: 'bank_card'
    },
    confirmation: {
        type: 'redirect',
        return_url: 'test'
    }
};

try {
    const payment = await checkout.createPayment(createPayload, idempotenceKey);
    console.log(payment)
} catch (error) {
     console.error(error);
}
```

### [拿到钱](https://yookassa.ru/developers/api#get_payment)

```javascript
import { YooCheckout } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const paymentId = '21966b95-000f-50bf-b000-0d78983bb5bc';

try {
    const payment = await checkout.getPayment(paymentId);
    console.log(payment)
} catch (error) {
     console.error(error);
}
```

### [扣押付款](https://yookassa.ru/developers/api#capture_payment)

```javascript
import { YooCheckout, ICapturePayment } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const paymentId = '21966b95-000f-50bf-b000-0d78983bb5bc';

const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';

const capturePayload: ICapturePayment = {
    amount: {
        value: '2.00',
        currency: 'RUB'
    }
};

try {
    const payment = await checkout.capturePayment(paymentId, capturePayload, idempotenceKey);
    console.log(payment)
} catch (error) {
     console.error(error);
}
```

### [取消付款](https://yookassa.ru/developers/api#cancel_payment)

```javascript
import { YooCheckout } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const paymentId = '21966b95-000f-50bf-b000-0d78983bb5bc';

const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';

try {
    const payment = await checkout.cancelPayment(paymentId, idempotenceKey);
    console.log(payment)
} catch (error) {
     console.error(error);
}
```

### [获取付款列表](https://yookassa.ru/developers/api#get_payments_list)

```javascript
import { YooCheckout, IGetPaymentList } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const filters: IGetPaymentList = { created_at: { value: '2021-01-27T13:58:02.977Z', mode: 'gte' },  limit: 20 };

try {
    const paymentList = await checkout.getPaymentList(filters);
    console.log(paymentList)
} catch (error) {
     console.error(error);
}
```

### [创建退款](https://yookassa.ru/developers/api#create_refund)

```javascript
import { YooCheckout, ICreateRefund } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';

const createRefundPayload: ICreateRefund = {
    payment_id: '27a3852a-000f-5000-8000-102d922df8db',
    amount: {
        value: '1.00',
        currency: 'RUB'
    }
};

try {
    const refund = await checkout.createRefund(createRefundPayload, idempotenceKey);
    console.log(refund)
} catch (error) {
     console.error(error);
}
```

### [退钱](https://yookassa.ru/developers/api#get_refund)

```javascript
import { YooCheckout } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const refundId = '21966b95-000f-50bf-b000-0d78983bb5bc';

try {
    const refund = await checkout.getRefund(refundId);
    console.log(refund)
} catch (error) {
     console.error(error);
}
```

### [获取退款列表](https://yookassa.ru/developers/api#get_refunds_list)

```javascript
import { YooCheckout, IGetRefundList } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const filters: IGetRefundList = { created_at: { value: '2021-01-27T13:58:02.977Z', mode: 'gte' },  limit: 20 };

try {
    const refundList = await checkout.getRefundList(filters);
    console.log(refundList)
} catch (error) {
     console.error(error);
}
```

### [创建收件](https://yookassa.ru/developers/api#create_receipt)

```javascript
import { YooCheckout, ICreateReceipt } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';

const createReceiptPayload: ICreateReceipt = {
    send: true,
    customer: {
        email: 'test@gmail.com'
    },
    settlements: [
        {
            type: 'cashless',
            amount: {
                value: '2.00',
                currency: 'RUB'
            }
        }
    ],
    refund_id: '27a387af-0015-5000-8000-137da144ce29',
    type: 'refund',
    items: [
        {
            description: 'test',
            quantity: '2',
            amount: {
                value: '1.00',
                currency: 'RUB'
            },
            vat_code: 1,
        }
    ]
};

try {
    const receipt = await checkout.createReceipt(createReceiptPayload, idempotenceKey);
    console.log(receipt)
} catch (error) {
     console.error(error);
}
```

### [拿收据来](https://yookassa.ru/developers/api#get_receipt)

```javascript
import { YooCheckout } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const receiptId = '21966b95-000f-50bf-b000-0d78983bb5bc';

try {
    const receipt = await checkout.getReceipt(receiptId);
    console.log(receipt)
} catch (error) {
     console.error(error);
}
```

### [获取收件列表](https://yookassa.ru/developers/api#get_receipts_list)

```javascript
import { YooCheckout, IGetReceiptList } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey' });

const filters: IGetReceiptList = { created_at: { value: '2021-01-27T13:58:02.977Z', mode: 'gte' },  limit: 20 };

try {
    const receiptList = await checkout.getReceiptList(filters);
    console.log(receiptList)
} catch (error) {
     console.error(error);
}
```

#### 以下功能仅作为下列功能的一部分: [附属程序](https://yookassa.ru/developers/partners-api/basics)

### [创建网点](https://yookassa.ru/developers/api#create_webhook)

```javascript
import { YooCheckout, ICreateWebHook } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey', token: 'your_OAuth_token' });

const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';
const createWebHookPayload: ICreateWebHook = {
    event: 'payment.canceled',
    url: 'https://test.com/hook'
};

try {
    const webhook = await checkout.createWebHook(createWebHookPayload, idempotenceKey);
    console.log(webhook)
} catch (error) {
     console.error(error);
}
```

### [获取 Webhook 列表](https://yookassa.ru/developers/api#get_webhook_list)

```javascript
import { YooCheckout } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey', token: 'your_OAuth_token' });
try {
    const webHookList = await checkout.getWebHookList();
    console.log(webHookList)
} catch (error) {
     console.error(error);
}
```

### [删除网点](https://yookassa.ru/developers/api#delete_webhook)

```javascript
import { YooCheckout, ICreateWebHook } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey', token: 'your_OAuth_token' });

const webHookId = 'wh-edba6d49-ce3e-4d99-991b-4bb164859dc3';

try {
    await checkout.deleteWebHook(webHookId);
} catch (error) {
     console.error(error);
}
```

### [获取商店信息](https://yookassa.ru/developers/api#get_me)

```javascript
import { YooCheckout, ICreateWebHook } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({ shopId: 'your_shopId', secretKey: 'your_secretKey', token: 'your_OAuth_token' });

try {
   const shop = await checkout.getShop();
   console.log(shop)
} catch (error) {
     console.error(error);
}
```

## 运行测试

要安装开发依赖( 运行到软件包所在位置 ) :

```bash
$ npm install
```

运行测试 :

```bash
$ npm run test:unit
```

## 常见问题

### @a2seven/yoo-checkout 是什么？

刘\. 检查出 API v3

### 如何安装 @a2seven/yoo-checkout？

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

### @a2seven/yoo-checkout 支持 TypeScript 吗？

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

### @a2seven/yoo-checkout 支持 ESM 还是 CommonJS？

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

### @a2seven/yoo-checkout 需要什么版本的 Node\.js？

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

### @a2seven/yoo-checkout 可以商用吗？

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

### @a2seven/yoo-checkout 的下载量有多少？

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

### @a2seven/yoo-checkout 还在维护吗？

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