携程预付卡分销平台对接指南

携程预付卡分销平台对接指南修订记录平台概述业务流程业务准备技术准备接口列表附件说明联系我们

修订记录

时间	内容	备注
2020-03-09	V1.0	新增礼品卡的账户充值业务
2020-05-11	V1.1	新增礼品卡的电子卡业务
2020-09-09	V1.2	queryGiftCardsByOrder增加生效日期和截止日期

平台概述

携程预付卡分销平台 是由携程预付卡技术团队提供，可以满足B端商户的购卡、充值的业务需求，具有简单、稳定、安全、高效、便捷等特点。B端商户办理入驻分销平台后，通过采购流程可以获得一个用于分销业务场景的资金池，B端企业的用户下单会消耗资金池里的金额；当消耗资金池触发阈值时会触发邮件提醒；当资金池消耗殆尽时，B端商户的用户继续下单将会返回下单失败。

携程礼品卡 是携程旅行网合法备案的单用途预付费卡，可以在携程环境中消费，携程礼品卡需要领用至携程会员帐户内方可使用。携程礼品卡在被领用至携程会员账户时需要设置支付密码，密码可以由顾客自行修改。携程礼品卡内预付价值一元等值于一元人民币。卡内余额不计息，不透支，不提供兑现、找零，严禁任何形式的套现等违规行为。

业务流程

查询分销资金池

账户充值（礼品卡）

电子卡（礼品卡）

业务准备

企业入驻
- 经业务经理确认后，由分销平台的运营人员依据B端商户所提供的企业信息完成企业入驻流程。
企业采购
- 业务经理/运营人员依据B端商户的业务需求，采购相应类型的分销额度到分销资金池，分销资金池将用于支付B端商户的用户分销订单。

技术准备

完成业务准备后，联系技术人员sunlei@trip.com，可以获得测试环境的对接参数。

测试环境对接参数

字段名	字段值	字段说明
CustomerNo	XXXX	商户名(平台提供)
CustomerPwd	aaaa-bbbb-cccc-dddd	商户秘钥(平台提供)
URL	http://gateway.fat.ctripqa.com/flopenapi/api	请求地址（平台提供，有时效限制）
AES密钥	4hdfgnfhgds364tyfdtghsdfgdfh	用于礼品卡券密的AES密钥(详见附件)

完成测试环境的联调后，再次联系技术人员sunlei@trip.com，生产环境的对接参数将邮件发给合同上的邮箱地址。

生产环境对接参数

字段名	字段值	字段说明
CustomerNo	XXXX	商户名(平台提供)
CustomerPwd	eeee-ffff-gggg-hhhh	商户秘钥(平台提供)
URL	https://b.ctrip.com/flopenapi/api	请求地址(正式)
AES密钥	4hdfgnfhgds364tyfdtghsdfgdfh	用于礼品卡券密的AES密钥(详见附件)

接口列表

提交订单

接口名：submitDistributionOrder
接口请求地址：http://gateway.fat.ctripqa.com/flopenapi/api/submitdistributionorder
Request

类型名	字段名	数据类型	长度	必填	字段描述
requestHeader	customerNo	string	20	Y	商户名（平台提供）
	timestamp	long	20	Y	请求时间戳（详见附件）
	signature	string	50	Y	签名（详见附件）
param	ticketType	string	20	Y	订单类型（账户充值：“Recharge”，电子卡：“Electronic”）
	transactionID	string	50	Y	流水号（GUID格式，防重复，调用方保证唯一）
	mobilePhone	string	11	N	手机号（订单类型为账户充值时必传；订单类型为电子卡时不传，详见附件）
	countryCode	string	10	N	国家码（不传默认86）
	orderAmount	decimal	18，2	Y	订单总金额，必须与SUM（OrderItem.FaceAmount* OrderItem.Quantity）一致
	remark	string	200	N	备注
