19pay捷迅充值卡兑换平台直联接口规范2.01(卡实际金额).doc

北京高阳捷迅信息技术有限公司 19PAY 捷迅支付商户直联接口规范版本号3.00北京高阳捷迅信息技术有限公司（19PAY）最后修改2009年11月01日Copyright 高阳捷迅 2006-2010 北京高阳捷迅信息技术有限公司目 录1.概要21.1目的21.2版权声明21.3客户服务22.支付接口32.1 接口说明32.2订单支付类型说明32.3 网上支付业务流程32.4 支付通道查询42.5 支付请求52.6支付结果服务器端通知(后台通知)72.7注意事项82.8 返回码列表.91. 概要1.1目的帮助商户接入 19PAY 支付平台，快速掌握 19PAY支付平台各项功能，便于尽快投入使用。1.2版权声明此文档版权归北京高阳捷迅信息技术有限公司所有。作为本系统的最终用户，可以拥有该份文档的使用权，但未征得北京高阳捷迅信息技术有限公司的书面批准，不得向第三方借阅、出让、出版该文档。1.3客户服务服务热线：400-019-19992. 支付接口2.1 接口说明本接口主要目的是为了让商户系统接入 19PAY 支付平台，能够通过预付费卡等方式快捷的实现电子支付。 请求方式： 商户系统19PAY支付平台商户系统作为请求客户端，按照本接口的约定发送请求，而19PAY支付平台监听来自商户系统的请求给予处理，处理完成后返回商户系统，同时提供查询接口。2.2订单支付类型说明1、 神州行充值卡神州行充值卡支付，玩家在商户网站页面输入卡号密码，商户请求信息到高阳捷迅卡兑换平台，高阳捷迅卡兑换平台进行处理2、 联通充值卡联通卡支付，玩家在商户网站页面输入卡号密码，商户请求信息到高阳捷迅卡兑换平台，高阳捷迅卡兑换平台进行处理3、 电信充值卡电信充值卡支付，玩家在商户网站页面输入卡号密码，商户请求信息到高阳捷迅卡兑换平台，高阳捷迅卡兑换平台进行处理 详细说明见: /page/pgwpage/help.jsp2.3 网上支付业务流程网上支付业务流程步骤说明：1、 用户登录商户网站，选择商品、输入充值卡卡号、密码等支付信息，商户网站产生预定单信息，包括商户唯一交易号、订单号、金额、充值卡号及充值卡密码等信息；2、 用户确认支付后，服务商将商户唯一交易号、订单号、支付金额、支付方式、产品名称等信息发送到高阳捷迅卡兑换平台；（参考接口2.5）3、 高阳捷迅系统根据商户发送的支付方式自动转到不同的支付系统（神州行、联通等）进行支付处理；4、 各支付系统将处理信息返回到高阳捷迅卡兑换平台； 5、 高阳捷迅卡兑换平台进行处理后，返回处理结果及相关的订单信息和捷迅交易流水号给商户服务器；（参考接口2.6）6、 商户收到信息进行验证，为用户提供服务。2.4 支付通道查询l 请求方式商户系统 19PAY卡兑换平台商户系统以HTTP Post的方式请求19PAY的接口地址，并按照接口参数定义传送数据。19PAY卡兑换平台将以html方式返回查询结果。l 接口地址测试环境 32/card/channel.jspl 接口参数参数含义长度是否非空备注merchant_id商户代码20非空19PAY统一分配的商户代码l 接口返回返回所有支付通道的四个相关属性组成的字符串：支付通道编码（pc_id），支付方式编码（pm_id），支付通道省份，支付方式描述。每个参数之间用“|”间隔，每种支付通道之间也使用“|”间隔。提示：解析此字符串时要注意有些语言需要用”|”来解析，如java中String info = 2.00|4004; String a = info.split(|);2.5 支付请求l 请求方式商户系统19PAY卡兑换平台商户系统通过HTTP协议链接到19PAY进行支付，并按照接口参数定义以post传送相关数据。l 接口地址测试地址：32/card/pgworder/orderdirect.do(正试地址另行通知)l 接口参数参数含义长度是否非空备注version_id版本号10非空本接口版本号：2.00merchant_id商户代码20非空19PAY统一分配的商户代码verifystring验证摘要串100非空32位小写详见验证方式order_date订单日期10非空格式为YYYYMMDDorder_id商户订单号30非空该订单号由商户系统生成。order_id唯一确定一条订单。amount订单金额8非空单位为元，精确到分，格式为50.0019pay系统默认充值卡面额与此参数值相同cardnum1充值卡卡号码的暗码30非空使用DES算法，通过密钥对卡号加密。详见后续描述cardnum2充值卡密码的暗码30非空使用DES算法，通过密钥对卡号加密。详见后续描述currency货币类型8非空RMB：人民币pm_id支付方式id20非空用于区分支付通道的类别，从接口地址获取pc_id支付通道id20非空接口地址中获取，详见2.4。returl支付请求返回url128空由于支付过程中不出现我们的页面，此参数无意义，设为空。notify_url后台通知地址128可空后台通知地址，如果空则以数据库配置为准，如果非空则以商户传入地址为准。retmode支付请求返回格式8可空如果为空，请求返回xml格式；赋值为”1”，请求返回纯文本格式。order_pdesc商品描述255可空此参数提交之后在支付结果通知中可能不会再传回给商户，如需要依据请自行进行入库处理。user_name订货人姓名10可空同上user_phone用户电话20可空同上user_mobile用户手机号20可空同上user_email用户EMAIL128可空同上l 请求的验证方式本接口采用MD5摘要对请求进行确认。验证失败的请求将不予处理。商户首先需要向19PAY支付平台申请商户代码（merchant_id）及加密串（merchant_key），并按照以下规则来构造验证摘要串（verifystring）。MD5摘要源串：version_id=%s&merchant_id=%s&order_date=%s&order_id=%s&amount=%s¤cy=%s &cardnum1=%s&cardnum2=%s&pm_id=%s&pc_id=%s&merchant_key=%s商户以具体的参数值替代以上的%s，并保证顺序及每项的准确性，参数如为空值则直接替代空串即可。l 接口卡序列号，卡密码的加密、解密方式商户系统用DES通过商户密钥(merchant_key)对卡号和密码进行加密。注：DES使用的是对称密钥，即加密和解密的密钥是相同的。请注意不要用反，即，解密的方法不要用去加密。l 接口返回xml格式 2.00 4004 ee56d480cc599e7e3bd6610481bb42d2 20061101 19PAYTEST71336 0.01 RMB GW200712251147114562 LTJFK00010001 LTJFK P 1 l Xml标签定义标签含义备注version_id版本号本接口版本号: 2.00merchant_id商户代码19PAY统一分配的商户代码verifystring验证摘要串32位小写详见验证方式order_date支付请求提交时间返回请求中的order_dateorder_id商户订单号返回请求中的order_id amount订单金额返回请求中的amountcurrency货币类型返回请求中的currencypay_sq19PAY支付流水号pay_date支付时间格式为YYYYMMDDHHMMSSpc_id支付通道接口地址中获取的，详见2.5pm_id支付方式同pm_idresult收单结果P：收单成功 F：收单失败resultstr错误码10016：该订单支付已成功，不能重复提交10076：该订单支付已失败，不能重复提交10120：该订单正在处理中10014：金额格式异常10123：协议输入参数有误82009：卡号密码加解密失败11111：MD5验证失败或订单参数有误。l 接口返回纯文本格式参数值之间用”|”间隔，参数顺序和含义与xml格式顺序相同，形式如下：version_id|merchant_id|verifystring|order_date|order_id|amount|currency|pay_sq| pay_date|pc_id|pm_id|result|resultstr提示：解析此字符串时要注意有些语言需要用”|”来解析，如java中String info = 2.00|4004;String a = info.split(|);l 接口返回验证方式19PAY平台按照以下规则来构造验证摘要串（verifystring）。MD5摘要源串：version_id=%s&merchant_id=%s&order_date=%s&order_id=%s&amount=%s¤cy=%s&pay_sq=%s&pay_date=%s&pc_id=%s&result=%s&merchant_key=%s19PAY平台将以具体的参数值替代以上的%s，并保证顺序及每项的准确性，参数如为空值则直接替代空串。商户系统接到请求返回后将按照同样的规则组成MD5摘要源串，得到结果后与xml中的verifystring进行比对来决定下一步操作。l 建议为了提高订单成功率，以及订单的质量，请商家在填写卡号密码的页面，对支付通道的卡号密码做位数以及面额限制，具体如下：通道名称卡号位数密码位数支持面额全国移动充值卡171810、20、30、50、100、200、300、500全国联通一卡充151920、30、50、100、200、300、500全国电信卡191820、30、50、100福建移动呱呱通充值卡161710、20、30、50、100江苏移动充值卡161730、50、100辽宁移动电话交费卡162110、20、30、50、100浙江移动缴费券10810、20、30、50、100、2002.6支付结果服务器端通知(后台通知)l 前置条件 结果通知notify_url：该值由商户直接提供给19PAY技术人员。19PAY卡兑换平台将根据这个url来发送后台服务器端的支付结果通知。 注意：如果商户在支付请求中传这个notify_url则以商户传的为准，否则以数据库配置为准。l 请求方式19PAY卡兑换平台商户系统19PAY卡兑换平台以HTTP Post方式发送支付结果通知给notify_url，商户系统在接收到支付结果后返回Y或者N（Y：成功 N：失败）19PAY卡兑换平台将在用户完成支付后第一时间发送结果通知，以确保商户能够及时进行下一步处理。如果19PAY卡兑换平台接收不到返回结果，将按照一定的时间间隔重发(时间间隔计算方法为：10*n2 分钟 n为重发次数)，直到超过一个限定的时间（暂定50次），19PAY系统则认为商户系统的接口出了问题，将暂停发送。对于已经暂停发送结果通知的商户，高阳捷迅将及时通知商户，商户也可联系客服进行重发或者通过商户专区查询补发。l 接口地址getresult_urll 接口参数参数含义是否非空备注version_id版本号非空本接口版本号:3.00merchant_id商户代码非空19PAY统一分配的商户代码verifystring验证摘要串非空32位小写详见接后描述order_date订单日期可空格式为YYYYMMDDorder_id商户订单号非空result支付结果非空amount金额非空currency币种非空pay_sq支付流水号非空pay_date支付时间非空格式为YYYYMMDDHHMMSScount卡支付次数可空card_num1卡号非空卡号DES加密card_pwd1卡密码非空卡密码DES加密pm_id1支付方式非空pc_id1支付通道编号非空card_status1卡支付状态非空0 成功 1失败card_code1卡支付错误码非空详见错误返回码card_date1卡支付完成时间非空格式为YYYYMMDDHHMMSSr1结算金额非空结算金额l 接口返回商户系统如果对该支付结果确认，则返回Y，否则返回N。返回请不要带任何html等静态标记。注：此接口19pay会在后台通知中告知销卡金额是多少，即参数r1。商户只需要判断card_status1和r1即可，不需要判断result和amountl 验证方式请求的MD5验证摘要串由该串产生：version_id=%s&merchant_id=%s&order_id=%s&result=%s&order_date=%s&amount=%s¤cy=%s&pay_sq=%s&pay_date=%s&count=%s&card_num1=%s&card_pwd1=%s&pc_id1=%s&card_status1=%s&card_code1=%s&card_date1=%s&r1=%s&merchant_key=%s2.7注意事项1、 MD5加密结果是32位小写字符串。2、 pm_id、pc_id从接口2.4中可以获取。3、 参数verifystring由每个接口里的验证方式中的验证串赋值之后进行MD5加密所得。4、 MD5加密原串中的cardnum1、cardnum2是进行DES加密之后的。5、 order_pdesc、user_name、user_phone、user_mobile、user_email这些参数19pay系统在商户提交之后可能不会再返回，如需要依据，请在提交的时候自行进行入库处理，之后依据订单号查询发货。6、 商户后台收到后台通知，根据支付通知的订单号，先查该订单支付状态，商户判断自己的系统是否处理过订单。处理过程如下： 如果商户处理过订单 ，则返回 Y (19pay 支付系统收到商户返回的Y 后，不会重复发通知) 如果商户没处理过订单 ，则商户进行发货并修改订单的支付状态 ，然后返回Y (19pay 支付系统收到返回的Y 后，不会重复发通知) 7、 订单号不能重复8、 商户接收后台通知后，按照参数card_status1和r1判断处理业务逻辑9、 可能出现card_status1为0，但是r1也为0的状态，此为错选导致金额丢失，属正常情况。2.8返回码列表支付结果返回码用户提示内容说明Y(成功)00000支付成功成功00001支付成功订单状态为成功。原因：用户选择面值与实际面值不符，实际面值大于订单金额。00003支付成功订单状态为成功。原因：用户选择面值与实际面值不符，实际面值小于用户选择金额。F(失败)00002支付失败！您选择的充值卡面值与实际面值不符。订单状态为失败。原因：用户选择面值与实际面值不符，实际面值小于订单金额。10014系统忙，请稍后再试金额格式异常10016该订单支付已成功，不能重复提交该订单支付已成功，不能重复提交