跳转至

Android接入 - 5.0.x

一. 准备

  • 获取商户应用的签名，并报备给盛付通做后台配置。
    • 方法：同一台手机上，安装商户自己的应用（需经过keystore证书签名），和“盛付通工具.apk”。打开后者，输入applicationId获取到应用签名
  • 获取到盛付通钱包SDK aar包，放入android项目libs文件夹内（拷贝或者覆盖包时,请clean工程和重新build）
  • App的build.gradle 文件内增加SDK引用（钱包SDK、人脸识别SDK），如下
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
        compileSdkVersion 26
        repositories {
            flatDir {
                dirs 'libs'
            }
        }
        //支付SDK
        dependencies {
          // 钱包SDK，具体文件名请以实际为准
          implementation(name: 'SDPWallet_product_5.0.12_release_202110201456', ext: 'aar')
          // 若钱包SDK ≥ 5.0.12，则需包含“人脸识别SDK”
          implementation(name: 'faceid_lib-release', ext: 'aar')


          // 其它系统引用
          implementation 'com.squareup.okhttp3:okhttp:3.12.5'
          implementation 'com.squareup.okhttp3:logging-interceptor:3.12.5'
          implementation 'com.google.code.gson:gson:2.8.6'
          implementation 'com.jakewharton:disklrucache:2.0.2'
          implementation 'com.android.support:support-v4:26.1.0'
          implementation 'com.android.support:appcompat-v7:26.1.0'
          implementation 'com.android.support:recyclerview-v7:26.1.0'
          // for AndroidX 项目
          // implementation "androidx.room:room-runtime:2.1.0-alpha07"
          // annotationProcessor "androidx.room:room-compiler:2.1.0-alpha07"
        }

二. 快速集成

钱包SDK开放的对外功能接口，统一集中在 SPWalletApi.java 类文件里。主要功能描述如下：

1. 初始化

1
2
3
4
public static void initWallet(
      @NonNull Context context,
      @NonNull SPBaseWalletParam param,
      @Nullable SPIAppAuthCallback appAuthCallback)
注意，使用钱包功能之前，需要提前初始化SDK！其中，初始化的两个参数说明如下：

  • 参数一：SPWalletParamCloud，包含基本的属性值（“掌门集团”内部的App接入时，该参数稍有不同，详情请联系钱包团队）
字段名 变量 必填 类型 示例值 描述
appId 盛付通分配的钱包Id 是 String 349566231193 由盛付通分配
environment 接入的环境 是 int 0 "生产环境"为0，"测试环境"为1
theme 皮肤主题 否 String SPBaseWalletParam.THEME_BLUE 内置三种主题色(定义在SPBaseWalletParam内): THEME_BLUE, THEME_GRAY, THEME_RED； 默认为SPBaseWalletParam.THEME_BLUE。若这三种无法满足需求，则可通过customThemeJson字段定制主题
customThemeJson 自定义主题色 否 String 参见下方的“自定义主题”json结构 若设置有值，则优先使用该字段，而忽略theme字段
loadingText loading框上的文案 否 String 请稍等 若不设置，则默认显示"请稍等"

自定义主题示例（通过customThemeJson属性设置）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "themeColor": "#FF6F61",    // 整体主题色
    "textColor": "#FF6F61", // 支付成功界面icon下面的字体颜色
    "iconColor": "#FF6F61", // 支付成功界面icon图标的颜色
    "button_cantClick": "#FFD3CF",  // 按钮不能点击时的“背景颜色”
    "buttonText_cantClick": "#FFFFFF",  // 按钮不能点击时的“字体颜色”
    "buttonStroke_cantClick": "#FFD3CF",    // 按钮不能点击时的“边框颜色”
    "button_clickable": "#FF6F61",  // 按钮可用时的“背景颜色”
    "buttonText_clickable": "#ffffff",  // 按钮可用时的“字体颜色”
    "buttonStroke_clickable": "#FF6F61",    // 按钮可用时的“边框颜色”
    "button_clickDown": "#FF6F61",  // 按钮按下时的“背景颜色”
    "buttonText_clickDown": "#FFFFFF",  // 按钮按下时的“字体颜色”
    "buttonStroke_clickDown": "#FF6F61" // 按钮按下时的“边框颜色”
  }

  • 参数二：SPIAppLoginCallback 实例