orderItemList	List<orderItem>				购买项集合（账户充值限制1行，电子礼品卡限制1-5行）
orderItem	cardType	int	--	Y	卡类型（0：电子卡，2：账户充值）
orderItem	ticketCategoryID	int	--	N	卡类别（2：任我游，3：任我行）
orderItem	faceAmount	decimal	18，2	Y	卡面额（账户充值：1-100000元，电子卡：1-1000元）
orderItem	quantity	int	--	Y	数量（账户充值：只能等于1，电子卡：1-999张）
orderExtList	List<keyValueType>			N	订单扩展字段集合
keyValueType	key	string	50	Y	扩展字段名，例如“welfareYear”
keyValueType	value	string	50	Y	扩展字段值，例如“2023”

Response

类型名	字段名	数据类型	长度	必填	字段描述
	code	int	20	Y	结果码（0：成功，非0 ：失败或者异常）
	message	string	200	Y	结果信息
data	orderID	long	--	Y	订单号（仅做关联展示）
	transactionID	string	50	Y	流水号（与request中的流水号一致）

code说明
未接入subCode

code	描述
100	参数校验为空/传参不合法
101	验签失败
102	customNO错误
110	Request is expired
111	请求action错误
201	IP白名单限流
300	系统错误
301	下单失败

Demo报文之礼品卡账户充值：


xxxxxxxxxx
request = 
{
    "requestHeader": {
        "customerNo": "customerNo",
        "signature": "e775b82334d15fc6c307af6cf44eb714",
        "timestamp": 1591087342
    },
    "param": {
        "ticketType": "Recharge",
        "transactionID": "BPRecharge_2020031****",
        "mobilePhone": "1351234****",
        "countryCode": "86",
        "orderAmount": 5.0,
        "remark": "test",
        "orderItemList": [
            {
                "cardType": 2,
                "ticketCategoryID": 3,
                "faceAmount": 5.0,
                "quantity": 1
            }
        ],
        "orderExtList": [
            {
              "key": "welfareYear",
              "value": "2023"
            }
        ]
    }
}
response = 
{
    "code": 0,
    "message": "成功",
    "data": {
    "orderID": 1,
        "transactionID": "BPRecharge_202003101****"
    },
    "successful": true
}

Demo报文之礼品卡电子卡：


xxxxxxxxxx
request = 
{
    "requestHeader": {
        "customerNo": "customerNo",
        "signature": "e775b82334d15fc6c307af6cf44eb714",
        "timestamp": 1591087342
    },
    "param": {
        "ticketType": "Electronic",
        "transactionID": "BPElectronic_2020031****",
        "mobilePhone": "1351234****",
        "countryCode": "86",
        "orderAmount": 15.0,
        "remark": "test",
        "orderItemList": [
            {
                "cardType": 0,
                "ticketCategoryID": 3,
                "faceAmount": 5.0,
                "quantity": 1
            },
            {
                "cardType": 0,
                "ticketCategoryID": 3,
                "faceAmount": 10.0,
                "quantity": 1
            }
    ]
    }
}
response = 
{
    "code": 0,
    "message": "成功",
    "data": {
        "orderID": 2,
        "transactionID": "BPElectronic_2020031****"
    },
    "successful": true
}

接入subCode（需联系我方技术开启配置），当code= 301时，添加subCode

subCode	描述
-1	系统错误
1101	transactionID不能为空
1102	orderItem不能为空
1103	ticketType有误
1104	orderAmount不能为空
1105	orderAmount有误，必须与SUM（OrderItem.FaceAmount* OrderItem.Quantity）一致
1106	countryCode有误
1107	mobilePhone有误
1108	ticketType=recharge，orderItemList订单明细只能有一条
1109	ticketType=recharge，quantity为1
1110	ticketType=Electronic，订单面额不可超过5种
1111	ticketType=Electronic，订单sum( OrderItem.Quantity)面额不可超过企业配置最大卡张数
1112	faceAmount必须等于saleAmount
1113	ticketType=electronic，faceAmount不能大于1000),ticketType=recharge，faceAmount不能大于企业配置的最大面额
1114	cardType和ticketType不一致
1115	订单ticketCategoryID必须相同
1116	ticketCategoryID有误,productType=GiftCard，ticketCategoryID必须为2或3),productType=WelfareCredit，ticketCategoryID不传
1117	faceAmount必须是大于等于1
1118	faceAmount只支持2位小数
1119	productType有误
1120	purchaseID有误，必须大于0
2201	企业不支持自动创建携程账户
2204	手机号绑定uid已超额
2205	手机号关联员工未激活
2206	手机号关联员工未绑定携程UID
2209	手机号未绑定携程账号
2207	创建用户失败
2213	手机号绑定uid无效
2301	查询企业账户是否可用失败，请重试
2302	查询企业账号余额失败，请重试
2303	企业账户额度不足
2304	电子卡库存不足
2305	企业账户资金池已被冻结，不支持下单
2306	冻结额度失败
2307	查询第三方员工信息失败
2501	创建订单失败

