# @astropay/astropay-sdk 中文文档

规范地址：https://npmcn.com/package/%40astropay/astropay-sdk/

版本：4\.2\.0
npm 元数据更新时间：2023-09-11T12:41:23.732Z
中文译文更新时间：2026-11-07T01:14:38.650Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：1.6 MB，66 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：2 个
- 首次发布：2022-06-09T03:12:43.346Z
- 最新版本发布：2023-09-11T12:41:23.568Z
- 近 30 天下载量：24004（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 0 个）

## 中文简介

AstroPay 官方客户端,用于方便的前端集成到 One Touch

## 安装

```sh
npm install @astropay/astropay-sdk
```

也可以使用：`pnpm add @astropay/astropay-sdk`、`yarn add @astropay/astropay-sdk`、`bun add @astropay/astropay-sdk`

## README

[![AstroPay](https://getapp.astropay.com/img/astropay/2023/logo-black.svg)](http://www.astropay.com/)

**用于 JavaScript 的 Astropay SDK**

AstroPay SDK用于方便产品集成

[![NPM version](https://img.shields.io/npm/v/@astropay/astropay-sdk/latest.svg)](https://www.npmjs.com/package/@astropay/astropay-sdk) [![NPM downloads](https://img.shields.io/npm/dm/@astropay/astropay-sdk.svg)](https://www.npmjs.com/package/@astropay/astropay-sdk) ![Typing](https://img.shields.io/npm/types/typescript.svg) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)

## 目录

-   [目录](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-table-of-contents)
-   [开始](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-getting-started-)
    -   [先决条件](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-prerequisites-)
    -   [安装](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-installation-)
-   [使用量](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-usage-)
    -   [平台输入](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-platform-init-)
    -   [活动听众](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-event-listeners-)
    -   [方法调用](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-method-call-)
-   [支持的语言](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-supported-languages-)
-   [提升](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-updrading-)
    -   [V4 - 最新数据](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-v4---latest-)
    -   [五.3](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-v3-)
    -   [五. 2级](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-v2-)
-   [支助](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-support-)
-   [许可证](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-license-)

## 开始

### 先决条件

-   节点.js v14 或更高.

### 安装

使用您最喜欢的软件包管理器安装 `@astropay/astropay-sdk` 软件包.

**国家预防机制**数字 :

```shell

npm install --save @astropay/astropay-sdk

```

**亚伦:**

```shell

yarn add @astropay/astropay-sdk

```

## 使用量

### 平台输入

_**SDK 配置参数**_

要正确配置 SDK,init 方法需要接收带有以下属性的APP ID和配置对象:

| 财产 | 类型 | 默认值 | 说明 |
| :-- | :-: | :-: | :-- |
| 环境 | `'sandbox'` | `'production'` | `undefined` | `'production'` | 报恩取用. |
| 语言 | [支持的语言](https://npmcn.com/package/%40astropay/astropay-sdk/#readme-languages) 未定义 | `'en'` | Init 对象上设置的语言优先于该对象上的 URL 属性语言 `ASTROPAY_RESPONSE` |
| 日志 | Logger 实例 `undefined` | `undefined` | 在 SDK 内使用控制台日志动作 |

如果在init上没有设置语言属性, SDK 将尝试在 URL 上使用语言查询参数 `ASTROPAY_RESPONSE`。如果两者没有设定,则SDK将使用默认语言: `english`

_**代码片段 :**_

```typescript
import AstropaySDK, { ClientConfiguration, ConsoleLogger, DepositStatus } from  '@astropay/astropay-sdk';

// SDK Config
const config: ClientConfiguration = {
    environment: 'production',
    language: 'en',
    logger: new ConsoleLogger(),
};

// SDK Init
AstroPaySDK.init(APP_ID, config);
```

### 活动听众

设置事件收听器, 接收回调 funcion 作为参数 .

```typescript
// SDK Event Listeners
const eventListening = AstroPaySDK.getEventListener('deposit');
eventListening.on('close', (data) => {
    console.log('data on close event', data);
    }
);
```

### 方法调用

_**方法参数**_

当调用其中一种产品方法(Deposit QQ Cashout QQ Onboarding)以有效打开SDK时,被注意的参数是: `ASTROPAY_RESPONSE` 编辑 `configUI` 属性来根据您的需要操纵 UI :

| 财产 | 类型 | 默认值 | 说明 |
| :-- | :-: | :-: | :-- |
| 阿斯托佩克语NAME | 对象 | **不适用:** 强制发送呼叫 | 您拨打时由 AstroPay 服务提供的输入对象 。 请检查access-date=中的日期值 (帮助) Usage 一节的示例. |

| 财产 | 类型 | 默认值 | 说明 |
| :-- | :-: | :-: | :-- |
| 背景情况 | `'static'` | `'active'` | `'static'` | 如果你想要的话 _**AstroPay SDK 软件**_ 当用户点击 Backdrop( 内容外部) 时关闭 `active`  
若为 `static`,背景元素不会在用户点击外部内容时关闭 SDK 模式. |
| zindex 数据 | 字符串 | `'auto'` | Z-index属性指定弹出物的堆栈顺序.  
更大的堆栈顺序总是在下堆栈顺序的元素前. |

> 注意到 `ASTROPAY_RESPONSE` 应配置产品调用的真实值(Disposit QQ Cashout QQ上载)。 注意不要就这些属性发送错误的值

_**交存**_

```typescript
// Non mandatory object
const configUI = {backdrop:'active', zIndex:'auto'}

// Mandatory object
const ASTROPAY_RESPONSE = {  
    "merchant_deposit_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  		
    "deposit_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
    "status":  "PENDING",  
    "url":  "https://onetouch-sandbox.astropay.com/deposit/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
    "type":  "default"  
};

// Show the DEPOSIT client
AstropaySDK.deposit(ASTROPAY_RESPONSE);

```

_**现金流出**_

```typescript
const ASTROPAY_RESPONSE = {  
    "merchant_cashout_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  		
    "cashout_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
    "status":  "PENDING",  
    "url":  "https://onetouch-sandbox.astropay.com/cashout/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe"
};

// Show the CASHOUT client
AstropaySDK.cashout(ASTROPAY_RESPONSE);
```

_**上岗**_

```typescript
const ASTROPAY_RESPONSE = {  
    "platform_merchant_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  
    "merchant_name": "Merchant"
    "onboarding_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
    "status":  "PENDING",  
    "url":  "https://onetouch-sandbox.astropay.com/onboarding/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",
};

// Show the ONBOARDING client
AstropaySDK.onboarding(ASTROPAY_RESPONSE);
```

_**付款**_

这种方法收到 AstroPay 响应, 并返回一个承诺, 它将解析一个对象的支付数据, 并随您的意愿在您的网站上显示 .

```typescript
//Method Response 
AstropaySDK.payment(AstropayResponse): Promise<PaymentData>
```

_**方法响应接口**_

```typescript
interface PaymentData {
  amount: number;
  currency: string;
  status: string;
  payment_type: string;
  data: {
        txt_qr: string;
        image: string;
    } & Record<string, any>
}
```

返回的对象字段 :

-   数额: 付款数额
-   货币: 支付货币
-   缴款情况
-   支付 类型: 使用此支付所选方法定义的字符串
-   数据:带有密钥-值格式的付款数据对象

> 通知此方法仅与类型相容:"出道"存款

  

> _**重要**_
> 
> 根据支付 类型字段,数据对象可包括特定字段:

| 付款类型 | 数据 | 数值 | 说明 |
| :-- | :-: | :-: | :-- |
| 临九 | 对象 | txt qr: 字符串, (中文(简体) ),  
图像:字符串 | Pix 付款作为字符串的 qr 代码 .  
包含 qr 代码图像的 Base64 字符串 |

```typescript
// Mandatory object
const ASTROPAY_RESPONSE = {  
    "merchant_deposit_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  		
    "deposit_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
    "status":  "PENDING",  
    "url":  "https://onetouch-sandbox.astropay.com/deposit/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
    "type":  "gateway"
};

// Get the payment data response
AstropaySDK.payment(ASTROPAY_RESPONSE).
    .then(result => {
      //This is the payment data response object
      console.log(result)
    })
```

示例答复:

```typescript
{
  amount: 5,
  currency: "BRL", 
  status: "PENDING",
  payment_type: "PIX",
  data: {
    txt_qr: "examplePixCode"
    image: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAYAAAAY4QDjAAAABmJLR0QA/wD/AP+gvaeTAAADfElEQVRoge2aXW/TQBBFf2BOwAhoh0CaQt0EfQAdAEYAIUARgCFWJED7FhYgFiwKFCAEsEKA"
  }
}
```

_**签名**_

这种方法允许您在您的站点上实现“ Astropay 签名” 按钮 .

在站点上,您想要显示选项设置带有"ap-login" id的元素.

```typescript
//On your site
 <div id="ap-login"></div>

// Mandatory Parameters
client_id: string
redirect_uri: string

// Show the Sign in with AstroPay button
AstropaySDK.signin(client_id, redirect_uri);
```

## 支持的语言

| 语言 | 代码 |
| :-- | :-: |
| 联合国 | 内 |
| 西班牙语Name | 对 |
| 印度尼西亚 | 编号 |
| 日本人 | 对 |
| 한국의 | 小可,别这样 |
| 葡萄牙 | ưμ㼯a |
| ไทย | 编号 |
| 蒂尔克 | 双 |
| 蒂扬·维斯特 | vi. 请检查url=值 (帮助) |
| 簡中 | 日语 |

## 提升

### V4 - 最新数据

SDK的最后一个版本提供了更好的UI控制,事件收听器,新的配置参数和新的产品集成使用.

为了充分了解这个版本,请检查使用部分的文件.

_**中断更改**_

要正确配置自动 SDK 模式关闭和重定向的事件, 请检查关于此文档的新事件收听器部分 .

### 五.3

_**中断更改**_

请注意,对于旧版本 `_external_id` 启动SDK UI是必要的。 现在,该方法接收了由您自己的服务提供的AstroPay init响应的对象.

-   遗产法调用 :

```typescript
const ASTROPAY_EXTERNAL_DEPOSIT_ID =  'External Deposit ID';
AstropaySDK.showDeposit(ASTROPAY_EXTERNAL_DEPOSIT_ID);
```

-   V3 更新方法呼叫 :

```typescript
const ASTROPAY_RESPONSE = {  
    "merchant_deposit_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  		
    "deposit_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
    "status":  "PENDING",  
    "url":  "https://onetouch-sandbox.astropay.com/deposit/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
    "type":  "default"  
};

// Show the DEPOSIT client
AstropaySDK.deposit(ASTROPAY_RESPONSE);
```

### 五. 2级

_**用法实例**_

```typescript
//Your APP ID SDK Credential
const APP_ID = ""; 

const ASTROPAY_CONFIG = {
  environment: "production",
  onDepositStatusChange: (depositResult) => getDepositStatus(depositResult), //Subscribes to every transaction status update.
  onClose: (depositResult) => iframeClosed(depositResult),
};

//Initiates the SDK with the configuration set above
AstropaySDK.init(APP_ID, ASTROPAY_CONFIG); 

//Sets the Deposit External ID generated for the deposit
const ASTROPAY_EXTERNAL_DEPOSIT_ID = "oehpJvCma8jaoaM7qmK3m3MX1LsmUWk8iulDl3Wx"; 

//Here you can do something according to the transaction current status.
const getDepositStatus = (depositResult) => { console.log(depositResult);};

const iframeClosed = (depositResult) => {
  //Here you can also do a action if the user closes the iFrame, also checking the transaction status.
  console.log(
    "action: iFrame was closed",
    "Deposit Status:",
    depositResult
  ); 
};
```

## 支助

我们提供详细文件,说明 [AstroPay OneTouch API 指南](https://developers-wallet.astropay.com/)。请检查它是否有开发者可能需要的更多信息.

如果你需要更多的技术支持,请 [联系支持](https://astropay.com/contact/?lang=en)

## 许可证

版权:"2023 AstroPay". 版权所有.

## 常见问题

### @astropay/astropay-sdk 是什么？

AstroPay 官方客户端,用于方便的前端集成到 One Touch

### 如何安装 @astropay/astropay-sdk？

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

### @astropay/astropay-sdk 支持 TypeScript 吗？

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

### @astropay/astropay-sdk 支持 ESM 还是 CommonJS？

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

### @astropay/astropay-sdk 需要什么版本的 Node\.js？

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

### @astropay/astropay-sdk 可以商用吗？

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

### @astropay/astropay-sdk 的下载量有多少？

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

### @astropay/astropay-sdk 还在维护吗？

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