如果App支持用户未登录时进入钱包首页，则需要传入该参数。在钱包首页，当用户使用那些需登录后才能查看的功能时，SDK会通过该对象实例回调App，从而触发App登录
初始化代码示例： 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    SPWalletParamCloud param = new SPWalletParamCloud();
    param.appId = "349566231193"; // 必填，盛付通分配的钱包Id
    param.environment = 0; // 必填，服务器环境,0生产环境 1测试环境
    param.theme = SPBaseWalletParam.THEME_BLUE; // 选填，默认为 THEME_BLUE

    SPIAppAuthCallback mAppAuthCallback =
          new SPWalletInterface.SPIAppAuthCallback() {
            @Override
            public boolean doAppLogin(@NonNull Activity activityContext,
                SPWalletInterface.SPIAppLoginResultNotify loginResultNotify) {
              // ......其它代码，如保存loginResultNotify对象。登录成功后，需要通过这里的"loginResultNotify"参数，将app登录结果(成功/失败)通知到钱包sdk
              Intent intent = new Intent(MainActivity.this, CloudLoginActivity.class);
              startActivity(intent);
              return true;
            }
          };

    SPWalletApi.initWallet(this, param, mAppAuthCallback);

其中，参数类型SPIAppAuthCallback定义如下： 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
  public interface SPIAppAuthCallback {
    /**
     * 必须实现!!!
     * 获取App登录用户的userId
     * @return App用户userId，为空或null表示未登录
     */
    String getAppUserId();

    /**
     * 必须实现!!!
     * 获取App登录用户的登录态token
     * @return App用户登录态token，为空或null表示未登录
     */
    String getAppUserToken();

    /**
     * 获取App其它的信息
     * @param key 相关信息对应的key值，定义在 {@link SPWalletConstant} 里。如做实名校验的 SPWalletConstant.EXTRA_REAL_NAME_INFO
     * @return key 对应的value值
     */
    Object getAppExtraProperty(@NonNull String key);

    /**
     * 钱包sdk首页需要用户登录app时，回调该方法。app应实现该方法，唤起登录界面。登录成功(或取消、失败)后，再通过 loginResultNotify 参数通知sdk
     * 注：如果进入钱包sdk时，app能保证已登录，则该方法也可以不实现
     *
     * @param activityContext 触发该功能的sdk内部activity实例
     * @param loginResultNotify 登录成功(或失败)后，通过该参数通知sdk登录结果 {@link SPIAppLoginResultNotify}
     * @return 是否成功唤起登录功能。为true表示成功处理(如正常唤起登录界面)，否则为false
     */
    boolean doAppLogin(
        @NonNull Activity activityContext, SPIAppLoginResultNotify loginResultNotify);
  }

2. 进入钱包首页

当前，SDK能够支持App已登录或未登录两种情况下打开钱包首页(钱包将通过前述的、初始化时的 SPIAppLoginCallback 对象获取App登录信息，或驱动App唤起登录流程)。接口定义如下： 

1
2
3
4
5
6
7
  /**
   * 打开钱包首页
   *
   * @param activityContext 启动该功能的源activity实例
   * @param requestCode 通过 startActivityForResult 打开钱包首页时传入的requestCode， 如不使用可以传0
   */
  public static void startWalletHomeForResult(@NonNull Activity activityContext, int requestCode)

3. 发起支付

支付之前，钱包SDK将通过前述相关接口保证用户已登录。支付接口定义如下： 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
  /**
   * 唤起支付功能
   *
   * @param activityContext 启动该功能的源activity实例
   * @param orderInfo 订单相关信息(json串)
   * @param showPayResultPage 支付完成后，是否展示钱包预置结果页
   * @param payCallback {@link SPIGenericResultCallback} 支付结果的回调
   * @return 是否成功唤起支付页面
   */
  public static boolean startPay(
      @NonNull Activity activityContext,
      @NonNull String orderInfo,
      boolean showPayResultPage,
      SPIGenericResultCallback payCallback)

