更新记录

1.0.0（2025-04-07） 下载此版本

多支付渠道统一接口：支持微信支付、支付宝、银联

平台兼容性

XL-Payment 多端支付聚合SDK

在线演示地址：在线demo

功能特点

• 多支付渠道统一接口：支持微信支付、支付宝、银联和国际信用卡
• 多端平台适配：H5、App、小程序全平台支持
• 混合支付能力：支持虚拟货币（积分、代金券）与实际支付混合使用
• 防重复支付：内置防重复支付机制，避免支付异常
• 订单状态自动同步：自动同步未完成订单状态，保障订单数据一致性
• 跨境支付支持：解决跨境支付场景的复杂适配问题

安装

将组件文件夹复制到你的项目中

快速开始

基础配置

import xlPayment from '@/components/xl-payment';

// 初始化配置
xlPayment.initialize({
  config: {
    // 微信支付配置
    wechat: {
      appId: 'wx123456789',
      mchId: '123456789',
      apiKey: 'your_api_key',
      notify_url: 'https://your-domain.com/pay/notify/wechat'
    },
    // 支付宝配置
    alipay: {
      appId: '2021000000000000',
      privateKey: 'your_private_key',
      publicKey: 'alipay_public_key',
      notify_url: 'https://your-domain.com/pay/notify/alipay'
    },
    // 虚拟货币配置
    virtual: {
      enabled: true,
      name: '积分',
      rate: 100, // 100积分=1元
      checkBalance: async () => {
        // 实际项目中应从服务端获取用户积分余额
        return { success: true, balance: 1000 };
      }
    }
  }
});

创建订单

// 创建支付订单
const createOrderResult = await xlPayment.createOrder({
  title: 'iPhone 14 Pro',
  amount: 6999,
  currency: 'CNY',
  paymentType: 'wechat', // 支付方式：wechat, alipay, unionpay, international
  virtualAmount: 500, // 使用500积分抵扣
  items: [
    { id: 'iphone14pro', name: 'iPhone 14 Pro', price: 6999, quantity: 1 }
  ],
  metadata: { 
    userId: '12345',
    source: 'app'
  }
});

if (createOrderResult.success) {
  console.log('订单创建成功:', createOrderResult.order);
} else {
  console.error('订单创建失败:', createOrderResult.message);
}

发起支付

// 发起支付
const payResult = await xlPayment.pay({
  orderId: createOrderResult.order.id
});

if (payResult.success) {
  console.log('支付成功或进行中:', payResult);

  if (payResult.pending) {
    // H5跳转支付等异步场景，需要等待用户完成支付
    console.log('已跳转到支付页面，等待用户完成支付');
  } else {
    // 支付已完成
    console.log('支付已完成:', payResult.order);
  }
} else {
  if (payResult.canceled) {
    console.log('用户取消支付');
  } else {
    console.error('支付失败:', payResult.message);
  }
}

查询订单

// 查询订单状态
const queryResult = await xlPayment.queryOrder(orderId);

if (queryResult.success) {
  console.log('订单状态:', queryResult.order.status);

  // 处理不同订单状态
  switch (queryResult.order.status) {
    case 'PAID':
    case 'SUCCESS':
      console.log('支付成功，订单完成');
      break;
    case 'CLOSED':
    case 'FAILED':
      console.log('订单已关闭或支付失败');
      break;
    case 'REFUNDED':
      console.log('订单已退款');
      break;
    default:
      console.log('订单处理中');
  }
} else {
  console.error('查询订单失败:', queryResult.message);
}

关闭订单

// 关闭未支付订单
const closeResult = await xlPayment.closeOrder(orderId);

if (closeResult.success) {
  console.log('订单已关闭:', closeResult.order);
} else {
  console.error('关闭订单失败:', closeResult.message);
}

申请退款

// 申请退款
const refundResult = await xlPayment.refund({
  orderId: orderId,
  amount: 100, // 退款金额，不传默认全额退款
  reason: '商品缺货'
});

if (refundResult.success) {
  console.log('退款申请成功:', refundResult);
} else {
  console.error('退款申请失败:', refundResult.message);
}

混合支付

支持虚拟货币（如积分）与实际支付混合使用：

// 创建混合支付订单
const createMixedOrderResult = await xlPayment.createOrder({
  title: '商品购买',
  amount: 100, // 总金额100元
  virtualAmount: 50, // 使用虚拟货币抵扣50元
  paymentType: 'wechat' // 剩余50元使用微信支付
});

// 发起支付，会先使用虚拟货币支付，再使用微信支付剩余部分
const payMixedResult = await xlPayment.pay({
  orderId: createMixedOrderResult.order.id
});

状态监听

监听支付状态变化：

import { useRequestStore } from '@/components/xl-payment/store';

export default {
  setup() {
    const store = xlPayment.getState();

    // 监听订单状态变化
    xlPayment.store.addEventListener('orderStatusChange', (order) => {
      console.log('订单状态变化:', order);
      if (order.status === 'PAID') {
        console.log('订单支付成功');
      }
    });

    // 监听支付成功事件
    xlPayment.store.addEventListener('paymentSuccess', (result) => {
      console.log('支付成功:', result);
    });

    // 监听支付失败事件
    xlPayment.store.addEventListener('paymentFailed', (error) => {
      console.log('支付失败:', error);
    });
  }
}

API 参考

xlPayment.initialize(options)

初始化支付SDK，设置全局配置。

xlPayment.createOrder(orderInfo)

创建支付订单。

xlPayment.pay(options)

发起支付。

xlPayment.queryOrder(orderId)

查询订单状态。

xlPayment.closeOrder(orderId)

关闭未支付订单。

xlPayment.refund(options)

申请退款。

xlPayment.setConfig(config)

更新配置。

xlPayment.getState()

获取当前状态。

xlPayment.clearError()

清除错误。

支持的支付方式

• 微信支付：小程序支付、H5支付、APP支付
• 支付宝：手机网站支付、APP支付、小程序支付
• 银联支付：银联在线支付
• 国际信用卡：Visa、MasterCard、JCB等
• 虚拟货币：平台积分、代金券等

注意事项

1. 正式环境需要配置正确的商户信息和密钥
2. H5环境下微信支付需在微信浏览器内使用
3. 异步通知地址(notify_url)必须可以被外网访问
4. 建议在正式环境启用日志功能，方便排查问题