# @basis-theory/apple-pay-js 中文文档

规范地址：https://npmcn.com/package/%40basis-theory/apple-pay-js/

版本：2\.0\.4
npm 元数据更新时间：2026-11-02T18:33:30.118Z
中文译文更新时间：2026-11-07T18:02:51.695Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：41.6 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16
- 运行依赖：3 个
- 首次发布：2023-09-11T19:43:04.090Z
- 最新版本发布：2026-07-07T18:57:22.258Z
- 近 30 天下载量：21165（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 1 个）

## 中文简介

依据 解密 Apple Pay Tokens 的理论工具

## 安装

```sh
npm install @basis-theory/apple-pay-js
```

也可以使用：`pnpm add @basis-theory/apple-pay-js`、`yarn add @basis-theory/apple-pay-js`、`bun add @basis-theory/apple-pay-js`

## README

# 基础理论 苹果支付 JS

![Version](https://img.shields.io/npm/v/%40basis-theory/apple-pay-js) ![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/Basis-Theory/apple-pay-js/release.yml) ![License](https://img.shields.io/npm/l/%40basis-theory%2Fapple-pay-js)

用于解密Node.js环境中的 Apple Pay Tokens 工具库.

## 特征

-   **苹果支付 [键盘](https://developer.apple.com/documentation/passkit/apple_pay/payment_token_format_reference) 解密**:安全地解密用户授权的Apple Pay交易令牌,使用易交互界面.
    
    | 加密 | 地区 | 支助 |
    | --- | --- | --- |
    | RSA v1 请检查url=值 (帮助) | 中国 | ✅ |
    | 欧共体 v1 | 所有其他国家 | ✅ |
    
-   **付款处理证书旋转**: 永远不要担心因为证书旋转不可预测的行为而丢失付款. 只要将两个证书都添加到解密上下文中,并放心在旋转窗口时会同时解密出新和旧的令牌.
    
-   **自动解密策略检测**:用于解密苹果的"支付托肯"的透明集成,而不管使用的加密标准如何.
    

## 苹果支付设置

使用此软件包的一个先决条件是,您必须完成您的 Merchant Apple Pay 设置 。 这可能是一个耗时的过程,所以下面的指南会帮助您获得分步指示,以获取必要的文件来发布并解密Apple Pay Tokens:

1.  [苹果开发者程序注册](https://npmcn.com/package/%40basis-theory/apple-pay-js/guides/apple-developer-program-enrollment.md)
2.  [创建商机标识](https://npmcn.com/package/%40basis-theory/apple-pay-js/guides/create-merchant-id.md)
3.  [创建付款处理证书](https://npmcn.com/package/%40basis-theory/apple-pay-js/guides/create-payment-processing-certificate.md)
4.  [创建商机身份证书](https://npmcn.com/package/%40basis-theory/apple-pay-js/guides/create-merchant-identity-certificate.md)

为了在您前端使用 Apple Pay 来收取付款, Apple 有以下特定指南:

-   [网页](https://applepaydemo.apple.com/)
-   [iOS系统](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app)

## 安装

使用国家防范机制安装软件包:

```shell
npm install @basis-theory/apple-pay-js --save
```

或者亚恩:

```shell
yarn add @basis-theory/apple-pay-js
```

## 节点.js

下面的例子显示如何使用来自此寄存器的样本从文件系统将证书加载到缓冲器中. 但你可以从你的KMS,秘密管理器,配置等设备中装入.

如果您需要帮助理解在自己的系统中解密和操纵各种形式的持卡人数据的风险, [联系我们](https://basistheory.com/contact)。 。 。 .

```javascript
import { ApplePaymentTokenContext } from '@basis-theory/apple-pay-js';
import fs from 'fs';
import token from './test/fixtures/ec/token.new.json';

// create the decryption context
const context = new ApplePaymentTokenContext({
  // add as many merchant certificates you need
  merchants: [
    {
      // optional certificate identifier
      identifier: 'merchant.basistheory.com-old',
      // the certificate and the private key are Buffers in PEM format
      certificatePem: fs.readFileSync(
        './test/fixtures/ec/apple/apple_pay.new.pem'
      ),
      privateKeyPem: fs.readFileSync(
        './test/fixtures/ec/apple/private.new.key'
      ),
    },
    {
      identifier: 'merchant.basistheory.com-new',
      certificatePem: fs.readFileSync(
        './test/fixtures/ec/apple/apple_pay.new.pem'
      ),
      privateKeyPem: fs.readFileSync(
        './test/fixtures/ec/apple/private.new.key'
      ),
    },
    {
      identifier: 'merchant.basistheory.china',
      certificatePem: fs.readFileSync(
        './test/fixtures/rsa/apple/apple_pay.pem'
      ),
      privateKeyPem: fs.readFileSync('./test/fixtures/rsa/apple/private.key'),
    },
  ],
});

try {
  // decrypts Apple's PKPaymentToken paymentData
  console.log(context.decrypt(token.paymentData));
} catch (error) {
  // couldn't decrypt the token with given merchant certificates
}
```

## 反应堆

此软件包可用于 [反应堆](https://developers.basistheory.com/docs/concepts/what-are-reactors) 上下文。 下面的例子说明如何解密苹果支付符并按规定为DPAN提供保险.

```javascript
const { Buffer } = require('buffer');
const { ApplePaymentTokenContext } = require('@basis-theory/apple-pay-js');
const {
  CustomHttpResponseError,
} = require('@basis-theory/basis-theory-reactor-formulas-sdk-js');

module.exports = async function (req) {
  const {
    bt,
    args: {
      applePayToken: { paymentData, ...applePayToken },
    },
    configuration: {
      PRIMARY_CERTIFICATE_PEM,
      PRIMARY_PRIVATE_KEY_PEM,
      SECONDARY_CERTIFICATE_PEM,
      SECONDARY_PRIVATE_KEY_PEM,
    },
  } = req;

  // creates token context from certificates / keys configured in Reactor
  const context = new ApplePaymentTokenContext({
    merchants: [
      {
        certificatePem: Buffer.from(PRIMARY_CERTIFICATE_PEM),
        privateKeyPem: Buffer.from(PRIMARY_PRIVATE_KEY_PEM),
      },
      {
        certificatePem: Buffer.from(SECONDARY_CERTIFICATE_PEM),
        privateKeyPem: Buffer.from(SECONDARY_PRIVATE_KEY_PEM),
      },
    ],
  });

  try {
    // decrypts Apple's PKPaymentToken paymentData
    const {
      applicationPrimaryAccountNumber,
      applicationExpirationDate,
      ...restPaymentData
    } = context.decrypt(paymentData);

    // vaults Apple Device PAN (DPAN)
    const btToken = await bt.tokens.create({
      type: 'card',
      data: {
        number: applicationPrimaryAccountNumber,
        expiration_month: applicationExpirationDate.slice(2, 4),
        expiration_year: `20${applicationExpirationDate.slice(-2)}`,
      },
    });

    // returns transaction details and vaulted token without sensitive DPAN
    return {
      raw: {
        btToken,
        applePayToken: {
          paymentData: restPaymentData,
          ...applePayToken,
        },
      },
    };
  } catch (error) {
    throw new CustomHttpResponseError({
      status: 500,
      body: {
        message: error.message,
      },
    });
  }
};
```

## 灵感

这个软件包灵感来自 [盛会](https://github.com/spreedly/gala)特别是 [这个叉子](https://github.com/Foxy/foxy-node-apple-pay-decrypt)。 。 。 .

## 常见问题

### @basis-theory/apple-pay-js 是什么？

依据 解密 Apple Pay Tokens 的理论工具

### 如何安装 @basis-theory/apple-pay-js？

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

### @basis-theory/apple-pay-js 支持 TypeScript 吗？

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

### @basis-theory/apple-pay-js 支持 ESM 还是 CommonJS？

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

### @basis-theory/apple-pay-js 需要什么版本的 Node\.js？

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

### @basis-theory/apple-pay-js 可以商用吗？

@basis-theory/apple-pay-js 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basis-theory/apple-pay-js 的下载量有多少？

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

### @basis-theory/apple-pay-js 还在维护吗？

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