Useepay SDK 使用说明

简介

这是一个用于对接收银台的SDK，旨在帮助开发者快速集成Useepay的支付功能。

对接流程图

对接支付方式说明

1. googlePay

:::caution[注意]
请确保在localhost或者https环境对接
:::

2. applePay

:::caution[注意]

• 对接applePay需要先申请证书，出现applePay按钮的域名都需要申请证书（无论生产或测试）
• 提供域名后，将useepay提供的证书放置在指定位置并进行验证
• 只能在申请证书的域名下进行调试
  :::

目前支持的支付方式

payMethods = 'googlepay' ｜ 'applepay'

快速开始

1. 首先使用script标签引用Useepay的官方SDK：

     <script src="https://cashier.useepay.com/jssdk3_1/1.0.0/useepay.min.js"></script>
   

2. 通过验证是否成功在window挂载来进行下一步：

     if (window.UseePay) {
    // todo success
     } else {
    // todo fail
     }
   

3. 在进行支付时sdk需要一些必要的支付信息来初始化以及后续的支付：

     UseePay.createPaymentInfo({
    environment: 'TEST', // 非必填，默认'TEST', 可选参数 'PRODUCTION' | 'TEST'
    merchantInfo: {
      merchantName: 'useepay', //非必填 商户名称
      merchantOrigin: 'www.pay.com', //必填 商户网站地址，在UseePay内进件的网站地址
      merchantNo: '500000000007245' // 必填商户号,
    },
    amount: '1234', //必填 订单金额
    currency: 'USD', //必填 货币类型
     })
   

4. 你需要实现该方法来创建支付订单获取AccessToken用于后续的支付，该方法会在点击支付按钮后触发(具体的获取方法请点击跳转至文档)：

     UseePay.getAccessToken = async () => {
    try {
      const params = {}
      const res = await getUseePayAccessToken(params) // 确保你处理好了异步问题，保证res不为undefined
      return res // 将获取的结果完全返回，获取失败可在payError回调中捕获，当然你也可以自行处理
    } catch (error) {
      throw new Error('getAccessToken failed')
    }
     }
   

示例getUseePayAccessToken请求（仅供参考）

  UseePay.getAccessToken = () => {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        resolve({
        resultCode: 'received',
        token: 'mop:mapi:redis:a51acf20-7198-11ef-adce-ec9109cd8df4',
        errorCode: '',
        errorMsg: ''
        })
      }, 500)
    })
  }
  UseePay.getAccessToken = async () => {
    try {
      const params = {};
      const response = await axios.post('/api/getAccessToken', params);
      return response.data;
    } catch (error) {
      throw new Error('getAccessToken failed');
    }
  };

5. 我们提供了全局的支付结果回调方法，你可以通过payMethods设置全局成功和失败回调(可选)：

     // 错误类型 errorType = 'pay_failed' | 'getAccessToken_failed'
     UseePay.paySuccess = (payMethods, result) => {
    console.log(payMethods, result)
     }
     UseePay.payError = (payMethods, errorType, result) => {
    console.log(payMethods, errorType, result)
     }
   

6. 调用该方法并传入支付方式和要渲染的元素ID来创建支付方式：

     // ElementId为支付方式容器的id
     const UseePayInstance = UseePay.createPayMethods(payMethods, ElementId)
   

7. 你可以为支付实例设置独有的成功和失败的回调来处理支付中的问题以及支付结果(可选)：

  UseePayInstance.paySuccess = (result) => {
    console.log(result)
  }
  
  // 错误类型 errorType = 'pay_failed' | 'getAccessToken_failed'
  UseePayInstance.payError = (errorType, result) => {
    console.log(errorType, result)
  }
  
  // PayCancel currently only supports applePay.
  UseePayInstance.payCancel = () => {
    console.log('The payment has been cancelled')
  }

8. 在创建支付方式的时，会有不支持的情况，该方法帮助你处理不支持的情况(可选, 仅支持googlePay、applePay)：

     UseePayInstance.nonSupportCallback = () => {
    console.log('The current payment method is not supported')
     }
   

9. 你的应用场景如果需要修改支付的参数，你可以通过实现该方法来完成（可选）：

:::tip[使用场景]
常用于消费者用积分抵扣或者优惠券扣减订单总额的场景
:::
:::caution[注意]

• 如果你没有修改金额和币种的需求，无需实现该方法
• changeAmountAndCurrency会在点击按钮后获取最新的amount和currency
• changeAmountAndCurrency默认返回{}
• 返回的对象中，amount和currency均为可选的String类型字段
• 如果返回的对象中，没有设置amount和currency，那么将使用createPaymentInfo中的值
• 确保changeAmountAndCurrency返回值的类型是对象
  :::

    const newAmount = '1234'
    UseePay.changeAmountAndCurrency = () => {
   return {
     amount: newAmount ,
     currency: 'USD'
   }
    }
  

  业务结果码（ResultCode）

:::caution[注意]
在处理paySuccess和payError时你需要关注支付的结果，根据ResultCode来进行相应的操作
:::
参考：点击查看文档

Tips: 如果上面的步骤都已完成，那么恭喜你，你已经成功了！

检测支持的payMethods

说明：上面的被动校验方式可能不满足你的需求，因此我们提供了主动校验

:::caution[注意（单独使用无需关注）]
sdk在创建支付方式时内置了检测，因此请确保你在结合使用时能正确处理逻辑，以免产生冲突
:::

1. 综合检测，检测是否支持：

     UseePay.payMethodsCheck.checkAllPaymentSupport().then((support) => {
    // support: { [payMethods]: boolean }
    console.log('Google Pay 支持情况:', support.googlepay);
    console.log('Apple Pay 支持情况:', support.applepay);
     })
     .catch((error) => {
    console.error('检测支付支持情况时出错:', error);
     });
   

2. 单独检测googlePay是否支持：

     UseePay.payMethodsCheck.checkGooglePaySupport().then(isSupport => {
    console.log(isSupport, 'google pay support')
     })
     .catch((error) => {
    console.error('检测支付支持情况时出错:', error);
     });
   

3. 单独检测applePay是否支持：

     UseePay.payMethodsCheck.checkApplePaySupport().then(isSupport => {
    console.log(isSupport, 'apple pay support')
     })
     .catch((error) => {
    console.error('检测支付支持情况时出错:', error);
     });