Skyline Pay SDK

支付中台前端 SDK，封装 PayController 全部接口。通过 CDN 引入即可直接与后端对接。

版本: SkylinePay.VERSION → '1.0.0'

安装

<!-- CDN 引入（推荐） -->
<script src="https://cdn.example.com/skyline-pay-sdk.js"></script>

// ESM
import { SkylinePay } from './skyline-pay-sdk.js';

// CJS
const { SkylinePay } = require('./skyline-pay-sdk');

快速开始

const pay = new SkylinePay({
  baseUrl: '/api',              // 网关地址
  token:   'your-token',        // 登录 Token
  timeout: 15000,               // 请求超时（ms）
  retry:   2,                   // 失败重试次数
  retryDelay: 1000,             // 重试间隔（ms）
  debug:   false,               // 调试模式
  headers: {},                  // 自定义请求头
  onTokenExpired: () => {
    window.location.href = '/login';
  },
});

API 方法一览

| 方法 | 说明 | 参数 | |---|---|---| | payment(params) | 发起充值 | { amount, currency, isClient? } | | reentryPay(orderId) | 重新支付 | 订单ID | | refreshOrder(orderId) | 刷新支付状态 | 订单ID | | getSecurityCode() | 获取安全令牌 | 无 | | getCoins() | 获取可用币种 | 无 | | queryRecords(params?) | 查询充值记录 | { current?, size?, startTime?, endTime?, currencyType?, status? } | | getRecordStatus(orderId) | 查询单条状态 | 订单ID | | pollPaymentStatus(orderId, opts?) | 状态轮询 | { interval?, timeout?, onStatusChange? } |

所有 API 方法的第二个参数均支持 requestOptions：{ timeout?, retry?, retryDelay?, signal? }

使用示例

基本充值流程

// 1. 发起充值
const result = await pay.payment({ amount: 100, currency: 'USDT' });
console.log(result.paymentUrl);   // 支付链接
console.log(result.orderId);      // 订单号

// 2. 轮询等待支付完成
const final = await pay.pollPaymentStatus(result.orderId, {
  interval: 3000,
  onStatusChange: (r) => console.log('状态变化:', r.status),
});

// 3. 查询充值记录
const page = await pay.queryRecords({
  current: 1, size: 10,
  status: 3,  // 只查成功的
});
console.log(page.records);

Token 管理

// 登录后设置 Token
pay.setToken('new-token-value');

// 批量更新配置
pay.setConfig({ timeout: 30000, debug: true });

拦截器

类似 Axios 的拦截器机制，可全局处理请求和响应。

// 请求拦截器 —— 加 loading
const reqId = pay.interceptors.request.use(
  (config) => {
    showLoading();
    return config;           // 必须返回 config
  },
  (error) => Promise.reject(error)
);

// 响应拦截器 —— 关 loading、格式化数据
const resId = pay.interceptors.response.use(
  (data) => {
    hideLoading();
    return data;             // 必须返回 data
  },
  (error) => {
    hideLoading();
    return Promise.reject(error);
  }
);

// 移除拦截器
pay.interceptors.request.eject(reqId);
pay.interceptors.response.eject(resId);

事件系统

// 监听事件
pay.on('paymentSuccess', (result) => {
  console.log('充值成功！', result.orderId);
});

pay.on('paymentFailed', (result) => {
  console.log('充值失败', result);
});

pay.on('tokenExpired', () => {
  // Token 过期，跳转登录
  window.location.href = '/login';
});

pay.on('error', (err) => {
  // 全局错误处理
  console.error('SDK 错误:', err.code, err.message);
});

pay.on('retry', ({ url, remaining }) => {
  console.log(`正在重试 ${url}，剩余 ${remaining} 次`);
});

// 取消监听
pay.off('paymentSuccess');

支持的事件：

