# @bloque/payments 中文文档

规范地址：https://npmcn.com/package/%40bloque/payments/

版本：0\.2\.1
npm 元数据更新时间：2026-08-27T16:10:42.241Z
中文译文更新时间：2026-11-08T07:58:38.562Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bloque/payments
原文对照：https://npmcn.com/package/%40bloque/payments/?lang=original
源码仓库：https://github.com/bloque-app/payments

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

- 包体积（解压后）：73.9 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2025-12-18T19:34:39.459Z
- 最新版本发布：2026-07-01T18:21:17.175Z
- 近 30 天下载量：6345（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

官方 Bloque SDK 用于创建和管理支付和结账.

## 安装

```sh
npm install @bloque/payments
```

也可以使用：`pnpm add @bloque/payments`、`yarn add @bloque/payments`、`bun add @bloque/payments`

## README

# Bloque 付款 SDK

官方TypeScript/JavaScript SDK用于整合Bloque支付.

## 安装

```bash
bun add @bloque/payments
```

## 认证

SDK支持三证模式:

| 证书 | 前缀 | 何处 | 目的 |
| --- | --- | --- | --- |
| **密钥** | `sk_test_` 编号 : `sk_live_` | 只有服务器 | 以短寿命 JWT 交换 `/origins/api-keys/exchange` |
| **可公布的密钥** | `pk_test_` 编号 : `pk_live_` | 浏览器 | 识别商家; 只读( 查看推车) |
| **客户端秘密** | 日本 | 浏览器 | JWT范围为单一的退出会议(`checkout.pay`(中文(简体) ) |

### 初始化( 建议)

```ts
import { Bloque } from '@bloque/payments';

const bloque = new Bloque({
  mode: 'sandbox',
  secretKey: process.env.BLOQUE_SECRET_KEY!,
  webhookSecret: process.env.BLOQUE_WEBHOOK_SECRET, // optional
});
```

SDK自动交换JWT的秘密密钥并缓存(在过期前刷新出1分).

### 初始化( 遗留)

```ts
const bloque = new Bloque({
  mode: 'sandbox',
  accessToken: process.env.BLOQUE_ACCESS_TOKEN!, // deprecated — use secretKey
});
```

## 快速启动: 创建退出

```ts
import { Bloque } from '@bloque/payments';

const bloque = new Bloque({
  mode: 'sandbox',
  secretKey: process.env.BLOQUE_SECRET_KEY!,
});

const checkout = await bloque.checkout.create({
  name: 'Pack Profesional de Productividad',
  description:
    'Periféricos premium para trabajo intensivo y alto rendimiento',
  asset: 'COPM/2',
  image_url: 'https://cdn.bloque.app/checkouts/productivity-pack.png',
  items: [
    {
      name: 'Teclado mecánico Keychron K2',
      description: 'Wireless, RGB, switches Blue',
      amount: 450_000_00,
      quantity: 2,
      image_url: 'https://cdn.bloque.app/items/keychron-k2.png',
    },
    {
      name: 'Mouse Logitech MX Master 3S',
      description: 'Inalámbrico, sensor 8K DPI',
      amount: 380_000_00,
      quantity: 1,
      image_url: 'https://cdn.bloque.app/items/mx-master-3s.png',
    },
  ],
  success_url: 'https://bloque.app/success',
  cancel_url: 'https://bloque.app/cancel',
  merchant: {
    name: 'Bloque',
    theme: {
      primary: '#10b981',
      primary_foreground: '#ffffff',
      background: '#f8fafc',
      surface: '#ffffff',
      border: '#d1d5db',
      input_border: '#10b98166',
    },
  },
  payment_methods: ['card', 'pse', 'cash'],
  payeer: {
    name: 'Nestor Cortina',
    email: 'nestor@bloque.team',
  },
});

console.log('Checkout URL:', checkout.url);
```

## API 密码

### `Bloque` 配置

```ts
type BloqueConfig = {
  mode: 'sandbox' | 'production';
  secretKey: string;        // sk_test_... or sk_live_...
  timeout?: number;         // request timeout in ms (default 10_000)
  maxRetries?: number;      // retry count (default 2)
  webhookSecret?: string;
};

/** @deprecated Use BloqueConfig with secretKey instead */
type BloqueConfigLegacy = {
  mode: 'sandbox' | 'production';
  accessToken: string;
  timeout?: number;
  maxRetries?: number;
  webhookSecret?: string;
};
```

### 离职

#### `bloque.checkout.create(params)`

```ts
type CheckoutParams = {
  name: string;
  description?: string;
  image_url?: string;
  asset?: 'COPM/2' | 'DUSD/6';
  items: {
    name: string;
    description?: string;
    amount: number;
    quantity: number;
    image_url?: string;
  }[];
  success_url: string;
  cancel_url: string;
  metadata?: Record<string, string | number | boolean>;
  merchant?: {
    name: string;
    theme: {
      primary: string;
      primary_foreground: string;
      background: string;
      surface: string;
      border: string;
      input_border: string;
    };
  };
  payment_methods?: ('card' | 'pse' | 'cash')[];
  expires_at?: string;
};
```

注释:

-   `asset` 默认为 `DUSD/6` 当省略时.
-   创建请求使用 `redirect_url` 来源于 `success_url`。 。 。 .

响应形状 :

```ts
type Checkout = {
  id: string;
  urn: string;
  object: 'checkout';
  url: string;
  client_secret: string;   // scoped JWT for browser-side checkout
  status: 'pending' | 'paid' | 'expired' | 'deposited' | 'cancelled';
  amount_total: number;
  amount_subtotal: number;
  asset: 'COPM/2' | 'DUSD/6';
  items: {
    name: string;
    description?: string;
    amount: number;
    quantity: number;
    image_url?: string;
  }[];
  metadata?: Record<string, string | number | boolean>;
  created_at: string;
  updated_at: string;
  expires_at: string | null;
};
```

通过 `client_secret` 改为 `@bloque/payments-core` 或者说 `@bloque/payments-react` 在浏览器上授权执行付款.

#### `bloque.checkout.retrieve(checkoutId)`

```ts
const checkout = await bloque.checkout.retrieve('checkout_123');
```

#### `bloque.checkout.cancel(checkoutId)`

```ts
const checkout = await bloque.checkout.cancel('checkout_123');
```

### 付款

#### `bloque.payments.create(params)`

支持的直接支付方法是 `card`, (中文(简体) ), `pse`,以及 `cash` (图 `POST /payments/:type` 在服务器上).

```ts
const payment = await bloque.payments.create({
  paymentUrn: 'did:bloque:payments:123e4567-e89b-12d3-a456-426614174000',
  payment: {
    type: 'card',
    data: {
      cardNumber: '4111111111111111',
      cardholderName: 'John Doe',
      expiryMonth: '12',
      expiryYear: '2028',
      cvv: '123',
      email: 'john@example.com',
      installments: 1,
      currency: 'COP',
    },
  },
});
```

付款答复:

```ts
type PaymentResponse = {
  id: string;
  object: 'payment';
  status: 'approved' | 'rejected' | 'pending';
  amount: number;
  currency: string;
  created_at: string;
  three_ds?: { current_step: string; iframe: string };
};
```

#### `bloque.payments.getStatus(paymentId)`

由URN(如:. `did:bloque:payments:...`)在3DS挑战后.

```ts
const latest = await bloque.payments.getStatus(payment.id);
```

### 3D 安全( 直接 API)

当您用 3DS 处理卡片支付服务器侧面时, 通过浏览器指纹字段和可选的沙盒方案:

```ts
import type { BrowserInfo } from '@bloque/payments';

function browserInfoFromRequest(req: {
  headers: Record<string, string | string[] | undefined>;
}): BrowserInfo {
  const ua = String(req.headers['user-agent'] ?? '');
  const accept = String(req.headers['accept'] ?? '*/*');
  const lang = String(req.headers['accept-language'] ?? 'en');
  return {
    browser_user_agent: ua,
    browser_language: lang,
    browser_color_depth: '24',
    browser_screen_height: '900',
    browser_screen_width: '1440',
    browser_tz: '0',
  };
}

const payment = await bloque.payments.create({
  checkoutId: 'checkout_123',
  payment: {
    type: 'card',
    data: {
      cardNumber: '4111111111111111',
      cardholderName: 'John Doe',
      expiryMonth: '12',
      expiryYear: '2028',
      cvv: '123',
      email: 'john@example.com',
      is_three_ds: true,
      browser_info: browserInfoFromRequest(req),
      three_ds_auth_type: 'challenge_v2', // sandbox only; omit in production
    },
  },
});

if (payment.three_ds?.iframe) {
  // 1) Decode HTML entities if the gateway returns escaped HTML
  // 2) If iframe is a URL (https://...), use <iframe src="...">
  // 3) Otherwise use <iframe srcdoc={decodedHtml}> with sandbox allow-scripts allow-forms allow-popups
  // 4) Show Mastercard ID Check branding before/around the challenge where required
  // 5) Poll until terminal state:
  let status = payment.status;
  while (status === 'pending') {
    await new Promise((r) => setTimeout(r, 3000));
    const next = await bloque.payments.getStatus(payment.id);
    status = next.status;
  }
}
```

字段名称 `BrowserInfo` 匹配 Bloque 付款 API (`browser_user_agent`, (中文(简体) ), `browser_language`(见a/c.5/49/70,附件).

### 网络呼号

校验webhook 签名( I)`HMAC-SHA256`:

```ts
const isValid = bloque.webhooks.verify(
  rawBody,
  signature,
  { secret: process.env.BLOQUE_WEBHOOK_SECRET! },
);
```

您也可以设置 `webhookSecret` 期间 `Bloque` 初始化和省略 `options` 内 `verify`。 。 。 .

## 示例

完整的例子见:

-   `examples/basic-checkout.ts`

## 常见问题

### @bloque/payments 是什么？

官方 Bloque SDK 用于创建和管理支付和结账\.

### 如何安装 @bloque/payments？

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

### @bloque/payments 支持 TypeScript 吗？

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

### @bloque/payments 支持 ESM 还是 CommonJS？

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

### @bloque/payments 需要什么版本的 Node\.js？

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

### @bloque/payments 可以商用吗？

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

### @bloque/payments 的下载量有多少？

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

### @bloque/payments 还在维护吗？

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