Demo报文之礼品卡账户充值：


xxxxxxxxxx
{
    "requestHeader": {
        "customerNo": "customerNo",
        "signature": "e775b82334d15fc6c307af6cf44eb714",
        "timestamp": 1591087342
    },
    "param": {
        "ticketType": "Recharge",
        "transactionID": "BPRecharge_2020031****",
        "mobilePhone": "1351234****",
        "countryCode": "86",
        "orderAmount": 5.0,
        "remark": "test",
        "orderItemList": [
            {
                "cardType": 2,
                "ticketCategoryID": 3,
                "faceAmount": 5.0,
                "quantity": 1
            }
        ],
        "orderExtList": [
            {
              "key": "welfareYear",
              "value": "2023"
            }
        ]
    }
}
response = 
{
"code": 301,
"message": "企业账户资金池已被冻结，不支持下单",
"data": null,
"subCode": 2305,
"successful": false
}

查询订单

接口名：queryDistributionOrders
接口请求地址：http://gateway.fat.ctripqa.com/flopenapi/api/querydistributionOrders
Request

类型名	字段名	数据类型	长度	必填	字段描述
requestHeader	customerNo	string	20	Y	商户名（系统分配）
	timestamp	long	20	Y	请求时间戳（详见附件）
	signature	string	50	Y	签名（详见附件）
param	pageIndex	int	--	N	分页索引（默认1）
	pageSize	int	--	N	分页大小（默认20，最大300）
	transactionID	string	200	N	流水号（多个流水号支持英文半角逗号拼接）
	ticketType	string	200	N	订单类型（Recharge：账户直充，Electronic：电子卡）
	orderStatus	string	200	N	订单状态（英文半角逗号拼接，详见附件）
	startDate	string	--	N	起始日期（默认三个月前）
	endDate	string	--	N	截止日期（默认当前时间）

Response

类型名	字段名	数据类型	长度	必填	字段描述
	code	int	20	Y	结果码（0：成功，非0 ：失败或者异常）
	message	string	200	Y	结果信息
data	totalRowCount	int			总记录条数
orderInfoDTOList	List
orderInfoDTO	orderID	long	--	Y	订单号
orderInfoDTO	transactionID	string	50	Y	流水号
orderInfoDTO	ticketType	string	20	Y	订单类型（Recharge：账户直充，Electronic：电子卡）
orderInfoDTO	orderDate	datetime	--	Y	下单时间
orderInfoDTO	mobilePhone	string	11	Y	手机号
orderInfoDTO	countryCode	string	10	Y	国家码
orderInfoDTO	remark	string	200	Y	备注
orderInfoDTO	orderAmount	decimal	18,2	Y	订单金额
orderInfoDTO	orderStatus	string	50	Y	订单状态（详见附件）
orderInfoDTO	ctripAccount	string	50	N	充值UID（当订单类型是账户充值时存在）
orderItemList	List	string	50	Y	流水号
orderItem	orderItemID	long	--	Y	购买项ID
orderItem	cardType	int	--	Y	卡类型（0：电子卡，2：账户充值）
orderItem	ticketCategoryID	int	--	Y	卡类别（2：任我游，3：任我行）
orderItem	faceAmount	decimal	18，2	Y	卡面额
orderItem	quantity	int	--	Y	数量

Demo报文：