其中参数orderInfo的结构(json字符串)如下（属性字段的含义也可参考服务端相关文档）： 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    {
        "appId":"349566231193",//应用Id,由盛付通分配 必填
        "mchId":"93756275",//商户在盛付通申请的商户号 必填
        "prepayId":"e62ef3f574b247ae9947418db51c0462",//预支付Id 必填
        "nonceStr":"pWUVWVYWNQhnTXpQzhIzMGCwqBkZclzg",//随机字符串 必填
        "timestamp":"1603941829",//时间戳 必填
        "signType":"RSA",//暂时固定为RSA,不可变更 必填
        "sign":"iaKliK7BOQoBJKxfSj+91toRp4L9CjFDpovU7376WBeXYg98b9v2jdQ58SsdVtsa9pbZ91bEXyx1
    RAJ+md90PzUsLItTYnUfOECSx/uesvghxEDQpj3t6FLO3Jr7LHWSaf07tLbzkKpbk9lwXEXIjWg4
    bgniCkWSJIvXYPCcNsIrzHY5itictO94attPD08dezhuY+Pv6MC7AmXGmfmogYfwn+PQtAy8qRHI
    B8YeW3XdtcTjNLGg6SfGhvNaG0gYffyFJOm7vFVd4smVKihnkxa8OIN4JXfOEwrJXhZfeomQijGY
    oppPa+Ixf605YYuOrkMdrVL9u3K+DJvBaU9o9g=="//请求加签,请参考服务端加签文档 必填
    }
支付完成后，通过参数payCallback通知调用方支付结果。其中，支付的返回码code的含义如下：

返回码 返回信息 备注
0 支付成功 建议不要作为支付的最终状态，需商户主动查询服务端的支付结果
-1 支付中 需商户主动查询最终的支付结果
-2 支付失败 可能原因:sign签名错误,userId不匹配,连尚校验失败,其他错误等
-3 支付取消 用户主动取消

4. 连尚钱包签约(自动续费)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  /**
   * 唤起连尚钱包签约(自动续费)功能
   *
   * @param activityContext 启动该功能的源activity实例
   * @param url 预签约地址(由服务端生成)
   * @param signCallback 签约结果回调
   */
  public static void walletSign(
      @NonNull Activity activityContext,
      @NonNull String url,
      SPWalletInterface.SPIWalletSignCallback signCallback)

5. 其它功能接口

  • 退出钱包所有页面 
1
public static void finishAllWalletPages();
  • 清除钱包的登录态 
1
public static void logoutWallet();
  • 设置控制台log开关 
1
public static void setLogcat(boolean enable); // 默认值为： 测试环境打开，生产环境关闭

三. 常见问题列表

  1. 问：测试环境，为什么绑卡会失败？
    答：在测试环境，绑卡只模拟支持了民生银行卡，格式为:622622+10位。

  2. 问：测试环境，为什么无法收到验证码？
    答：测试环境绑卡不发送短信验证码,请输入任意6位数字。

  3. 问：为什么设置支付密码失败？
    答：目前不支持弱支付密码，如123456等。请检查并重新输入。

  4. 问：钱包SDK是否有日志log输出？如何查看？
    答：SDK默认只在测试环境时输出日志，生产环境下默认关闭。在Android Studio中以“SP_NET”为tag名称，可以过滤SDK内的http网络请求相关日志(另，以“SP_”为tag可以查看更多输出日志)。

  5. 问：测试环境接入通过后，为什么切换到生产环境会报错？
    答：在生产环境上，每个商户在盛付通都对应独有的配置信息。上线前，请向盛付通邮件申请开通生产配置，同时盛付通将提供商户独有的、生产环境的钱包SDK。

Back to top