logo

卡咪在线API接口文档

来源:卡咪技术

分类:帮助中心

发布时间:2020-01-09 12:11:32

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字段返回的提示信息