4.1 订单
4.1订单
4.1.1消费
【场景介绍】
消费支付，需要调用此接口，此接口为聚合模式，比如集成账户余额、账户绑卡、银行卡、微信支付等，具体支持情况需要双方业务确定，商户根据需要可以展示自己的收银台，也可以使用钱麦的收银台。一笔订单支付失败时允许多次进行重试。
【页面展示】
【调用流程】
| 【重要说明】关于1.1钱麦返回支付URL，此URL可支持自适应浏览器；即此URL在PC端浏览器打开，则展示PC收银台页面样式和PC收银台支持的支付方式；如在移动端打开，则展示移动端收银台页面样式和移动收银台支持的支付方式。请注意，商户需在相应的收银台开通对应的支付方式，方可正常展示，否则会提示支付失败。 |
|---|
【请求地址】
| 环境 | 接口服务URI |
|---|---|
| 生产环境 | /rest/v1.0/order/consume |
4.1.1.1 请求参数 （注意大小写）
| 参数名称 | 参数含义 | 数据类型 | 必填 | 参数说明 |
|---|---|---|---|---|
| requestNo | 商户请求号 | String(32) | Y | 必须在该商户编号下唯一 |
| merchantNo | 商户编号 | String(16) | Y | 商户编号 |
| merchantUserId | 商户用户标识 | String(32) | Y | 商户用户唯一编号，必须在该商户下唯一 |
| orderAmount | 订单金额 | Amount | Y | 商户订单总金额，单位：元。必须大于等于0.01，最大为18位。 |
| fundAmount | 需支付金额 | Amount | Y | 用户实际需支付金额单位：元。必须大于等于0，最大18位 |
|---|---|---|---|---|
| couponNos | 卡券列表 | List<String> | N | 1.格式：限制Json串。2.样例：[”1234567802,1234567801”]，即[”卡券A编号,卡券B编号”] |
| payTool | 指定支付方式 | Enum(20) | N | 余额支付-BALANCE（仅移动端）； 绑卡支付-BINDCARD（仅移动端）； 账户绑新卡支付-DIRECTFIRST（仅移动端）；微信App支付-WECHATAPP（非微信浏览器，仅移动端）；易宝银行卡支付-YEEPAYCASHIER；微信用户扫码支付-WECHATSCAN；网银B2C支付- SALESB2C；微信公众号支付（仅移动端，仅微信浏览器）-WECHATOFFICIAL；支付宝用户扫码支付- ALIPAYSCAN；支付宝APP支付（仅移动端）ALIPAYAPP;备注：如商户使用自己的收银台时，此项必传。 |
| bindCardId | 绑卡ID | String(16) | N | 当商户传入的payTool=BINDCARD时，此项必传 |
| merchantExpireTime | 订单有效期 | Int(5,1440) | N | 单位：分钟。微信全部:5<= date <= 120 支付宝全部：5<=date<=90,其他:5<=date<=1440，如不传，则默认最大值 |
|---|---|---|---|---|
| bankCode | 指定银行编码 | String(16) | N | 当指定支付方式传入SALESB2C时，可传入此项后，直接跳转对应网银页面。 指定银行编码，请参考附录：各银行支持列表及通道限额。 |
| merchantOrderDate | 商户下单时间 | DateTime | Y | 商户服务器记录的下单时间，格式：YYYY-MM-DD HH:mm:ss |
| trxExtraInfo | 风控参数 | String(256) | N | 建议按照附件《行业风险字段标准对接》相应行业传输所需字段。（特别重要） |
| serverCallbackUrl | 后台服务通知地址 | String(512) | Y | 服务器点对点通知地址 |
| webCallbackUrl | 前端页面通知地址 | String(512) | Y | 跳转商户页面地址 |
| mcc | 行业类别码 | String(16) | Y | 商品所属行业 |
| productCatalog | 产品类别码 | String(32) | Y | 产品类别； 如使用限定商品的营销卡券，则需在此处传入营销券适用的产品类别。 |
| productName | 商品名称 | String(50) | Y | 商品名称 |
| productDesc | 商品描述 | String(1024) | N | 当商户传入的payTool为微信支付时（WECHATAPP），此项必传；如不传则默认其内容为【消费】 |
| marketingExtraInfo | 营销补充信息 | List（String） | N | 当使用营销卡券时，则此项必填，需传入商品归属方的商编列表。 样例：{‘finalFundMerchant’:’BL12345678’} |
| Ip | 用户真实IP | String(20) | N | 微信支付时，需传入 |
| openId | 微信openid | String(128) | N | 用户在微信公众号的唯一标识。 如商户开通微信公众号，则此项必传。 |
4.1.1.2 返回参数
| 参数名称 | 参数含义 | 参数说明 |
|---|---|---|
| requestNo | 商户请求号 | 请求成功后返回，原值返回 |
| redirectUrl | 支付链接 | 请求成功后返回，返回的链接为需要进行支付的钱麦收银台地址,商户需要将浏览器跳转到此地址以完成后续支付流程。 微信用户扫码返回说明详见注释。 |
| orderAmount | 订单金额 | 请求成功后返回，商户订单总金额，单位：元 |
| fundAmount | 需支付金额 | 请求成功后返回，用户实际需支付金额 ，单位：元。 |
|---|---|---|
| status | 状态 | 请求成功后返回，未支付-UNPAY，支付成功-SUCCESS |
| code | 返回码 | 请参考附录：返回码列表 |
| message | 返回消息 | 返回码的详细说明 |
| 重要说明： 各端支持的支付方式列表可参见下表。其中，前置条件必须是商户需要完成入网开通对应的支付方式。 |
|---|
| 支持的支付方式 | PC端收银台 | PC端指定支付方式 | 移动端收银台 | 移动端指定支付方式 |
|---|---|---|---|---|
| 余额支付-BALANCE | √ | X | √ | √ |
| 绑卡支付-BINDCARD | √ | X | √ | √ |
| 账户绑新卡支付-DIRECTFIRST | √ | X | √ | √ |
| 微信App支付-WECHATAPP（非微信浏览器） | X | X | √ | √ |
| 微信用户扫码支付-WECHATSCAN | √ | X | √ | √ |
| 易宝银行卡支付-YEEPAYCASHIER | √ | √ | √ | √ |
| 网银B2C- SALESB2C | √ | √ | X | X |
| WECHATOFFICIAL-微信公众号支付（仅微信浏览器） | X | X | √ | √ |
| ALIPAYSCAN-支付宝用户扫码支付 | √ | √ | √ | √ |
| ALIPAYAPP-支付宝APP支付 | X | X | √ | √ |
微信用户扫码和支付宝用户扫码返回说明
1、前置条件，商户使用指定支付方式，默认返回二维码字符流。
2、返回的字符串转图片示列如下： import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.ByteArrayInputStream;
import java.io.File;
public class HexImage {
public static void main(String[] args) throws Exception
{
\/\/返回的图像参数HexImage
String hexImageString = "89504E470D0A1A0A0000000D494844520000008B0000008B0802000000DE7BFDA8000003A34944415478DAEDDB5172E3300C0451DFFFD2C90D1212D343CA76EB335B892D3E950062B8AF1FAF675F2F97E03D845ED9F5D7072CFC56F8597FFCC1E1A22C7CD5ADAF91ACAA420A29C40ACDEE84FAAD2DCEDE5ACFBE73697D145248A192D06CB1F08AD223A7169DAA4C0A29A4D09B0ACD6AC356434F2DF1ECF1A29E60851452E84D85C2DE9ADA9FCF163DACAF0A29A4D0938566AF7BAA19A5C6A3E16CB7570EAF4D7D1452E8EB857A6FF06FFEC983123C7FA2D0B70A610753B2D07A769357B2283C7AFFE7AC8F420A299409E1494F1848F7DEF2F8B3D84BCB145248215028DC0FCF4A0235270D2B1C3EB608976EB5DB5648218520A1B003A6E2F0D9E833CCA27A33D9F53FA890420AB142784B4D0D1766A585EAA4F1C76B3E39554821854642D4AE1E5FFDD9425C8973A889F0F6D4472185145A10C253136A8240F5D6BDA96858C2155248A1EB4207F6D5618DC14329AAD884555921851402854EA641F82C005F6B7CDE3AABDC0A29A4504308DF69F79ADADE899CF0D1A1F6150A29A41028742035C10B1B5E90A8790A02A390420AB14278204DDDD2439E8FB0D4256DB7420A29C40A9D5C507C28105E781286D4338514520811DA6A10F1E5A32216AA6F0E03A7305E52482185AA42D430747603781DC2C7ACF87E0038A7A090420A8DD2073CBC098BCD2CCEE9CD40A9EFB39A822BA490429050AF0EE143D5A705ED611DBADF6D2BA4D0470BCD12DC030DF495B34707BED8FA43A990420A5D143A19E784A93CD5251F2899641D52482185B2FF9DB265964C0FC731762FEE0AFF89AC430A29A4D082D0AC893C705CA61787F746C3D47756482185AA42D43B9DDAC3E3397478E8A7775FDBF990420A293412A2660AD451186A578F5726BC6829A490420D21BC89C4479FB366FD64650A3D80D9B6420A2994CD14A836B7F4BEDE5D35FC8450290E5748218510A1709470A0F19D2D28D5FD5FD90F28A49042A0D0CC039F3BE035264CF70F94D57F3F542185142A09853D289B91806173AF110F6BF0EA6C5B218514CA847A1D305EBD66490FD51C537F79BB0E29A4904223A1596613DEED81B9E4C9DA493D4C0A29A4504388BAF0C122BEF3A7140FCC381452482150087F87E2DBFB93F17C383566E32585145288153A3046A4429730C5A196B8FD3428A4904225A1DEFEFC4A271D8652D4486230A0514821853E40887ADD9F1CE0F6C6280A29A4D05B0885B7DD1B37CCEE8BFAD0C12228A4904225A1DE819EF0DC4CD2B956EF8B9AB72AA4904255A1D2C678DCD48665A377E827DC065C4BF01452E85B85BC1E7B29F4F4EB1762045A137848CC7F0000000049454E44AE426082";
\/\/转成image
byte[] b = hex2byte(hexImageString);
ByteArrayInputStream in = new ByteArrayInputStream(b);
BufferedImage image = ImageIO.read(in);
\/\/输出
ImageIO.write(image,"jpg",new File("\/Users\/xp-od-m-2596\/Downloads\/im.jpg"));
}
public static byte[] hex2byte(String s) {
byte[] src = s.toLowerCase().getBytes();
byte[] ret = new byte[src.length \/ 2];
for (int i = 0; i < src.length; i += 2) {
byte hi = src[i];
byte low = src[i + 1];
hi = (byte) ((hi >= 'a' && hi <= 'f') ? 0x0a + (hi - 'a')
: hi - '0');
low = (byte) ((low >= 'a' && low <= 'f') ? 0x0a + (low - 'a')
: low - '0');
ret[i \/ 2] = (byte) (hi << 4 | low);
}
return ret;
}
}
微信公众号接入说明
- 对接公众号支付需提供正确的 appid,必须为已通过认证的服务号 appid(以 wx 开头)。如需修改，请联系钱麦客户经理。
- 对接公众号支付需提供正确的支付授权目录,即用户点击“去支付”时跳转的 url。最多可同时配置 3 个支付授权目录,可修改。如需修改,请联系易宝客户经理。
- 使用指定支付方式时，微信公众号支付默认返回支付链接URL。可支持返回JSPAPI字符串，如有需要请联系钱麦客户经理。
- 指定支付方式时，返回的 JSAPI 样例: S{\"appId\":\"wx482956283fg02030\",\"timeStamp\":\"1461652466\",\"signType\":\"MD5\",\"p ackage\":\"prepay_id=wx201605061437864fe40ch8d50260150500\",\"nonceStr\":\"gv6IY95nt rW1Lp0\",\"paySign\":\"1ABSIEPE88F6R814C93312C2EC0B432F\"}
4.1.1.3主动通知：
通知方式：将参数通知到请求时传入的serverCallbackUrl。
通知机制：仅异步通知一次，如通知失败，则每3分钟补偿通知1次，共通知3次。
通知参数：同4.1.2.2订单查询的返回参数。
4.1.2订单查询（消费\/充值）
【场景介绍】
可通过商户消费\/充值请求号查询支付订单的状态，常用于订单支付状态的同步。
调用时尽量控制查询频次，如果遇到需要做高频次的查询需求，未及时通知技术对接负责人，设置过高的查询频率，可能会触发易宝接口安全保护拦截机制
【请求地址】
| 环境 | 接口服务URI |
|---|---|
生产环境: /rest/v1.0/order/query`` |
| 环境 | 接口服务URI |
|---|---|
| 生产环境 | /rest/v1.0/order/query`` |
4.1.2.1请求参数：
| 参数名称 | 参数含义 | 数据类型 | 必填 | 参数说明 |
|---|---|---|---|---|
| trxRequestNo | 请求号 | String(32) | Y | 原商户消费\/充值请求号 |
| merchantNo | 商户编号 | String(16) | Y | 商户编号 |
4.1.2.2返回参数：
| 参数名称 | 参数定义 | 参数说明 | |
|---|---|---|---|
| merchantUserId | 商户用户标识 | 商户用户唯一编号 | |
| orderAmount | 订单金额 | 商户订单总金额单位：元。 | |
| fundAmount | 需支付金额 | 用户实际需支付金额单位：元。 | |
| paidAmount | 已付金额 | 用户已支付金额。单位：元。 | |
| status | 订单状态 | 订单状态：未支付-UNPAY支付成功-SUCCESS处理中-PROCESS | |
| payTool | 支付方式 | 余额支付-BALANCE，绑卡支付-BINDCARD，账户绑新卡支付-DIRECTFIRST；微信APP支付-WECHATAPP（非微信浏览器）；微信用户扫码支付-WECHATSCAN；易宝银行卡支付-YEEPAYCASHIER；网银B2C-SALESB2C；网银B2B-SALESB2B；WECHATOFFICIAL-微信公众号支付（仅移动端，仅微信浏览器）；ALIPAYSCAN-支付宝用户扫码支付；ALIPAYAPP-支付宝APP支付（仅移动端） \ | ； |
| cardLast | 卡号后四位 | 1.用户支付银行卡卡号后四位；2.当payTool=BINDCARD\/DIRECTFIRST\/YEEPAYCASHIER时，返回此项。 | |
| cardType | 银行卡类别 | 1.用户支付银行卡的类别；2.当payTool=BINDCARD\/DIRECTFIRST\/YEEPAYCASHIER时，返回此项；3.DEBIT-储蓄卡；CREDIT-信用卡。 | |
| bankCode | 银行编码 | 1.用户支付银行卡的银行编码，请参考附录：银行编码表。2.当payTool=BINDCARD\/DIRECTFIRST\/YEEPAYCASHIER时，返回此项 |
| fee | 该笔交易的商户手续费 | |
|---|---|---|
| couponInfo | 营销信息 | 带营销券的订单会返回券的信息，详见下文注释。 |
| code | 返回码 | 请参考附录：返回码列表 |
| message | 返回消息 | 返回码的详细说明 |
营销信息注释说明：
1、格式：Json串。
2、示例返回信息如下：
“couponInfo” : [ {
"couponNo" : "AMCRP20160830150622292LtgwPWN",
"amount" : "5.00",
"status" : "SUCCESS"
}, {
"couponNo" : "AMCRP20160830151402531QG8GuWv",
"amount" : "0.02",
"status" : "REFUNDED"
} ]
即
“营销信息” : [ {
"卡券编号" : "AMCRP20160830150622292LtgwPWN",
"面值" : "5.00",
"状态" : "SUCCESS"
}, {
"卡券编号" : "AMCRP20160830151402531QG8GuWv",
"面值" : "0.02",
"状态" : "REFUNDED"
} ]
3、状态：处理中-PROCESS，销券成功-SUCCESS，销券失败-FAILURE，已退券-REFUNDED，已撤销-CANCELE。
4、状态说明：
处理中：该券已被支付订单占用。
销券成功：券已使用。
销券失败：销券未成功。
已退券：退款时请求退券，且已退成功。
已撤销：用户一直未付款，当订单超过有效期后，券变为已撤销。该券仍可继续使用。
4.1.3退款
【场景介绍】
商户因业务原因需要退款时，可通过成功交易的商户消费请求号号进行退款 ，支持部分退款；多次退款订单金额不能超过原订单总金额。
请求地址：
| 环境 | 接口服务URI |
|---|---|
| 生产环境 | /rest/v1.0/refund/refund |
4.1.3.1请求参数：
| 参数名称 | 参数含义 | 数据类型 | 必填 | 参数说明 |
|---|---|---|---|---|
| requestNo | 商户请求号 | String(32) | Y | 商户退款请求号号；必须在该商户编号下唯一 |
| merchantNo | 商户编号 | String(16) | Y | 商户编号 |
| trxRequestNo | 商户消费请求号 | String(32) | Y | 将被退款的原已交易成功的商户消费请求号 |
| refundAmount | 退款金额 | Amount | Y | 退款金额；单位：元；必须大于等于0.01，最大18位， 退款金额需小于等于消费订单的需支付金额。 |
| couponNos | 指定退券 | List(string) | N | 需要退的卡券编号1、格式：限制Json串；2、样例：[”1234567802,1234567801”]，即[”卡券A编号,卡券B编号”]，重要说明：创建活动时需勾选是否退券功能。 |
| serverCallbackUrl | 后台服务通知地址 | String(512) | N | 服务器点对点通知地址 |
|---|---|---|---|---|
| webCallbackUrl | 前端页面通知地址 | String(512) | N | 跳转商户页面地址 |
4.1.3.2返回参数：
| 参数名称 | 参数含义 | 参数说明 |
|---|---|---|
| refundAmount | 退款金额 | 请求成功后返回，此次的退款金额 |
| refundWay | 退款方式 | 请求成功后返回：原路退回-OLDWAY |
| status | ||
| 退款状态 | ||
| 请求成功后返回：退款失败-FAILURE，退款成功-SUCCESS | ||
| code | ||
| 返回码 | ||
| 请参考附录：返回码列表 | ||
| message | 返回消息 | 返回码的详细说明 |
4.1.4退款查询
【场景介绍】
可通过商户退款请求号，查询退款订单相关信息。
【请求地址】
| 环境 | 接口服务URI |
|---|---|
| 生产环境 | /rest/v1.0/refund/query |
4.1.4.1请求参数：
| 参数名称 | 参数定义 | 数据类型 | 是否必传 | 参数说明 |
|---|---|---|---|---|
| merchantNo | 商户编号 | String(16) | Y | 商户编号 |
| trxRequestNo | 商户消费请求号 | String(32) | Y | 商户退款订单对应的原消费请求号 |
| refundRequestNo | 商户退款请求号 | String(32) | N | 如传入，则查询的是此退款订单；如不传，则查询的是原消费订单的全部退款订单 |
4.1.4.2返回参数：
| 参数名称 | 参数定义 | 参数说明 |
|---|---|---|
| refundOrderList | 退款订单详情List<QueryRefundOrderDTO> | 如refundRequestNo不传，则返回原消费订单的全部退款订单列表；详见下文注解。 |
| code | 返回码 | 请参考附录：返回码列表 |
| message | 返回信息 | 返回码的详细说明 |
refundOrderList退款订单详情注解：
1、格式：Json串。
2、举例：
{“message”:”成功”,”refundOrderList”:[{"message":"成功","orderAmount":"0.01","requestNo":"1111111","code":"1","orderStatus":"SUCCESS"}],"code":"1"}。即{“此查询请求”:”成功","退款订单详情":[{"退款请求A":"成功","退款金额":"0.01","商户退款请求号":"1111111","返回码":"1","退款状态":"SUCCESS"}{"退款请求B":"成功","退款金额":"0.01","商户退款请求号":"1111112","返回码":"1","退款状态":"SUCCESS"}],"返回码":"1"}。3、退款状态：INIT-初始化、SUCCESS-退款成功、FAILURE-退款失败。
4.1.5分账
【场景介绍】
一笔订单支付成功后，对该订单进行分账，一笔支付订单，支持多次分账，每次分账需要生成不同的分账请求订单号，分账结果异步通知给商户。
【调用流程】
【请求地址】
| 环境 | 接口服务URI |
|---|---|
| 生产环境 | /rest/v1.0/divide/divide |
4.1.5.1请求参数：
| 参数名称 | 参数含义 | 数据类型 | 必填 | 参数说明 |
|---|---|---|---|---|
| requestNo | 商户请求号 | String（32） | Y | 商户分账请求号；必须在该商户编号下唯一 |
| merchantNo | 商户编号 | String（16） | Y | 商户编号 |
| serverCallbackUrl | 后台服务通知地址 | String（512） | Y | 分账之后回调点对点通知商户的地址 |
| divideDetail | 分账详情 | String（256） | Y | 格式详见下文的【divideDetail详解】。 |
| trxRequestNo | 商户消费请求号 | String（32） | Y | 原交易成功的商户消费请求号 |
【重要】divideDetail 详解:
当订单按比例分账时,格式:1001246518012345:0.4|10012465181123456:0.3
当订单按金额分账时,格式:1001246518012345:AMOUNT13.25|1001246518112345:AMOUNT20;该种方式的分账金额最多精确到小数点后两位。
分账金额的计算:A商户编号:0.4|B商户编号:0.055:金额计算:如订单金额为100,费率为1%,则分给A的金额=(100-100_1%)_0.4 = 39.6; 分给 B 的金额=(100-100_1%)_0.055 = 5.44【5.445 为 5.44 元】。
分账按固定金额分账是两位小数。
如果用户使用分账方A的无资金营销劵，则第一次给A的分账金额必须大于等于营销劵的金额。
4.1.5.2.返回参数：
| 参数名称 | 参数含义 | 参数说明 |
|---|---|---|
| code | 返回码 | 请参考附录：返回码列表 |
| message | 返回消息 | 返回码的详细说明 |
4.1.6分账查询
【场景介绍】
可通过分账请求订单号查询分账的状态。
【请求地址】
| 环境 | 接口服务URI |
|---|---|
| 生产环境 | /rest/v1.0/divide/query |
4.1.6.1请求参数：
| 参数名称 | 参数含义 | 数据类型 | 必填 | 参数说明 |
|---|---|---|---|---|
| merchantNo | 商户编号 | String（16） | Y | 商户编号 |
| trxRequestNo | 商户消费请求号 | String（32） | Y | 商户分账订单对应的原消费请求号 |
| divideRequestNo | 商户分账请求号 | String（32） | N | 如传入，则查询的是此分账订单；如不传，则查询的是原消费订单的全部分账订单 |
4.1.6.2返回参数：
| 参数名称 | 参数含义 | 参数说明 |
|---|---|---|
| divideOrderList | 分账订单列表 | 如divideRequestNo不传，则返回原消费订单的全部分账订单列表，详见下文注释 |
| code | 返回码 | 请参考附录：返回码列表 |
| message | 返回信息 | 返回码的详细说明 |
备注：divideOrderList分账订单列表注解：
1、格式：Json串。
2、举例：
divideOrderList" : [ {
"code" : "1",
"message" : "success",
"requestNo" : "divide1472613864429",
"divideStatus" : "SUCCESS",
"divideAmount" : "2.00",
"couponAmount" : "0.00",
"divideInfos" : [ {
"code" : "1",
"message" : "success",
"ledgerNo" : "B112345678901298",
"stauts" : "SUCCESS",
"amount" : "1.00",
"couponAmount" : "0.00"
}] } ]
即
“分账订单列表" : [ {
"返回码" : "1",
"返回信息" : "success",
"分账请求号" : "divide1472613864429",
"分账状态: "SUCCESS",
"分账资金金额" : "2.00",
"分账卡券金额" : "0.00",
"分账详情" : [ {
"返回码" : "1",
“返回信息" : "success",
"分账方编号" : "B112345678901298",
"状态" : "SUCCESS",
"分账资金金额" : "1.00",
"分账卡券金额" : "0.00"
}] } ]3、分账状态：
1）分账订单状态：初始化INIT、分账成功-SUCCESS、处理中-PROCESS；2）分账详情状态：初始化INIT、分账成功-SUCCESS。