校园码解码集成

1、联调环境说明

生产调试环境

正常调用alipay.trade.pay

2、校园码格式

数据类型定义

Byte: 对应1byte 8 bit

Vars: 变长度数据单元.第一字节表示后面数据段的长度,为无符号格式.表达范围是0~255.

读取流程：

a: 读第一字节的内容,获得一个长度

b: 读第一个字节指定的长度的字节内容,为数据段

3、码数据协议

调用机具内置的支付宝解码SDK,解码成功后,会返回userdata数据. userData数据格式如下

 当数据模版ID = 4 (请将4字节转化成int)的时候,Vas内的数据格式如下:

当数据模版ID = 5 (请将4字节转化成int)的时候,Vas内的数据格式如下:

字段解释如下:

school_no:     是国标,10位数字. 编码成long型处理

identify_id:    在校园电子卡场景里,放的是电子学生证ID.

card_type:     00,01 ..... 15 ,表示卡的类型

card_status:    保留字段,无含义.请忽略该字段的值

student_no:    指学生在学校里的学号

student_name:  学生姓名. 使用码头中指定的编码方式编码成byte流.一般是GB2312

extinfos:       保留字段,目前是空

4、校园码支付必读

• 设备需要保存2分钟内的解码记录. 防止单台设备重复受理同一张码.
• 有条件的设备,尽量保证多台设备不重复受理同一张码.
• 为了保证支付体验
• 设备受理码之后,尽快发送至支付宝服务端进行支付处理.一般建议24小时内送达支付宝服务端.最长不超过10天[该时间会根据实际情况调整,调整后会另行通知].超出时间后,支付宝端支付将会失败.

5、校园码支付流程

a:学生展示码

b:学生通过机具扫码

c:机具解码通过后,提示支付成功

d:机具异步发送数据到服务端

e:服务端向支付宝发起支付请求

6、请求代码示例：

机具调用支付宝解码SDK接口定义

/**
 * @oaram [in] code 码值
 * @param [in] len_code 码值长度
 * @param [in] priority 业务权限 取值范围0-1，分别代表门禁业务（不校验权限），支付代扣业务
 * @param [in] pid 受理业务id, 8bytes，选择门禁业务时，可填空
 * @param [in/out] result 作为入参要求不为空，作为出参表示校验结果码，参照前文注释
 * @param [in/out] len_result 作为入参要求输入result内存空间大小（不小于32），作为出参时表示result赋值后实际长度
 * @param [out] data_encode_type 用户数据编码格式
 * @param [in/out] user_data 入参要求不为空，出参表示用户数据
 * @param [in/out] len_data 入参要求输入user_data内存空间大小（不小于255），出参表示实际用户数据长度
 * @param [in/out] data_formwork_id 入参要求不为空，出参表示用户数据模版码值 4bytes
 * @param [in/out] in_use_time 入参要求不为空，出参表示码生成时间，按照大端字节序，8bytes的字节流
 * @param [in/out] version 离线码的版本号
 * @param [in/out] final_data 入参要求不为空，出参表示处理之后的码值
 * @param [in/out] len_data 入参要求输入final_data内存空间大小（不小于原始码值的长度），出参表示实际用户数据长度
 * 注意：所有参数的内存均为接口调用方申请，接口内部不申请相关内存
 * 
 * @return  ALIPAY_CODEVERIFY_FAILED_ILLEGAL_CODE：输入的码不合法
 *          ALIPAY_CODEVERIFY_FAILED_WRONG_RESULT_PARAMS：输入的参数result或者len_result不合法
 *          ALIPAY_CODEVERIFY_FAILED_WRONG_PARAMS：输入的其他参数不合法
 *          ALIPAY_CODEVERIFY_FAILED_NORMAL：码解析校验失败
 *          ALIPAY_CODEVERIFY_OK：验码成功
 */

注意：

priority：0表示门禁业务不校验权限，1表示代扣业务，参照枚举：

typedef enum
{
    ALIPAY_USER_PRORITY_IGNORE = 0,
    ALIPAY_USER_PRORITY_AGENT = 1,
    ALIPAY_USER_PRORITY_MAX,
}alipay_user_prority_e;

所有参数的内存均为接口调用方申请，接口内部不申请相关内存

返回值说明

* @return  ALIPAY_CODEVERIFY_FAILED_UNREGISTERED：接口未注册
 *          ALIPAY_CODEVERIFY_FAILED_ILLEGAL_CODE：输入的码不合法
 *          ALIPAY_CODEVERIFY_FAILED_WRONG_RESULT_PARAMS：输入的参数result或者len_result不合法
 *          ALIPAY_CODEVERIFY_FAILED_WRONG_PARAMS：输入的其他参数不合法
 *          ALIPAY_CODEVERIFY_FAILED_NORMAL：码解析校验失败
 *          ALIPAY_CODEVERIFY_OK：验码成功

校验结果码说明（result）

校验结果码（uint8_t型字符串）
----------------------------------------
结果                解释
----------------------------------------
DES_ERROR           码解密失败
INST_SIGN_FAILED    机构信息签名验证失败
USER_SIGN_FAILED    用户授权信息签名验证失败
USER_AUTH_FAILED    该场景用户未开通
RUN_EXCEPTION       运行中程序遇到异常
USER_AUTH_TIMEOUT   授权证书过期
CODE_TIMROUT        二维码过期
SUCCESS             成功
----------------------------------------

----------------------------------------

接口注册

/*
 * 注册适配层接口
 */
void alipay_adapter_register(os_adapter_layer_handler *handler);

在调用验码接口时需要完成SDK系统接口的注册，数据结构如下：

typedef struct _os_adapter_layer_handler
{
    void (*alipay_get_sys_time)(uint64_t *time_now);//获取系统时间
} os_adapter_layer_handler;

目前只需要注册系统时间的接口，单位ms

e.g.
linux系统为例：

void alipay_get_sys_time(uint64_t *time_now)
{
    struct timeval tv_time_now;

    gettimeofday(&tv_time_now, NULL);
    *time_now = (uint64_t)tv_time_now.tv_sec * 1000 + tv_time_now.tv_usec / 1000;
}

 os_adapter_layer_handler handler;
    handler.alipay_get_sys_time = &alipay_get_sys_time;
    alipay_adapter_register(&handler);

注意：此接口注册只需要进程创建时调用一次即可，不需要重复调用

7、联调中常见问题说明

机具扫码识别速度慢

主要是机具扫码识别模块问题. 双离线码有如下2个特点

a:码值是byte数组,不是string. 因此对于扫码模块,不能直接将从码图中读取的字节流变成string传递给解码SDK

b:双离线码的码值较长,280字节左右. 因此对于扫码模块有要求. 需要有主流的识别算法.

机具调用解码SDK失败

失败主要有如下原因

a.码值传入不对. 比如希望传入的是byte数组,结果传入了string.

b.SDK环境和码的环境不一致. 比如集成的SDK是daily环境的,但是码是生产环境的,反之亦然.

c.码过期了(双离线码2分钟后过期,再送给SDK解码失败)

d.传入接口的pid和用户开通码的时候签约的pid不一致

解析码中的用户数据遇到异常

a.参考上文中的userData数据格式. 按照这个数据格式解析出各个字段.

调用支付链路失败

a.未将调用SDK后的fianl_data传递给服务端,而是将code传递给后续的链路.

b.用户本身账户问题

FAQ