> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> 安装并配置 UQPAY 官方 Node.js SDK，集成支付、账户与发卡 API。

UQPAY Node.js SDK 以带类型的方式访问 UQPAY API，内置自动鉴权、分页、重试与 webhook 校验。

<Card title="npm" icon="npm" href="https://www.npmjs.com/package/@uqpay/sdk">
  @uqpay/sdk
</Card>

<Info>
  SDK 需要 **Node.js 20** 或更高版本。
</Info>

## 安装

```bash theme={null}
npm install @uqpay/sdk
```

## 快速上手

```ts theme={null}
import { UQPayClient } from '@uqpay/sdk'

const client = new UQPayClient({
  clientId: 'your-client-id',
  apiKey: 'your-api-key',
  environment: 'sandbox',
})

const account = await client.account.accounts.retrieve('acc-123')
console.log(account.status) // 'ACTIVE'
```

## 配置

创建 client 时传入配置项：

```ts theme={null}
const client = new UQPayClient({
  clientId: 'your-client-id',       // 必填
  apiKey: 'your-api-key',           // 必填
  environment: 'sandbox',           // 'sandbox' | 'production'——默认 'sandbox'
  webhookSecret: 'whsec_...',       // 校验 webhook 时必填
  timeout: 30_000,                  // 请求超时（毫秒）——默认 30000
  maxRetries: 2,                    // 自动重试次数——默认 2
  logLevel: 'info',                 // 'none' | 'info' | 'debug'——默认 'none'
})
```

## 鉴权

SDK 自动处理鉴权。它会用 `clientId` 和 `apiKey` 换取 token，缓存并在过期前自动刷新，你无需手动管理 token。

## 代子账户调用

代 Connected 子账户调用 API 时，传入 `x-on-behalf-of` 头：

```ts theme={null}
await client.account.accounts.retrieve('acc-123', {
  headers: { 'x-on-behalf-of': 'sub-account-id' },
})
```

## 幂等性

每次请求会自动生成一个 UUID 幂等键。如果要自定义：

```ts theme={null}
await client.account.subAccounts.create(params, {
  headers: { 'x-idempotency-key': 'your-uuid-v4' },
})
```

## 分页

所有 list 方法返回 `PaginatedResponse<T>`，包含 `data`、`total_pages` 与 `total_items`：

```ts theme={null}
const page = await client.issuing.cards.list({ page_number: 1, page_size: 50 })

console.log(page.data)        // Card[]
console.log(page.total_pages) // 总页数
console.log(page.total_items) // 总条数
```

递增 `page_number` 直到 `total_pages`，即可遍历全部结果。

## 日志

开启 debug 日志可以看到所有请求和响应：

```ts theme={null}
const client = new UQPayClient({
  // ...
  logLevel: 'debug',
})
```

敏感字段（`apiKey`、`card_number`、`cvc`、`iban` 等）会自动脱敏。也可以自行追加需脱敏的字段：

```ts theme={null}
const client = new UQPayClient({
  // ...
  logLevel: 'debug',
  redactFields: ['my_secret_field'],
})
```

## 通用逃生出口

对于 SDK 暂未覆盖的接口，使用通用的 `request` 方法：

```ts theme={null}
const result = await client.request('POST', '/v1/some/endpoint', {
  body: { key: 'value' },
})
```

## 平台信息

如果你在 UQPAY 之上构建平台，把应用信息附加到 User-Agent 头：

```ts theme={null}
client.setAppInfo('MyPlatform', '2.0.0', 'https://myplatform.com')
// User-Agent: uqpay-node/0.2.0 node/20.0.0 MyPlatform/2.0.0 (https://myplatform.com)
```