xxxxxxxxxx
    request = 
    {
        "requestHeader": {
            "customerNo": "customerNo",
            "signature": "e775b82334d15fc6c307af6cf44eb714",
            "timestamp": 1591087342
        },
        "param": {
            "orderID": "",
            "transactionID": "BPRecharge_202003101****",
            "ticketType": "Recharge",
            "orderStatus": "Init,Paying",
            "startDate": "2020-01-12 18:16:17.000",
            "endDate": "2020-03-20 17:16:17.000"
        }
    }
    response = 
    {
        "code": 0,
        "message": "成功",
        "data": {
            "orderInfoDTOList": [{
            "orderID": 3,
            "transactionID": "BPRecharge_202003101****",
            "ticketType": "Recharge",
            "orderDate": "2018-03-10 10:48:20.000",
            "mobilePhone": "1351234****",
            "countryCode": "86",
            "remark": "test",
            "orderStatus": "Processed",
            "ctripAccount": "170000****",
            "orderAmount": 5.0,
            "orderItemList": [{
                    "cardType": 2,
                    "ticketCategoryID": 3,
                    "faceAmount": 5.0,
                    "quantity": 1
                    }]
            }],
            "totalRowCount": 1
            },
        "successful": true
    }

查询订单内的礼品卡（订单类型仅限电子卡）

接口名：queryGiftCardsByOrder
接口请求地址：http://gateway.fat.ctripqa.com/flopenapi/api/queryGiftCardsByOrder
Request

类型名	字段名	数据类型	长度	必填	字段描述
requestHeader	customerNo	string	20	Y	商户名（系统分配）
	timestamp	long	20	Y	请求时间戳（详见附件）
	signature	string	50	Y	签名（详见附件）
param	transactionID	string	50	Y	流水号
	pageIndex	int	--	N	分页索引（默认1）
	pageSize	int	--	N	分页大小（默认20，最大200）

Response

类型名	字段名	数据类型	长度	必填	字段描述
	code	int	20	Y	结果码（0：成功，非0 ：失败或者异常）
	message	String	200	Y	结果信息
data	totalRowCount	int		Y	总记录条数
giftCardList	List
giftCardInfoDTO	orderItemID	long	--	Y	购买项ID
giftCardInfoDTO	serialNum	String	14	Y	卡序列号
giftCardInfoDTO	ticketCategoryID	int	--	Y	卡类别（2：任我游，3：任我行）
giftCardInfoDTO	faceAmount	Decimal	18,2	Y	卡面额
giftCardInfoDTO	cardCode	String	12	Y	卡号
giftCardInfoDTO	password	String	200	Y	礼品卡密码的密文格式（详见附件）
giftCardInfoDTO	cardStatus	int	--	Y	礼品卡状态（详见附件）
giftCardInfoDTO	effectiveDate	String	50	Y	生效日期（yyyy-MM-dd HH:mm:ss.SSS）
giftCardInfoDTO	expirationDate	String	50	Y	失效日期（yyyy-MM-dd HH:mm:ss.SSS）

Demo报文：


xxxxxxxxxx
request = 
{
    "requestHeader": {
        "customerNo": "customerNo",
        "signature": "e775b82334d15fc6c307af6cf44eb714",
        "timestamp": 1591087342
    },
    "param": {
        "transactionID": "BPElectronic_2020031****",
        "pageIndex": 1,
        "pageSize": 20
    }
}
response = 
{
    "code": 0,
    "message": "成功",
    "data": {
        "giftCardList": [
             {
                "orderItemID": 33670,
                "serialNum": "3000000002823752",
                "ticketCategoryID": 3,
                "faceAmount": 10,
                "cardCode": "928542665495",
                "password": "xi7IXaxS9whVaAYmKNvJ1Q==",
                "cardStatus": 5,
                "effectiveDate": "2020-09-10 0:00:00.000",
                "expirationDate": "2023-09-9 23:59:59.997"
            },
            {
                "orderItemID": 33671,
                "serialNum": "3000000002823753",
                "ticketCategoryID": 3,
                "faceAmount": 10,
                "cardCode": "980788193810",
                "password": "2aiEYpZ5AadYfsfXXBBX0w==",
                "cardStatus": 5,
                "effectiveDate": "2020-09-10 0:00:00.000",
                "expirationDate": "2023-09-9 23:59:59.997"
            }],
            "totalRowCount": 2
        },
    "successful": true
}

