资源描述
腾讯公司财付通支付网关商户开发指南Version: 5.0Public date: 2021-11-17All copyright reservedTenpay 第一章 文档描述1 文档说明本操作手册用来指导财付通用户实现与电子商务支付网关系统的顺利对接。请相关技术人员详细阅读本手册。文中黑粗的内容表示要重点注意的内容。2 版本2021-9-17增加字段spbill_create_ip改变文档结构Magichu2021-3-18升级查询接口Magichu3 阅读对象商户开发人员腾讯科技(深圳)财付通支付网关相关技术人员4 接口联系人职责业务支持姓名田小姐 86013388-84564Emailorangetian tencent QQ88881486职责技术支持姓名许先生 86013388-82208Emailxiaoqiangxu tencent QQ88881535第二章 业务功能描述1 作业流程简述1) 商户根据客户的支付行为生成订单，包括商户号、订单号、金额、等支付要素，并提交付款请求。2) 用户支付成功，财付通将后台调用方式将支付结果实时返回商户系统。3) 商户接收到支付成功请求后，输出反应信息给财付通，并完成相关业务逻辑。4) 财付通接收到商户返回的成功信息，再将用户引导回商户网站show_url。 2 接口通知流程1) 返回结果在此通知接口模式中，商户需要确保return_url稳定可靠。该return_url完成接收财付通发送的支付结果信息，交易结果信息将以GET方式传递至商户。财付通只将支付成功的订单进行返回。在传送给商户的参数中，包含使用财付通私钥(非对称加密中的述语)对交易结果数据的数字签名。商户应该先用财付通的公钥文件验证该数字签名，确认该通知信息的合法性。然后完成相关业务逻辑。2) 输出反应财付通要求商户系统return_url输出以下代码：-window.location.href= :/show_url; -财付通不允许在return_url中发生任何跳转，并要求商户系统第一时间输出此为财付通系统判断是否成功返回支付结果的唯一凭证。3) 用户返回财付通接收到以上反应信息后，将引导用户返回show_url进行浏览3 平安控制1 财付通采用加密和数字签名认证体系2 通讯使用SSL协议128位，对数据进行加密3 商户和财付通间数据交互都使用加密，并使用数字签名进行数据验证，确保数据的完整性和不可抵赖性第三章 系统原理1 支付流程支付功能面对用户，为商家和客户提供资金流动的效劳。此处对其中步骤进行详细描述，请仔细阅读。1. 用户在商户系统挑选所需商品。2. 商户系统按照财付通支付请求格式生成订单确认页面展示给用户。3. 用户确认订单信息，选择支付方式，并确认提交给财付通。4. 财付通验证交易单信息，生成支付引导页面展示给用户。5. 用户填写付款帐户信息，并确认提交给财付通或者银行。6. 财付通执行或者接收扣款结果信息，如果失败那么展示支付失败信息给用户如图6.1，如果成功那么继续如图67. 财付通后台按照支付通知格式通知商户系统支付成功结果给return_urla) return_url指定支付成功之后，接收财付通支付结果通知的商户系统URL8. 财付通接收商户系统反应信息，分析报文格式，如果正确那么认为同步成功，取商户反应的result_url,并展示给用户如图9；否那么前台输出错误信息提示同步失败如图9.19. 支付成功结束，展示给用户成功信息。10. 用户端支付通知前台调用，分析错误信息。11. 商户系统反应的结果信息给用户。2 查询流程查询功能是财付通提供的辅助功能，用来协助商户系统处理网络异常引发的各类掉单问题，商户系统可以根据自己的需求来开发自己的订单查询功能。商户可以在用户查看自己购置的物品时触发查询，流程如下：1. 用户查看自己已经付款的商品列表2. 商户系统对未确定的交易单发起订单查询，按照查询请求组织请求报文3. 财付通将查询到的交易信息，返照查询通知格式组织回应报文，通知商户系统4. 商户系统验证订单信息，并更新订单状态5. 商户系统检索已经支付的物品清单，展现给用户3 结算流程财付通将按照商谈确定的结算规那么，将交易款项存放到商家设定的帐号中。此处从略，假设有疑问可以联系财付通业务支持人员。 第四章 支付请求接口协议1 接入URL :/service.tenpay /cgi-bin/v3.0/payservice.cgi2 接入方式POST/GET方式 3 协议参数字段名填写类型说明cmdno必填业务代码, 财付通支付支付接口填 1 date必填商户日期：如20051212bank_type必填银行类型:财付通支付填0desc必填交易的商品名称,32个字符16汉字内,不包含特殊符号purchaser_id必填用户(买方)的财付通帐户(QQ或EMAIL),如无法获取，填空值bargainor_id必填商家的商户号,有腾讯公司唯一分配transaction_id必填交易号(订单号)，由商户网站产生(建议顺序累加)，一对请求和应答的交易号必须相同。transaction_id 为28位长的数值，其中前10位为商户网站编号(SPID)，由财付通统一分配；之后8位为订单产生的日期，如20050415；最后10位商户需要保证一天内不同的事务用户订购一次商品或购置一次效劳，其ID不相同。此财付通订单号必须保持唯一，不能重复,财付通根据此定单号通知商户发货和数据更新等。sp_billno必填商户系统内部的定单号，此参数仅在对账时提供,28个字符内。 total_fee必填总金额，以分为单位,不允许包含任何字符fee_type必填现金支付币种，目前只支持人民币，码编请参见附件中的return_url必填接收财付通返回结果的URL(推荐使用ip)attach必填商家数据包，原样返回spbill_create_ip必填用户IP非商户效劳器IP，为了防止欺诈，支付时财付通会校验此IPsign必填MD5签名结果cs选填字符编码标准，gbk或者utf-84 签名规那么sign=md5(cmdno=1&date=20051219&bargainor_id=1000000301&transaction_id=1000000301200512190000012138&sp_billno=1111&total_fee=1300&fee_type=1&return_url= :/ xxx /tenpay1.aspx&attach=1&spbill_create_ip=219.133.62.73&key=1000000301)对所有请求字段，其值为空的不参加MD5验证，以上拼凑值不要有空格！使用标准MD5算法对该字符串进行加密，即为我们所需的订单MD5 校验码，将其写入sign字段即可。第五章 支付通知接口协议1 通知url用户提供的return_url2 通知方式Get 方式3 协议参数MD5支付通知目的URL$ return_url 商户支付请求中填写的return_url字段名填写类型说明cmdno必填任务代码 1pay_result必填支付结果，详见“返回值编码定义, 0成功pay_info可选支付结果信息，支付成功时为空date必填商户日期bargainor_id必填卖方账号商户spidtransaction_id必填财付通交易号(订单号) sp_billno必填商户系统内部的定单号，此参数仅在对账时提供。 total_fee必填订单总金额，以分为单位fee_type必填现金支付币种attach必填商家数据包，原样返回sign必填MD5签名结果4 签名规那么sign=md5(cmdno=1&pay_result=0&date=20051220&transaction_id=1000000301200512200000000004& sp_billno=k0000000001&total_fee=100& fee_type=1&attach=test_attach&key=1000000301)对所有请求字段，其值为空的不参加MD5验证，以上拼凑值不要有空格！使用标准MD5算法对该字符串进行加密，即为我们所需的订单MD5 校验码，将其写入sign字段即可。第六章 查询接口请求协议1 接入url :/mch.tenpay /cgi-bin/cfbi_query_order_v3.cgi2 接入方式该接口接入方式为post3 协议参数字段名填写类型说明cmdno必填业务代码, 财付通支付查询接口填 2 date必填商户订单日期：如20051212bargainor_id必填商家的商户号,由腾讯公司唯一分配transaction_id必填财付通交易单号(订单号)。sp_billno必填商户系统内部的定单号，此参数仅在对账时提供。 attach必填商家数据包，原样返回output_xml必填固定为1charset必填字符集，GB2312或UTF-8sign必填MD5签名结果4 请求签名规那么参数以字母顺序排序key除外，key放在最后。输入例如：sign=md5(attach=1&bargainor_id=1000000301&charset=GB2312&cmdno=2&date=20211201&output_xml=1& sp_billno=1111&transaction_id=1000000301200512190000012138&key=1000000301)对所有请求字段，其值为空的不参加MD5验证，以上拼凑值不要有空格！使用标准MD5算法对该字符串进行加密，即为我们所需的订单MD5 校验码，将其写入sign字段即可。第七章 查询接口通知协议1 返回方式数据将以xml形式在同一会话中同步返回例如： a 1900000108 GB2312 2 20210315 1 1 未付款 2006 00 交易成功 :/192.168.1.129/bank/cft_return.aspx 0CC280C5219302E95C1A3D01CB442124 56212087 3000 1900000108202103150056212087 2 返回参数MD5查询通知字段名填写类型说明cmdno必填任务代码 2pay_result必填支付结果，详见“返回值编码定义, 0成功pay_info可选支付结果信息，支付成功时为空date必填商户日期bargainor_id必填卖方账号商户spidtransaction_id必填财付通交易号(订单号) sp_billno必填商户系统内部的定单号，此参数仅在对账时提供。 total_fee必填订单总金额，以分为单位fee_type必填现金支付币种attach必填商家数据包，原样返回sign必填MD5签名结果3 返回签名规那么参数以字母顺序排序key除外，key放在最后。sign=md5(attach=1&bargainor_id=1000000301&cmdno=2&date=20211201&fee_type=1&pay_info=OK&pay_result=0&sp_billno=7654321&total_fee=3000&transaction_id=1000000301200512190000012138&key=1000000301)对所有请求字段，其值为空的不参加MD5验证，以上拼凑值不要有空格！使用标准MD5算法对该字符串进行加密，即为我们所需的订单MD5 校验码，将其写入sign字段即可。第八章 网银直联实现方法1 定义财付通网银直联是财付通为商户提供的免费增值效劳。财付通网银直联是指用户可以在商户网站选择银行，进行支付，直接进入银行支付页面，不再转入财付通支付页面。财付通网银直联可以有效提升支付成功率，优化用户支付体验，降低用户支付心理门槛。2 效果重要提示：开通直联银行后，在财付通支付界面效果上请与以下列图示保持一致。如果在不经财付通同意的情况下修改直联银行展现样式，财付通将保存收回此功能的权利。3 实现方法财付通网银直联对所有用户默认开通，不需要另行申请，所使用的商户号和密钥，也不需要另行申请。在财付通支付接口中，有指定支付银行的参数bank_type，将用户选择的银行，按照财付通银行编码表赋值给bank_type，在提交到财付通时，就自动跳转到用户所选择的网上银行。财付通银行编码表见第九章第一节?银行代码?，银行LOGO图片在demo开发包的images文件夹中商户可根据需要自行取用。例如：bank_type=1038将会直联招商银行。第九章 帮助中心如果您在财付通的申请，使用过程出现相关的问题可登陆财付通企业帮助中心查看相关的常见问题及其解答如果您在财付通的集成开发过程中遇到相关的问题，可登陆腾讯财付通产品交流查看相关的问题及其解答，里面涵盖了在集成开发过程见常见的问题第十章 枚举类型1 银行代码编码银行名称0财付通1001招商银行借记卡(不支持信用卡，信用卡请用1038)1002中国工商银行1003中国建设银行1004上海浦东开展银行1005中国农业银行1006中国民生银行1008深圳开展银行1009兴业银行1010平安银行1020交通银行1021中信银行1022中国光大银行1024上海银行1025华夏银行1027广东开展银行1028中国邮政储蓄银行仅支持广东地区1038招商银行信用卡，招行限额499元1032北京银行1033网汇通1052中国银行2 货币类型1 RMB 人民币2 - USD 美元3 - HKD 港币3 返回值编码pay_result返回值编码 ：0 成功其他 错误4 自动补单机制财付通支持自动补单，补单通过重复请求商户提供的回调页面请求接口参数return_url指定 实现。商户开发人员编写该页面代码时应注意检查订单状态，防止重复发货。财付通在下面条件下执行自动补单：1) 银行系统发生补单时用户选择网银账户支付，支付后银行与财付通之间发生掉单，稍后银行与财付通之间发生补单时；2) 用户完成支付，财付通请求商户回调页面失败时；3) 商户回调页面返回内容格式不符合财付通标准时格式标准见接口“通知模流程；5 接入考前须知您在接入时，需要进行的测试，订单金额必须小于1元，即total_fee必须小于100
展开阅读全文