卡咪在线API接口文档
1.1接口说明
1.客户编号由卡咪在线提供，注册后会获得唯一用户ID；
2.接口安全机制采用MD5签名防止信息篡改与3DES加密卡信息方式防止卡信息泄露；
3.接口提交与回调均采用http 协议,异步返回支付结果
2.1接口地址
接口地址：https://www.kamicc.com/api/api/submit-card
提交方式：POST
2.2接口参数
顺序 | 参数名称 | 参数描述 | 可否为空 | 备注信息 |
1 | customerId | 商户编号 | N | 商户编号，由卡咪在线提供 |
2 | orderId | 订单号 | N | 商户订单号，保证唯一性，长度最多32位 |
3 | productCode | 产品编码 | N | 编码列表见商户后台产品编码 |
4 | amount | 卡面额 | N | 单位为元,整数 |
5 | cardNumber | 卡号（加密） | N | 使用客户后台设置的加密密钥进行3DES加密 |
6 | cardPassword | 卡密（加密） | N | 使用客户后台设置的加密密钥进行3DES加密 |
7 | callbackURL | 回调地址 | N | 接口将通过此地址进行订单结果通知（暂不支持带端口的IP地址，请使用80端口的IP或域名地址） |
8 | sign | 签名 | N | 使用MD5算法生成的加密验证字符串 |
9 | extendParams | 扩展信息 | Y | 商户扩展信息，返回时原样返回（长度小于50位，可为空） |
10 | discount | 折扣值 | Y | 折扣产品才需要传（示例值：98.00） |
2.3接口说明
2.3.1 cardNumber（卡号）、cardPassword（卡密）加密说明：
（1）进行3DES加密(ECB模式)。注：加密密钥不足24位长度时后面补0，超过24位长度时需截取前24位字符。
（2）将加密后的密文进行hex转换。
2.3.2 sign生成说明：
（1）接口采用md5算法对请求数据验证，验证失败将不予处理，MD5组合源串如下：
customerId&orderId&productCode&amount&cardNumber&cardPassword&callbackURL&signkey
其中signkey为卡咪在线商户后台设置的签名密钥。MD5生成的加密串统一转换为小写。
2.3.3 3DES及MD5测试结果比对：
（1）MD5测试结果比对：
中文测试数据：这是中文测试
加密结果：5fcafaaeda6ae109ff3811f6ffb74c65
不带中文测试数据：test
加密结果：098f6bcd4621d373cade4e832627b4f6
（2）3DES测试结果比对：
密钥：test0123456789
测试数据：0123456789
加密结果：034dcda761d12373f82b025355c6870d(密钥未补全24位)
加密结果：027c4ed35551c6ca264ba9d2283b16fe(密钥补全24位)
新增加解密在线测试：
加密测试：https://www.kamicc.com/api/api/check-encrypt
解密测试：https://www.kamicc.com/api/api/check-decrypt
参数为cardNumber和encryptionKey
2.4接口返回码
同步结果的返回码，最终的销卡结果以异步通知的为准。如果在同步提交的时候就报错，提交不成功则没有异步通知。如果提交成功，则等待通道处理及异步通知，成功提交并不代表最终被成功销卡，不能使用同步提交的结果码来进行判断是否被成功销卡，否则可能造成损失！
请参考 3.1提交充值卡返回码列表
2.5接口回调通知
2.5.1回调通知说明
卡咪在线会在订单处理完毕后将处理结果以Http POST方式发送到商户提交的callbackURL参数的地址中，客户在接收到支付结果后向页面写入“Y”（无需添加其它任何标签或字符），回调通知信息目前只发送一次，如果有需要可以在用户中心订单页面进行补发通知。
2.5.2回调参数说明
顺序 | 参数名称 | 可否为空 | 参数描述 |
1 | customerId | N | 商户编号 |
2 | orderId | N | 商户订单号 |
3 | systemOrderId | N | 系统流水号 |
4 | productCode | N | 产品编码 |
5 | status | N | 状态（1：处理中、2：成功、3：失败4：手动处理）判断订单的状态请使用这个字段！ |
6 | cardNumber | N | 卡号（加密）（使用客户后台设置的加密密钥进行3DES加密） |
7 | cardPassword | N | 卡密（加密）（使用客户后台设置的加密密钥进行3DES加密） |
8 | amount | N | 商户提交的面值 |
9 | successAmount | N | 结算面值(正常情况下，这个结算面值和下面的真实面值是一致的，但是如果出现卡损的情况下，这个结果可能和真实面值不一致，请根据你的业务选择给用户结算的时候使用的是结算面值还是真实面值，一般情况下如果出现卡损是用户承担的那么就使用这个结算面值进行计算，如有疑问请先联系商务咨询，如因商户对接问题出现资损，由商户承担) |
10 | actualAmount | N | 结算金额 |
11 | successTime | N | 成功日期,格式为：yyyy-MM-dd HH:mm:ss |
12 | code | N | 状态码（参考4.2回调通知返回码列表） |
13 | callbackURL | N | 回调地址（原样返回） |
14 | sign | N | 签名（具体实现请看下面的说明） |
15 | extendParams | Y | 扩展信息（原样返回商户的扩展信息） |
16 | memo | Y | 备注说明（比如具体的失败信息。极少数的状态码可能出现同一个状态码返回不同的错误信息，这是由于销卡通道那边也有这种情况，同一个状态码可能返回不同的信息，为了方便兼容，接口这边也直接返回。因此如果订单失败需要使用失败信息的可以直接参考该备注字段的信息。） |
17 | realPrice | Y | 真实面值（销卡成功才有返回，真实面值是不变的，哪怕是出现卡损的情况下返回的也是这张卡本来的卡面面值，请根据自己的业务选择是使用结算面值还是真实面值给用户进行结算，如有疑问请先联系商务咨询，如因商户对接问题出现资损，由商户承担） |
2.5.3回调sign签名说明
采用md5算法对数据进行数字签名，MD5组合源串如下：
customerId&orderId&systemOrderId&productCode&status&amount&cardNumber&cardPassword&successAmount&actualAmount&code&signKey
备注：cardNumber和cardPassword为解密后的明文卡号和卡密数据，signKey为在卡咪在线商户后台设置的签名密钥，MD5生成的加密串请转换为小写。
2.5.4注意事项
1. 商户在获得通知结果的时候，请首先根据sign验证各个参数的合法性；
2. 如果订单状态是正在处理中或者失败，则真实面值和结算金额为0，可能带有小数位，如0.0，成功日期为空字符串；
3. 商户在接收到返回信息后，请回写“Y”字符给卡咪在线。
4. 如果是失败状态的订单，也麻烦在收到回调后如正常处理完也返回“Y”，处理完成状态码，方便同步更新两边订单的回调状态
三、返回码列表
3.1提交充值卡返回码列表
返回码 | 返回码描述信息 |
000000 | 提交成功（注：表示充值卡只是成功提交到通道中处理，不代表已被成功销卡，最终是否成功销卡要以异步通知中的status参数结果为准！） |
100001 | 系统维护 |
100002 | 必要参数为空 |
100003 | 卡号、卡密超过失败次数限制 |
100004 | 商户不存在 |
100005 | 商户被关闭 |
100055 | 时间戳不合法（要10分钟之内） |
100006 | 未设置密钥 |
100007 | 产品不存在 |
100008 | 产品暂停销售 |
100009 | 商户没有开通该产品 |
100010 | 不支持的面值 |
100011 | 签名错误 |
100012 | 卡密已成功（已有成功记录） |
100013 | 卡密正在处理中 |
100014 | 订单号已存在 |
100015 | 该产品的运营商费率不存在或未开通 |
100016 | 卡号、卡密不符合规则 |
100017 | 回调地址格式、订单号长度、扩展信息长度不合法 （回调地址格式为URL格式，长度不能超过255个字符、订单号32个数字字符以内、扩展信息不能超过50个字符） |
100077 | 卡种为空 |
100018 | 输入的折扣区间不合法 |
100019 | 不支持的电信地方卡 |
100099 | 商户编号不能为空 |
100020 | 销卡有效期不合法(时间要为今天起3天之内的日期，格式为yyyy-MM-dd) |
100021 | 系统错误，可重新提交或联系客服 |
100022 | 该卡号已被锁定，请联系客服 |
100023 | 请求IP不在白名单 |
100024 | 系统繁忙 |
100025 | 无法判断充值卡发行地区 |
100026 | 充值卡预判面值与提交面值不符 |
100027 | 卡号密码错误 |
100028 | 卡号密码加解密失败 |
100029 | 该订单支付已失败，不能重复提交 |
100030 | 提交失败，可以重新提交 |
100031 | 金额小于0或金额格式不正确 |
100032 | 校验码验证失败 |
100033 | 订单相关错误 |
100034 | 收卡失败 |
100035 | 合作方账号类型或者状态错误 |
100036 | 合作方资金账户错误 |
100037 | 合作方余额不足等错误 |
100038 | 合作方支付错误 |
100039 | 合作方没有该业务权限 |
100040 | 商品状态相关错误 |
100041 | 充值卡无效 |
100042 | 处理失败，卡密没有消耗 |
100043 | 系统异常，需要核实 |
100055 | 时间戳不合法 |
100077 | 卡种为空 |
100099 | 商户编号不能为空 |
100044 | 该卡号属于被禁止提交的类型，详情请联系客服咨询 |
100045 | 卡号或密码不正确或已经使用完了 |
100046 | 卡中余额不足 |
100047 | 单据不存在（一般情况不会出现） |
100048 | 卡号已有成功记录 |
3.2回调通知返回码列表
返回码 | 返回码描述信息 |
000000 | 兑换成功 |
000001 | 兑换成功，充值卡实际大于订单金额 |
000002 | 兑换成功，充值卡实际小于订单金额 |
000003 | 错选订单，充值卡实际小于订单金额，兑换失败，充值卡内金额丢失 |
000004 | 金额格式异常 |
000005 | 订单支付已成功，请勿重复提交 |
000006 | 运营商系统维护，支付通道暂时关闭 |
000007 | 运营商系统维护，该面值暂时关闭 |
000008 | 商户没有开通此支付通道，请联系客服 |
000009 | 商户不支持余额卡支付，请联系客服 |
000010 | 订单支付已失败，不能重复提交 |
000011 | 支付失败，该卡已失效，已被锁卡 |
000012 | 失败次数过多，已经锁卡，如需重试请联系客服解锁 |
000013 | 充值卡正在处理中,不能重复提交 |
000014 | 系统处理超时，可以重新提交 |
000015 | 当前商户不支持多卡支付 |
000016 | 面额选择错误 |
000017 | 订单正在处理中，请勿重复提交 |
000018 | 输入参数有误 |
000019 | 运营商系统临时维护，该省充值卡暂时无法支付，可继续提交，且不影响其它省充值卡支付 |
000020 | 充值卡已失效 |
000021 | 运营商系统处理失败，该卡可再次提交 |
000022 | 充值卡金额不足，无法支付订单 |
000023 | 无效的充值卡号或密码 |
000024 | 暂不支持该充值卡支付 |
000025 | 充值卡号密码加解密失败 |
000026 | 订单不存在 |
000027 | 充值卡超时未使用 |
000028 | 充值卡已使用 |
000029 | 第三方运营商官方维护 |
000030 | 充值卡可疑，可联系客服处理 |
000031 | 余额不足 |
000032 | 未使用 |
000033 | 充值卡号、卡密正在处理中 |
000034 | 该充值卡已有成功记录 |
000035 | 该充值卡类型不存在 |
000036 | 第三方销卡系统处理失败，请联系客服了解具体失败信息 |
000037 | 订单超时，可重新提交 |
000038 | 充值卡密码有误 |
000039 | 非卡密原因失败，卡密未被我平台使用 |
000040 | 该卡号不存在 |
000041 | 该卡号属于被禁止提交的类型，详情请联系客服咨询 |
000042 | 卡号、卡密不符合规则 |
000043 | 卡密未激活 |
000044 | 卡密注销状态，不能消耗 |
000045 | 商品状态相关错误 |
000046 | 系统或运营商维护，卡密未被充值平台使用 |
000047 | 原来：销卡失败，核实卡号卡密无误后，可重新提交 修改为：销卡失败，核实卡号卡密无误且状态正常后，可重新提交 |
000048 | 销卡失败，请求面值与实际面值不符 |
000049 | 处理中 |
000050 | 充值卡状态有误 |
000051 | 直接参考memo字段返回的提示信息 |