查商户资金池

接口名：queryCompanyInfo
接口请求地址：http://gateway.fat.ctripqa.com/flopenapi/api/queryCompanyInfo
Request

类型名	字段名	数据类型	长度	必填	字段描述
requestHeader	customerNo	string	20	Y	商户名（系统分配）
	timestamp	long	20	Y	请求时间戳（详见附件）
	signature	string	50	Y	签名（详见附件）
param	cardType	int	--	Y	卡类型（0：电子卡，2：账户直充）
	ticketCategoryID	int	--	N	卡类别（2：任我游，3：任我行）

Response

类型名	字段名	数据类型	长度	必填	字段描述
	Code	int	20	Y	结果码（0：成功，非0 ：失败或者异常）
	Message	String	200	Y	结果信息
data	TotalAmount	decimal	18,2	Y	总采购金额
	AvailableAmount	decimal	18,2	Y	可用发放金额

Demo报文：


xxxxxxxxxx
request = 
 {
    "requestHeader": {
        "customerNo": "customerNo",
        "signature": "e775b82334d15fc6c307af6cf44eb714",
        "timestamp": 1591087342
    },
    "param": {
        "cardType": 2,
        "ticketCategoryID": 3
    }
}
response = 
{
    "code": 0,
    "message": "成功",
    "data": {
        "totalAmount": 2090.0000,
        "availableAmount": 90.0000
    },
    "successful": true
}

附件说明

关于分销订单状态

关于礼品卡状态
- 1：未激活
- 2：未领用
- 3：已领用
- 4：已作废
- 5：已激活
- 6：变更中
关于时间戳Timestamp
- 限制时差最大5分钟，否则返回失效
- 获取方法示例：Instant.now().getEpochSecond()
- 获取示例值：1588054199
关于流水号TransactionID
- 流水号TransactionID 由B端商户提供并保证唯一
- 流水号TransactionID可以用于防重复、幂等，当使用重复的流水号TransactionID提交订单时，系统不会重新下单，而是返回之前的订单号
- 流水号TransactionID将用于整个OpenApi的交互和最终订单数据的统计
关于接口签名算法
- md5Encrypt(CustomerNo + "&" + CustomerPwd + "&" + Timestamp + "&" + JSON.toJSONString(param))
- 获取示例值：e775b82334d15fc6c307af6cf44eb714
- param定义的参数顺序以文档为准
关于礼品卡密码的密钥
- 当接入方购买电子礼品卡时，礼品卡的密码需要加密之后在网络中传输
- 接入方需要为此单独申请一个密钥，提供一个接收人的邮箱，再提供以下信息：所属公司、姓名、手机号、邮箱
- 这个邮箱将用接收携程信安回复的FAT/UAT/PRO三个环境的密钥，请接入方妥善保管密钥
- 接入方拿到密文后，使用AES的CBC模式进行解密，密钥是长度为32的字符串，截断前16位的字符串作为Key，后16位的字符串作为IV，得到的6位数字就是礼品卡密码的明文
关于手机号
- 订单类型为账户直充时必传，强烈建议该手机号已经绑定携程UID
- 请在企业入驻时告知是否需要自动创建新的携程UID
- 配置一：不允许创建新的携程UID，当手机号没有绑定的携程UID时下单失败，返回错误的Code和Message
- 配置二：允许创建新的携程UID，当手机号没有绑定的携程UID时，创建UID，完成礼品卡的账户充值，手机短信通知用户名和密码，以及账户余额变化；当手机号有绑定的携程UID时，完成礼品卡的账户充值，手机短信通知账户余额变化；
关于返回的错误码
- 1：未知异常，如果是下单场景，可以使用TransactionID来查询订单；
- 100：请求参数不合法；
- 101：签名不合法，参见签名算法；
- 110：请求超时，参见时间戳有效期；
- 111：请求方法不存在；
- 300：请求方法执行失败；
- 301：系统异常；

联系我们

技术支持： LP_TechServ@trip.com