| 事件名 | 触发时机 | 回调参数 | |---|---|---| | error | 任何业务/网络错误 | SkylinePayError | | tokenExpired | Token 过期（401/403） | 无 | | retry | 请求重试 | { url, remaining } | | statusChange | 轮询状态变化 | orderId, result | | paymentSuccess | 充值成功（状态=3）| result | | paymentFailed | 充值失败（状态=4）| result | | paymentExpired | 支付超时（状态=5）| result | | pollTimeout | 轮询超时 | orderId |

请求取消

// 方式一：创建取消令牌
const cancel = pay.createCancelToken();
pay.payment({ amount: 100, currency: 'USDT' }, { signal: cancel.signal });
// 需要时取消
cancel.cancel('用户取消了');

// 方式二：取消所有进行中的请求
pay.cancelAll();

自动重试

const pay = new SkylinePay({
  baseUrl: '/api',
  token: 'xxx',
  retry: 3,         // 失败最多重试 3 次
  retryDelay: 2000, // 每次重试间隔 2 秒
});

// 也可以针对单个请求覆盖
await pay.getCoins({ retry: 0 }); // 该请求不重试

调试模式

const pay = new SkylinePay({ baseUrl: '/api', debug: true });
// 控制台输出：
// [SkylinePay] SDK 初始化完成 { baseUrl: '/api', timeout: 15000, retry: 0 }
// [SkylinePay] → POST /api/pay/payment { amount: 100, currency: 'USDT' }
// [SkylinePay] ← POST /api/pay/payment (234ms) { code: 0, data: {...} }

订单状态码

SkylinePay.OrderStatus.WAITING    // 0 - 待付款
SkylinePay.OrderStatus.CONFIRMING // 1 - 区块链确认中
SkylinePay.OrderStatus.CONFIRMED  // 2 - 区块链已确认
SkylinePay.OrderStatus.FINISHED   // 3 - 充值成功
SkylinePay.OrderStatus.FAILED     // 4 - 充值失败
SkylinePay.OrderStatus.EXPIRED    // 5 - 支付超时

错误处理

try {
  await pay.payment({ amount: 100, currency: 'USDT' });
} catch (err) {
  if (err instanceof SkylinePayError) {
    console.log(err.code);    // 32000001（与 ChannelCodeMsg 一致）
    console.log(err.message); // "订单不存在"
    console.log(err.enMsg);   // "Order not found"
  }
}

框架集成示例

Vue 3

// plugins/pay.js
import { SkylinePay } from 'https://cdn.example.com/skyline-pay-sdk.js';

const pay = new SkylinePay({
  baseUrl: import.meta.env.VITE_API_URL,
  debug: import.meta.env.DEV,
  retry: 2,
});

export default {
  install(app) {
    app.config.globalProperties.$pay = pay;
    app.provide('pay', pay);
  },
};

// main.js
import payPlugin from './plugins/pay';
app.use(payPlugin);

// 组件中使用
import { inject } from 'vue';
const pay = inject('pay');
pay.setToken(userStore.token);
const coins = await pay.getCoins();

React

// contexts/PayContext.jsx
import React, { createContext, useContext } from 'react';

const pay = new SkylinePay({
  baseUrl: process.env.REACT_APP_API_URL,
  debug: process.env.NODE_ENV === 'development',
});

const PayContext = createContext(pay);
export const usePay = () => useContext(PayContext);
export const PayProvider = ({ children }) => (
  <PayContext.Provider value={pay}>{children}</PayContext.Provider>
);

// 组件中使用
const pay = usePay();
const coins = await pay.getCoins();

CDN 部署

SDK 设计为单文件无依赖，适合直接部署到 CDN：

skyline-pay-sdk.js      ← 核心 JS（CDN 部署此文件）
skyline-pay-sdk.d.ts    ← TypeScript 类型定义（TS 项目可选引入）

建议通过 URL 版本号管理更新：

<!-- 固定版本 -->
<script src="https://cdn.example.com/[email protected]"></script>

<!-- 始终最新（实时更新） -->
<script src="https://cdn.example.com/skyline-pay-sdk.js"></script>