Documentation Index
Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt
Use this file to discover all available pages before exploring further.
UQPAY Node.js SDK 以带类型的方式访问 UQPAY API，内置自动鉴权、分页、重试与 webhook 校验。
快速上手
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'
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'
})
clientId 和 apiKey 换取 token，缓存并在过期前自动刷新，你无需手动管理 token。
代子账户调用
代 Connected 子账户调用 API 时，传入 x-on-behalf-of 头：
await client.account.accounts.retrieve('acc-123', {
headers: { 'x-on-behalf-of': 'sub-account-id' },
})
幂等性
每次请求会自动生成一个 UUID 幂等键。如果要自定义：
await client.account.subAccounts.create(params, {
headers: { 'x-idempotency-key': 'your-uuid-v4' },
})
PaginatedResponse<T>，包含 data、total_pages 与 total_items：
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 日志可以看到所有请求和响应：
const client = new UQPayClient({
// ...
logLevel: 'debug',
})
apiKey、card_number、cvc、iban 等）会自动脱敏。也可以自行追加需脱敏的字段：
const client = new UQPayClient({
// ...
logLevel: 'debug',
redactFields: ['my_secret_field'],
})
通用逃生出口
对于 SDK 暂未覆盖的接口，使用通用的 request 方法：
const result = await client.request('POST', '/v1/some/endpoint', {
body: { key: 'value' },
})
平台信息
如果你在 UQPAY 之上构建平台，把应用信息附加到 User-Agent 头：
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)
