营销中台

更新时间:2024-02-28 19:08:26

商家券接口

调用时序图

image.png

1.0 新增商家券

  • URL:coupon/marketing/createmchstock
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
channel String 16 Y 渠道类型WECHAT:微信 ALIPAY:支付宝 ,多个以逗号分隔
stock_type String 16 Y 券类型 NORMAL:满减券 DISCOUNT:折扣券
stock_name String 20 Y 券名称
coupon_code_mode String 16 N 券code模式
LC_MODE:系统分配券code(固定19位纯数字);
MERCHANT_API:商户发放时接口指定券code;
MERCHANT_UPLOAD:商户上传自定义code,发券时系统随机选取上传的券code。
不传默认LC_MODE
use_rule String 1024 Y 券核销相关规则
send_rule String 1024 Y 券发放相关规则
wx_custom_entrance String 1024 N 微信卡详情页面,可选择多种入口引导用户。
ali_custom_entrance String 1024 N 支付宝卡详情页面,可选择多种入口引导用户。
wx_display_pattern_info String 1024 N 微信创建批次时的样式信息。
ali_display_pattern_info String 1024 N 支付宝创建批次时的样式信息。预留字段,暂未开放
wx_extra_params String 1024 N 微信额外参数
ali_extra_params String 1024 N 支付宝额外参数,预留字段,暂未开放
upload_image String 1 N 是否上传过图片 0否 1是(传1 后面得图片地址请调用接口2.3得返回地址,该字段仅针对微信使用)
notify_url String 255 N 接收用户领券/核券通知地址
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

券使用规则use_rule字段如下

参数名称 类型 长度 必填 说明
description String 1000 N 使用须知,channel包含支付宝时必传
coupon_available_time Object 1024 Y 日期区间内可以使用优惠。
fixed_normal_coupon Object 1024 N stock_type为NORMAL时必填。
└discount_amount string 16 Y 优惠金额,单位:分。
└transaction_minimum string 16 Y 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
discount_coupon Object 1024 N stock_type为DISCOUNT时必填。
└discount_percent string 16 Y 折扣百分比,例如:86为八六折。
示例值:86
└transaction_minimum string 16 Y 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
goods_name String 12 N 商品名称,支付宝创建单品券时填入

coupon_available_time如下

参数名称 类型 长度 必填 说明
available_begin_time String 19 Y 批次开始时间,格式为yyyy-MM-dd HH:mm:ss
available_end_time String 19 Y 批次结束时间,格式为yyyy-MM-dd HH:mm:ss
available_day_after_receive string 32 N 生效后N天内有效,可配合wait_days_after_receive一同填写,也可单独填写。单独填写时,有效期内领券后立即生效,生效后x天内有效。
wait_days_after_receive string 1 N 需配合available_day_after_receive一同填写,不可单独填写。
available_week Object 1024 N 固定周期有效时间段(仅微信生效)
└week_day array[int] 16 N 可用星期数,0代表周日,1代表周一,以此类推
当填写available_day_time时,week_day必填
示例值:1, 2
└time_period string 32 N 当天可用时间段,格式:HH:mm-HH:mm,可以填写多个时间段,最多不超过2个。
示例值:08:00-12:00, 15:00-18:00

send_rule如下

参数名称 类型 长度 必填 说明
max_coupons String 11 Y 批次最大可发放个数限制
max_coupons_per_user String 11 Y 用户最大可领个数
max_coupons_by_day String 11 N 单天发放上限个数(仅微信生效)
natural_person_limit bool 1 N 不填默认否,枚举值:
true:是
false:否
注:自然人防刷即同证件号下的所有账户合并计算的限领次数(限领次数指的是参数字段“用户最大领取个数”填写的值)
示例值:false

wx_custom_entrance如下

参数名称 类型 长度 必填 说明
mini_programs_info Object 11 N 批次最大可发放个数限制
└mini_programs_appid string 16 Y 商家小程序appid
└mini_programs_path String 32 Y 商家小程序path
示例值:/path/index/index
└entrance_words String 32 Y 入口文案,字数上限为5个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:欢迎选购
└guiding_words String 32 N 小程序入口引导文案,用户自定义字段。字数上限为6个,一个中文汉字/英文字母/数字均占用一个字数。
示例值:获取更多优惠
appid String 32 N 商户公众号appid
hall_id String 32 N 填写微信支付营销馆的馆id,用户自定义字段。 营销馆需在服务商平台创建。
示例值:233455656
store_id String 32 N 填写代金券可用门店id,用户自定义字段。
示例值:233554655
code_display_mode String 32 N 枚举值:
NOT_SHOW:不展示code
BARCODE:一维码
QRCODE:二维码
示例值:BARCODE

ali_custom_entrance如下

参数名称 类型 长度 必填 说明
store_ids String 1024 N 券可使用的门店列表。多个逗号分隔(支付宝侧门店id)
real_shop_ids string 1024 N 代运营商业关系门店列表,列表中的门店id是调用接口alipay.business.relation.shop.create创建门店返回的real_shop_id,多个逗号分隔
mini_app_id String 32 N 卡包详情页可跳转的小程序appId。 限制: 该appId归属的pid必须和当前商户保持一致。 目前mini_app_id、store_ids、real_shop_ids必须三选一。
mini_app_path String 32 N 指定跳转到mini_app_id时的具体页面路径。 限制: 该小程序路径是相对路径。
offlineCodeUseGuide String 8 N 控制是否展示线下核销 true:展示线下核销 false:不展示线下核销 (字符串格式,不传默认 true)

wx_display_pattern_info如下

参数名称 类型 长度 必填 说明
merchant_logo_url String 255 N 商户logo的URL地址
1、商户logo大小需为120像素*120像素。
2、支持JPG/JPEG/PNG格式,且图片小于1M。
merchant_name String 16 N 商户名称
background_color String 32 N 券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图 https://pay.weixin.qq.com/wiki/doc/apiv3_partner/apis/chapter9_2_1.shtml#part-01
。颜色取值为颜色图中的颜色名称。
示例值:Color020
coupon_image_url String 255 N 券详情图片,850像素*350像素,且图片大小不超过2M,支持JPG/PNG格式

wx_extra_params如下
+

参数名称 类型 长度 必填 说明
use_method String 16 N 微信枚举值:
OFF_LINE:线下滴码核销,点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS:线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序appid和path)。
PAYMENT_CODE:微信支付付款码核销,点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME:用户自助核销,点击券“立即使用”跳转至用户自助操作核销界面(当前暂不支持用户自助核销)。
示例值:OFF_LINE
mini_programs_appid String 19 N 小程序appid
示例值:wx23232232323
mini_programs_path String 13 N 小程序path
示例值:/path/index/index
notify_appid string 32 N 事件通知appid。用于回调通知时,计算返回操作用户的openid(诸如领券用户),支持小程序or公众号的APPID;如该字段不填写,则回调通知中涉及到用户身份信息的openid与unionid都将为空
subsidy bool 1 N 是否允许营销补贴
枚举值:
true:是
false:否
默认为false

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
stock_no String 32 N 券批次编号,result_code为01时返回

1.1 投放活动

  • URL:coupon/marketing/deliveryactivity
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
activity_type String 16 Y 活动类型枚举:
PAY:微信支付有礼,
DELIVERY:支付宝自运营活动
brand_id String 11 N 品牌id
upload_image String 1 N 是否上传过图片 0否 1是(传1 后面得图片地址请调用接口2.3得返回地址,该字段仅针对微信使用)
activity_info String 1024 Y 活动基本信息,支付宝为数组
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

支付宝活动activity_info如下,支持传数组;例:"{\"delivery_config_list\":[{\"booth_code\":\"XXX\",\"stock_no\":\"XXX\"}]}

参数名称 类型 长度 必填 说明
delivery_config_list String
Y 活动信息
delivery_merchant_infos String
N 品牌id不传时 必填,都传则品牌id生效

delivery_config_list参数

参数名称 类型 长度 必填 说明
stock_no String 32 Y 批次号
booth_code String 20 Y _展位码:booth_code表达的是具体渠道所属的展位码。例如:支付有礼 PAY_RESULT_

delivery_merchant_infos参数

参数名称 类型 长度 必填 说明
merchant_id String 16 Y 支付宝商户号
merchant_id_type String 16 Y 传固定值SMID

微信活动activity_info如下

参数名称 类型 长度 必填 说明
activity_base_info Object 1024 N 活动基本信息
award_send_rule Object 1024 N 活动奖品发放规则

activity_base_info如下

参数名称 类型 长度 必填 说明
activity_name String 10 Y 活动名称
activity_second_title String 1024 N 活动副标题
merchant_logo_url String 255 N 商户logo,送出优惠券时展示
background_color String 8 N 代金券的背景颜色,可设置10种颜色,颜色取值请参见色卡图,默认为微信支付绿色, 颜色取值为颜色图中的颜色名称。
示例值:COLOR020
begin_time String 19 Y 活动开始时间yyyy-MM-dd HH:mm:ss
end_time String 19 Y 活动结束时间yyyy-MM-dd HH:mm:ss
available_periods Object 1024 N 可自定义活动有效时间内可用的多个时间段以及每天可用的时间点。
└available_time String 32 N 可用时间,可选择多个时间段,在可用时间段内会发放优惠券。当传入available_periods(可用时间段)后,该字段必填。yyyyMMddHHmmss-yyyyMMddHHmmss。多个逗号分隔
└available_day_time String 32 N 每日可用时间,基于“可用时间(available_time)”范围内,可再设置每日可用时间,取两者的交集时间段发券。无限制填 00:00-23:59 即可。当传入available_periods(可用时间段)后,该字段必填。多个逗号分隔
delivery_purpose String 16 Y 枚举值:
OFF_LINE_PAY:拉用户回店消费
JUMP_MINI_APP:引导用户前往小程序消费
示例值:OFF_LINE_PAY
mini_programs_appid String 32 N 商家小程序appid,投放目的为JUMP_MINI_APP时必填。
示例值:wx23232232323
mini_programs_path String 127 N 商家小程序path

award_send_rule如下

参数名称 类型 长度 必填 说明
transaction_amount_minimum String 10 Y 消费金额门槛,单位:分。
注:该字段金额指订单金额
示例值:100
send_content String 1024 Y 发放内容,可选单张券或礼包,选礼包时奖品限定3-5个。
枚举值:
SINGLE_COUPON:单张券
GIFT_PACKAGE:礼包
示例值:SINGLE_COUPON
award_type String 255 Y 奖品类型,暂时只支持商家券。枚举值:
BUSIFAVOR:商家券
示例值:BUSIFAVOR
award_list Array - Y 奖品基本信息列表,当send_content(发放内容)选择GIFT_PACKAGE(礼包)时,奖品信息必须是3-5个,与send_content(发放内容)中礼包的个数保持一致。
条目个数限制:[1,5]
注:创建活动时,作为奖品的券包,券包里的券核销时间需要一致
└stock_no String 32 Y 批次id
└original_image_url String 255 Y 奖品原始图(大图)
└thumbnail_url String 255 N 奖品缩略图(小图)

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
activity_no String 32 N 活动编号,result_code为01时返回

1.2 停止活动

  • URL:coupon/open/activitystop
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
inst_no String 8 Y 机构编号,扫呗分配
activity_no String 32 Y 活动编号 activity_no和acceptance_no二选一,都传时以activity_no为准
acceptance_no String 11 N 受理流水号 activity_no和acceptance_no二选一,都传时以activity_no为准
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换


返回参数

result String 2 Y 返回json字符串

result类型

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号

1.3 微信小程序插件发券

  • URL:coupon/marketing/minisend
  • Method: POST
  • ContentType: application/json

注:支付宝的请使用官方小程序插件
请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
inst_no String 8 Y 机构编号,扫呗分配
merchant_no String 15 Y 扫呗商户号
pay_type String 10 Y 发券类型 010微信
stock_params String 1024 Y 发券批次数组
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换


stock_params如下

参数名称 类型 长度 必填 说明
out_coupon_no String 32 N 外部券码code。当券批次券code模式为”商户发放时接口指定券code“时传
out_request_no String 32 Y 发券凭证,可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,需在单个批次单个用户下确保唯一性
stock_no String 32 Y 券批次编号


返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
send_coupon_params String 32 N 发券参数
sign String 32 N 签名
send_coupon_merchant String 32 N 发券商户号 示例值:10016226


注意:

请求完这个接口得到的返回参数直接去调微信小程序发券插件API,参数值不用做变化

https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter9_3_1.shtml

1.4 查询用户已领取的可用的券

  • 返回的券只包含当前时间(发起查询的时间)可用的券。

  • URL:coupon/open/queryusercoupons

  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 10 Y 用户标识类型
PHONE:手机号
OPENID:微信open_id
USERID:支付宝user_id
UNIONID:微信union_id
PAYCODE:付款码
CARDNO:会员卡号
user_id String 32 Y 用户标识。
user_id_type为PHONE时传手机号
user_id_type为OPENID时传微信open_id
user_id_type为USERID时传支付宝user_id
user_id_type为UNIONID时传微信union_id
user_id_type为PAYCODE时传微信/支付宝付款码
user_id_type为CARDNO时传会员卡号
channel_type String 10 N 通道类型 LC:利楚 WECHAT:微信 ALIPAY:支付宝 MALLCOO:猫酷
amount String 11 N 参与优惠金额(分),该字段有值时返回满足该用券金额门槛的可用券
coupon_type String 10 N 券类型 0:满减券 1:折扣券 2.兑换 3.停车 4.团购 5:优惠券。4、5只在channel_type为MALLCOO时存在
,多个类型,号分割
start_time String 19 N 券有效期开始时间 yyyy-MM-dd HH:mm:ss,channel_type为LC、WECHAT、ALIPAY时该字段生效
end_time String 19 N 券有效期结束时间 yyyy-MM-dd HH:mm:ss,channel_type为LC、WECHAT、ALIPAY时该字段生效
page_size String 11 N 页面大小,最大20。不传默认每页返回10条数据
previou_id String 11 N 上一页最后一条数据id,不填查询第一页
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_info String - N 会员信息,JSON字符串,需要转义
coupons String - N 可用券列表,JSON字符串,需要转义
sence_no String 32 N 请求支付宝流水号,result_code为01时返回

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
card_no String 32 Y 卡号

coupons字段如下

参数名称 类型 长度 必填 说明
id String 11 Y id
channel_type String 10 Y 通道类型 LC:利楚 WECHAT:微信
ALIPAY:支付宝
MALLCOO:猫酷
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
apply_scope String 1 Y 适用范围 0:全场 1:单品
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:停车券 4:团购券 5:优惠券。4、5只在channel_type为MALLCOO时存在
get_time String 19 N 领取时间 yyyy-MM-dd HH:mm:ss
start_time String 19 Y 券有效期开始时间 yyyy-MM-dd HH:mm:ss
end_time String 19 Y 券有效期结束时间 yyyy-MM-dd HH:mm:ss
discount_amt String 11 N 优惠金额(分),根据amount计算出来的优惠金额,amount有值时返回
actual_amt String 11 N 实付金额(分)(优惠后金额),amount有值时返回
discount_rule Object Y 优惠规则
use_rule Object Y 券使用规则

优惠规则discount_rule字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 消费门槛(分),0代表没门槛
discount_amt String 8 N 优惠金额(分)。coupon_type为0或2时必传
rebate String 3 N 折扣,1~100的整数(eg:70表示七折)。coupon_type为1时必传
discount_top String 8 Y 单笔优惠封顶金额,0代表不封顶
park_special_tag String 1 N 停车券特殊优惠标记 0.普通优惠 1.特殊优惠 coupon_type为3时必传
deduction_amt String 11 N 抵用金额(分) coupon_type为3时选传
deduction_time String 11 N 抵消时常(分钟) coupon_type为3时选传

券使用规则use_rule字段如下

参数名称 类型 长度 必填 说明
use_time_type String 1 Y 券可用时间类型 0:用户领券后N天内可用 1:固定可用时间段 2:规则日期可用
limit_days String 4 N 用户领券多少天内有效。use_time_type为0时必传
wait_days String 4 N 领取后N天开始生效,最大值90。use_time_type为0时非必传
use_start_time String 19 N 固定可用时间段开始时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
use_end_time String 19 N 固定可用时间段结束时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
days_period String 13 N 规则日期可用星期,1代表周日,2代表周一,以此类推,多个,分隔。示例值:1,2。use_time_type为2时传,为空代表没有可用时间
time_period String 11 N 规则日期可用时间段,格式:HH:mm-HH:mm。use_time_type为2时选传,days_period不为空时和days_period搭配使用,为空代表不限制。days_period为空该字段无意义。
use_note String 144 Y 使用需知

1.5 查询用户已领取的可用的券最优解

  • URL:coupon/open/querybestcoupons
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 10 Y 用户标识类型
PHONE:手机号
OPENID:微信open_id
USERID:支付宝user_id
UNIONID:微信union_id
PAYCODE:付款码
CARDNO:会员卡号
user_id String 32 Y 用户标识。
user_id_type为PHONE时传手机号
user_id_type为OPENID时传微信open_id
user_id_type为USERID时传支付宝user_id
user_id_type为UNIONID时传微信union_id
user_id_type为PAYCODE时传微信/支付宝付款码
user_id_type为CARDNO时传会员卡号
amount String 11 Y 参与优惠金额(分)
freeze_flag String 1 N 是否需要同时冻结查出的最优券 0:不冻结 1:冻结 ,该字段为空不冻结
freeze_time String 11 N 冻结时长(秒)。freeze_flag为1时选填,不可小于300秒,不传默认冻结2小时
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_info String - N 会员信息,JSON字符串,需要转义
coupon String - N 券信息,JSON字符串,需要转义
, result_code为01时返回
sence_no String 32 N 请求支付宝流水号,result_code为01时返回

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
card_no String 32 Y 卡号

coupon字段如下

参数名称 类型 长度 必填 说明
coupon_credential String 128 N 优惠券凭据,调用支付接口时用,freeze_flag为1时返回
channel_type String 10 Y 通道类型 LC:利楚 WECHAT:微信
ALIPAY:支付宝
MALLCOO:猫酷
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
apply_scope String 1 Y 适用范围 0:全场 1:单品
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:停车券 4:团购券 5:优惠券。4、5只在channel_type为MALLCOO时存在
get_time String 19 N 领取时间 yyyy-MM-dd HH:mm:ss
start_time String 19 Y 券有效期开始时间 yyyy-MM-dd HH:mm:ss
end_time String 19 Y 券有效期结束时间 yyyy-MM-dd HH:mm:ss
discount_amt String 11 Y 优惠金额(分),根据amount计算出来的优惠金额
actual_amt String 11 Y 实付金额(分)(优惠后金额)
discount_rule Object Y 优惠规则
use_rule Object Y 券使用规则

优惠规则discount_rule字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 消费门槛(分),0代表没门槛
discount_amt String 8 N 优惠金额(分)。coupon_type为0时必传
rebate String 3 N 折扣,1~100的整数(eg:70表示七折)。coupon_type为1时必传
discount_top String 8 Y 单笔优惠封顶金额,0代表不封顶
deduction_amt String 11 N 抵用金额(分) coupon_type为3时选传
deduction_time String 11 N 抵消时常(分钟) coupon_type为3时选传

券使用规则use_rule字段如下

参数名称 类型 长度 必填 说明
use_time_type String 1 Y 券可用时间类型 0:用户领券后N天内可用 1:固定可用时间段 2:规则日期可用
limit_days String 4 N 用户领券多少天内有效。use_time_type为0时必传
wait_days String 4 N 领取后N天开始生效,最大值90。use_time_type为0时非必传
use_start_time String 19 N 固定可用时间段开始时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
use_end_time String 19 N 固定可用时间段结束时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
days_period String 13 N 规则日期可用星期,1代表周日,2代表周一,以此类推,多个,分隔。示例值:1,2。use_time_type为2时传,为空代表没有可用时间
time_period String 11 N 规则日期可用时间段,格式:HH:mm-HH:mm。use_time_type为2时选传,days_period不为空时和days_period搭配使用,为空代表不限制。days_period为空该字段无意义。
use_note String 144 Y 使用需知

1.6 查询单个券信息

  • URL:coupon/open/getcoupon
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
支持100、110、200
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 O 券码,版本号110选填,其他版本必填
merchant_trade_no String 64 O 商户订单号,商户测保证唯一(与coupon_no字段二选一) 版本号110选填,其他版本不填
channel_type String 3 O 券通道类型:如
LC:利楚券
MT:美团券
DY:抖音券;
版本号200时必填
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_info String - N 会员信息,JSON字符串,需要转义
coupon String - N 券信息,JSON字符串,需要转义
, result_code为01时返回,110版本返回集合

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
card_no String 32 Y 卡号

coupon字段如下

参数名称 类型 长度 必填 说明
channel_type String 10 Y 通道类型 LC:利楚 WECHAT:微信 ALIPAY:支付宝 MALLCOO:猫酷
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
apply_scope String 1 Y 适用范围 0:全场 1:单品
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:停车券 4:团购券 5:优惠券。4、5只在channel_type为MALLCOO时存在
activity_no String 32 N 所属活动编号
stock_no String 32 N 所属券批次编号
get_time String 19 Y 领取时间 yyyy-MM-dd HH:mm:ss
use_status String 1 Y 状态 1.可用 2.已失效 3.已核销 4.已过期
out_trade_no String 32 N 核销关联订单号,use_status为2时返回
use_time String 19 N 核销时间 use_status为2时返回
discount_rule Object Y 优惠规则
use_rule Object Y 券使用规则

优惠规则discount_rule字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 消费门槛(分),0代表没门槛
discount_amt String 8 N 优惠金额(分)。coupon_type为0时必传
rebate String 3 N 折扣,1~100的整数(eg:70表示七折)。coupon_type为1时必传
discount_top String 8 Y 单笔优惠封顶金额,0代表不封顶
park_special_tag String 1 N 停车券特殊优惠标记 0.普通优惠 1.特殊优惠 coupon_type为3时必传
deduction_amt String 11 N 抵用金额(分) coupon_type为3时选传
deduction_time String 11 N 抵消时常(分钟) coupon_type为3时选传

券使用规则use_rule字段如下

参数名称 类型 长度 必填 说明
use_time_type String 1 Y 券可用时间类型 0:用户领券后N天内可用 1:固定可用时间段 2:规则日期可用
limit_days String 4 N 用户领券多少天内有效。use_time_type为0时必传
wait_days String 4 N 领取后N天开始生效,最大值90。use_time_type为0时非必传
use_start_time String 19 N 固定可用时间段开始时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
use_end_time String 19 N 固定可用时间段结束时间 yyyy-MM-dd HH:mm:ss。use_time_type为1时必传
days_period String 13 N 规则日期可用星期,1代表周日,2代表周一,以此类推,多个,分隔。示例值:1,2。use_time_type为2时传,为空代表没有可用时间
time_period String 11 N 规则日期可用时间段,格式:HH:mm-HH:mm。use_time_type为2时选传,days_period不为空时和days_period搭配使用,为空代表不限制。days_period为空该字段无意义。
use_note String 144 Y 使用需知

1.7 券冻结

  • URL:coupon/open/freeze
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 Y 券码
freeze_time String 11 N 冻结时长(秒),不可小于300秒,不传默认冻结2小时
goods_ids String - N 商品编号,多个商品编号,分割
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_credential String 128 N 优惠券凭据,调用支付接口时用
verify_warn_msg String 32 N 核销预警信息,result_code为01时若有值,表示用户用券次数达到了设置的优惠示警值

1.8 券解冻

  • URL:coupon/open/unfreeze
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 Y 券码
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号

1.9 券核销

  • URL:coupon/open/use
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100;
支持100,200
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 Y 券码
order_amt String 11 N 订单金额(优惠前的金额,单位分),券通道为支付宝时必传
channel_type String 3 O 券通道类型:如
LC:利楚券
MT:美团券
DY:抖音券;
版本号200时必填
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
verify_warn_msg String 32 N 核销预警信息,result_code为01时若有值,表示用户用券次数达到了设置的优惠示警值
channel_type String 3 Y 券通道类型:如
LC:利楚券
MT:美团券
DY:抖音券;
版本号200时返回
tail_amount String - N 尾款金额,等于订单总金额减去券抵扣金额;
版本号200时返回

1.10 券核销撤销

  • URL:coupon/open/canceluse
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100;
支持100,110,200
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 O 券码110版本选填,其他版本必填
merchant_trade_no String 64 O 商户订单号,商户测保证唯一(与coupon_no字段二选一)110版本支持,其他版本不填
channel_type String 3 O 券通道类型:如
LC:利楚券
MT:美团券
DY:抖音券;
版本号200必填
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
channel_type String 3 O 券通道类型:如
LC:利楚券
MT:美团券
DY:抖音券;200版本返回

1.11 券失效

  • URL:coupon/open/deactivate
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupon_no String 32 Y 券码
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号

1.12 领券/券核销/券核销撤销通知

  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 N 终端号
event_type String 15 Y 事件类型 USED:核销券 SEND:领券 CANCEL:核销撤销
activity_no String 32 Y 活动编号
stock_no String 32 Y 券批次编号
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:团购券 4:停车券 5:优惠券
phone String 20 Y 手机号
open_id String 32 Y 用户标识(微信openid,支付宝userid)
union_id String 32 N 微信开发平台UnionID,event_type为COUPON.SEND时返回
out_trade_no String 32 N 关联交易流水号,
event_type为COUPON.USE时代表支付交易订单号,
event_type为COUPON.CANCEL时代表退款/撤销交易流水号,
time String 19 Y 时间 yyyy-MM-dd HH:mm:ss,
event_type为COUPON.SEND时代表领取时间,
event_type为COUPON.USE时代表核销时间,
event_type为COUPON.CANCEL时代表核销撤销时间,
verify_merchant_no String 15 N 核券/撤销券商户号(该商户号不一定为发券商户号),event_type为USED或CANCEL时返回
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败
return_msg String 128 Y 返回信息提示

1.13 通过用户标识查询用户会员信息

  • URL:coupon/open/querymemberinfo
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 10 Y 用户标识类型
PHONE:手机号
OPENID:微信open_id
USERID:支付宝user_id
UNIONID:微信union_id
CARDNO:会员卡号
user_id String 32 Y 用户标识。
user_id_type为PHONE时传手机号
user_id_type为OPENID时传微信open_id
user_id_type为USERID时传支付宝user_id
user_id_type为UNIONID时传微信union_id
user_id_type为CARDNO时传会员卡号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_info String - N 会员信息,result_code为01时有值,JSON字符串,需要转义

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
card_no String 32 Y 卡号
register_time String 32 Y 注册时间 yyyy-MM-dd HH:mm:ss
balance String 11 Y 会员余额(分)
score String 11 Y 会员积分
real_name String 9 N 真实姓名
level_desc String 32 N 会员等级中文描述

1.14 微信关联订单信息

  • 将有效态(未核销)的商家券与订单信息关联,用于后续参返佣的统计。
  • 注意:订单交易时间和券核销时间间隔不可超过2分钟。

  • URL:coupon/open/associate

  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
inst_no String 8 Y 机构号
merchant_no String 15 Y 扫呗商户号
coupon_no String 32 Y 券码
out_trade_no String 128 Y 关联的商户订单号。
若商户支付是通过调用扫呗的支付接口处理的,该字段传支付接口的out_trade_no即可;
若商户支付不是通过扫呗的支付接口处理的,该字段传微信支付下单时的商户订单号。
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号

1.15 取消关联订单信息

  • URL:coupon/open/disassociate
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
inst_no String 8 Y 机构号
merchant_no String 15 Y 扫呗商户号
coupon_no String 32 Y 券码
out_trade_no String 128 Y 关联的商户订单号。
若商户支付是通过调用扫呗的支付接口处理的,该字段传支付接口的out_trade_no即可;
若商户支付不是通过扫呗的支付接口处理的,该字段传微信支付下单时的商户订单号。
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号

支付券接口

调用时序图

image.png

2.0 新增支付券

  • URL:coupon/marketing/createpaystock
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
channel String 16 Y 渠道类型WECHAT:微信 ALIPAY:支付宝 ,多个以逗号分隔
stock_type String 16 Y 批次类型,仅支持:
NORMAL:固定面额满减券批次
stock_name String 20 Y 券名称
available_begin_time String 19 Y 可用时间-开始时间yyyy-MM-dd HH:mm:ss
available_end_time String 19 Y 可用时间-结束时间yyyy-MM-dd HH:mm:ss
stock_use_rule String 1024 Y 发放规则
pattern_info String 1024 Y 样式设置
coupon_use_rule String 1024 Y 核销规则
budget_info String 1024 Y 营销资金预算
notify_url String 255 N 接收用户核券通知地址
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

发放规则stock_use_rule

参数名称 类型 长度 必填 说明
max_coupons String 11 Y 最大发券数
校验规则:
1、发放总个数最少5个
2、发放总个数最多1000万个
max_amount String 11 C (微信必传,支付宝不传)最大发券预算,当营销经费no_cash选择预充值false时,激活批次时会从制券商户的余额中扣除预算,请保证账户金额充足,单位:分
max_amount需要等于coupon_amount(面额) * max_coupons(发放总上限)

校验规则:批次总预算最多1000万元 | | max_coupons_per_user | String | 16 | Y | 单个用户可领个数 |

样式设置pattern_info

参数名称 类型 长度 必填 说明
description String 2000 Y 使用说明
merchant_logo String 255 C (微信时生效)商户logo url
merchant_name String 128 N 品牌名称
background_color String 16 C (微信时生效)券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。可选枚举字段不用则不传,不可以传空值
coupon_image String 255 N 微信券详情图片 url,支付宝传resource_id
ali_coupon_image String 255 C (支付宝时生效)券详情页封面图,支付宝resource_id,resource_id调用2.3 上传营销图片获取,限制:1.指定可核销商品(available_items)时必传
ali_voucher_detail_images String 255 C (支付宝时生效)支付宝券详细图列表,支付宝resource_id,多个resource_id以逗号分隔 ,resource_id调用2.3 上传营销图片获取,限制:1.ali_coupon_image填入,该值才能填入; 2.最多3张;
customer_service_mobile String 20 C (支付宝必传)商家客服电话,会展示在支付宝卡包券详情页。

核销规则coupon_use_rule

参数名称 类型 长度 必填 说明
coupon_amount String 11 Y 面额,单位:分。
transaction_minimum String 11 Y 使用券金额门槛,单位:分。
若指定可核销商品编码,门槛则为可核销商品部分的消费金额,而不是订单的消费金额。
goods_tag array 1024 C (微信时生效)订单优惠标记,按json格式。
商户下单时需要传入相同的标记(goods_tag),用户同时符合其他规则才能享受优惠
校验规则:
1、最多允许录入50个
2、每个订单优惠标记支持字母/数字/下划线,不超过128个UTF8字符。
available_items array 1024 N (限制:
1、available_items与
unavailable_items只能二选一或者同时为空)
可核销商品编码,包含指定SKU商品编码的交易才可核销/使用代金券:活动商户在交易下单时,需传入用户购买的所有SKU商品编码,当命中代金券中设置的商品编码时可享受优惠。
校验规则:
1、单个商品编码的字符长度为【1,128】
2、条目个数限制为【1,50】
示例值:['123321','456654']
unavailable_items array 1024 N (限制:
1、available_items与
unavailable_items只能二选一或者同时为空)包含指定SKU商品编码的交易不可核销/使用代金券。
校验规则:
1、单个商品编码的字符长度为【1,128】
2、条目个数限制为【1,50】

示例值:['123321','456654'] | | ali_available_merchants | Object | 1024 | N | 优惠券可核销的直连商户PID,优惠券可核销的间连商户SMID | | └available_pids | array | 84000 | C | 优惠券可核销的直连商户PID

限制:
1、available_pids和available_smids至少二选一。 | | └available_smids | array | 84000 | C | 优惠券可核销的间连商户SMID

限制:
1、available_pids和available_smids至少二选一。 | | wx_available_merchants | array | 1024 | N | 微信可核销商户号 |

营销资金预算budget_info

参数名称 类型 长度 必填 说明
budget_type String 11 Y 营销资金预算类型
枚举值:
NO_CASH 免充值
RECHARGE 预充值
max_amount String 11 C (微信必传,支付宝不传)最大发券预算,当营销经费no_cash选择预充值false时,激活批次时会从制券商户的余额中扣除预算,请保证账户金额充足,单位:分
max_amount需要等于coupon_amount(面额) * max_coupons(发放总上限)

校验规则:批次总预算最多1000万元 | | amount | String | 16 | c | (支付宝预充值必传)营销资金预算,单位元。
总预算=优惠金额*总发券张数 | | logon_id | String | 16 | C | (支付宝预充值必传)出资的支付宝登录账号
限制:
1、登录账号和用户ID必须且只能二选一
username@gmail.com | | user_id | String | 16 | C | (支付宝预充值必传)出资的支付宝用户id
2088512417841101
限制:
1、登录账号和用户ID必须且只能二选一 |

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
stock_no String 32 N 券批次编号,result_code为01时返回

2.1 激活支付券

  • URL:coupon/marketing/publish
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
pay_type String 10 Y 支付类型 010微信 020支付宝
stock_no String 16 Y 券批次编号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
recharge_url String 32 N 预充值链接(支付宝返回)
限制:
1、有效时间3天

2.2 发放支付券

  • URL:coupon/marketing/send
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
stock_no String 16 Y 券批次编号
pay_type String 10 Y 支付类型 010微信 020支付宝
openid String 32 Y 微信用户openid,支付宝user_id账号( 单个用户 )
appid String 32 C (微信必传)公众账号ID校验规则:
1、该appid需要与接口传入中的openid有对应关系;
2、该appid需要与调用接口的商户号(即请求头中的商户号)有绑定关系,若未绑定,可参考该指引完成绑定(商家商户号与AppID账号关联管理
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
coupon_no String 32 Y 券码
receive_url String 32 N (支付宝返回)支付宝插卡包URL

2.3 上传营销图片

  • URL:coupon/marketing/uploadimage
  • Method: POST
  • ContentType: application/json


请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
type String 10 Y 类型 010微信 020支付宝
image_url String 32 Y 图片地址
image_type String 32 Y 图片类型
券详情页封面图:PROMO_VOUCHER_IMAGE
券详细图列表:PROMO_VOUCHER_DETAIL_IMAGE
推广计划图片素材:PUBLIC_UNION_CHANNEL_PIC、DELIVERY_CHANNEL_PIC
文件业务标识。

枚举值
alipay.marketing.activity.delivery.create接口中
delivery_base_info.delivery_material.delivery_single_material.delivery_image
当delivery_booth_code=PUBLIC_UNION,上传图片接口需指定file_key=PUBLIC_UNION_CHANNEL_PIC。上传图片尺寸600600,支持格式:png、jpg、jpeg、bmp,大小不超过200kb;
当delivery_booth_code=PAYMENT_RESULT,上传图片接口需指定file_key=DELIVERY_CHANNEL_PIC。上传图片尺寸600
600,支持格式:png、jpg、jpeg、bmp,大小不超过200kb。
上传图片更多要求参考文档: https://render.alipay.com/p/c/18tpirlg12e8?operateFrom=BALIPAY

alipay.marketing.activity.ordervoucher.create接口中
voucher_display_info.brand_logo字段,file_key=PROMO_BRAND_LOGO,上传图片尺寸600600,支持格式:png、jpg、jpeg、bmp,大小不超过2MB
voucher_display_info.voucher_image字段,file_key=PROMO_VOUCHER_IMAGE,上传图片尺寸670
335,支持格式:png、jpg、jpeg、bmp,大小不超过2MB(支付宝图片使用该字段) | | key_sign | String | 32 | Y | 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换 |

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
resource_id String 32 N 图片唯一资源ID

2.4 支付宝补传logo

  • URL:coupon/marketing/uploadlogo
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
logo_url String 32 Y logo图片地址
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
resource_id String 32 N 图片唯一资源ID

2.5 查询通道券批次

  • URL:coupon/marketing/querychannelstock
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
inst_no String 8 Y 机构编号,扫呗分配
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
stock_no String 32 Y 批次号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为key),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
channel_stock_list String 255 N 通道券批次数组

channel_stock_list如下

参数名称 类型 长度 必填 说明
channel_stock_id String 32 Y 上游渠道券批次id
stock_channel int 1 Y 批次通道 1.微信 2.支付宝
use_count int Y 已消耗库存
total_count int Y 总库存

会员接口

3.1 变更记录

日期 接口 内容
2022-10-20 新增接口

3.2 会员注册接口

  • 测试URL : member/terminal/registerMember
  • Method :POST

请求参数:

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,当前版本100
trace_no String 32 Y 请求流水号
custom_no String 32 O 自定义编号,需在扫呗侧配置关联,否则不能使用
版本号110时选填
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
out_member_no String 32 O 外部会员号,商户自己的会员编号,商户侧保证唯一,选其一
phone String 11 Y 手机号
nick_name String 8 N 会员昵称
sex Integer 1 N 用户性别 0未知 1.男性 2.女性
birthday String 11 N 生日yyyy-MM-dd
user_info String 32 N 身份标识,JSON数组字符串,需要转义
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

user_info字段内容:

pay_type String Y 010微信 020支付宝
appid String O 微信必传的appid
user_id String Y 微信为opneid,支付宝为user_id

返回参数:

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 N 扫呗商户号
terminal_id String 8 Y 终端号
member_no String 32 N 会员编号
member_card_no String 32 N 会员卡号
register_time String 19 Y 注册时间 yyyy-MM-dd HH:mm:ss
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

3.3 查询会员

  • URL : member/terminal/querymember
  • Method :POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
custom_no String 32 O 自定义编号,需在扫呗侧配置关联,否则不能使用
版本号110时选填
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
user_id_type String 3 Y 用户标识类型
AUTO: 自动识别
PAYCODE:付款码
PHONE:手机号
OPENID:微信open_id
USERID:支付宝user_id
UNIONID:微信union_id
CARDNO:会员卡号
MEMBERNO:会员编号
DYNAMICCODE:动态会员code
user_id String 32 Y 用户标识
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_no String 32 N 会员编号(注册会员才有此字段。注册会员:有录入手机号的会员)
member_card_no String 32 N 会员卡号(注册会员才有此字段。注册会员:有录入手机号的会员)
phone String 11 N 手机号(注册会员才有此字段。注册会员:有录入手机号的会员)
member_status String 2 N 会员状态 0:待激活 1:正常 2:停用 99:删除
nick_name String 8 N 会员昵称
sex String 1 N 用户性别 0未知 1.男性 2.女性
score String 11 N 积分
level String 11 N 会员等级
level_desc String 32 N 会员等级中文描述
balance String 11 N 会员卡余额(分)
birthday String 11 N 生日yyyy-MM-dd
register_time String 19 Y 注册时间 yyyy-MM-dd HH:mm:ss
update_time String 19 N 更新时间 yyyy-MM-dd HH:mm:ss
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

3.4 会员充值活动查询

URL:member/terminal/queryrechargeactivity
Method: POST
ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
terminal_id String 8 Y 终端号
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
recharge_type String 15 Y FIXED固定金额充值 ANY任意额度充值
amount String 11 N 充值任意金额,都优惠固定填写的金额,ANY任意额度充值有效( amount=5元时 充值100元 实际支付95元 用户会员卡到账100元 )
fixed_rule String 32 N FIXED固定金额充值规则,JSON数组字符串,最多8组
manual_switch String 1 用户手动输入充值金额开关 0.关闭 1.开启
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

fixed_rule数组字段如下

参数名称 类型 长度 必填 说明
threshold String 11 Y 充值门槛
value String 11 Y 充值赠送金额

3.5 查询用户已领取的可用的券

返回的券只包含当前时间(发起查询的时间)可用的券。
URL:member/terminal/queryusercoupons
Method: POST
ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 10 Y 用户标识类型
PHONE:手机号
CHANNEL_USER_ID:支付宝/微信用户标识
OUT_USER_ID:外部系统用户标识
user_id String 32 Y 用户标识的值
amount String 11 N 参与优惠金额(分),该字段有值时返回满足该用券金额门槛的可用券
page_size String 11 Y 页面大小,最大20。
previou_id String 11 N 上一页最后一条数据id,不填查询第一页
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换


返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
coupons String - N 可用券列表,JSON字符串,需要转义
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换


coupons字段如下

参数名称 类型 长度 必填 说明
id String 11 Y 券id,16进制加密
share_flag String 1 Y 能否与商家活动共享 0:否 1:能
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
apply_scope String 1 Y 适用范围 0:全场 1:单品
coupon_type String 1 Y 券类型 0:满减券 1:折扣券
get_time String 19 N 领取时间 yyyy-MM-dd HH:mm:ss
start_time String 19 Y 券有效期开始时间 yyyy-MM-dd HH:mm:ss
end_time String 19 Y 券有效期结束时间 yyyy-MM-dd HH:mm:ss
discount_rule Object Y 优惠规则
discount_amt String 11 N 优惠金额(分),根据amount计算出来的优惠金额,amount有值时返回
actual_amt String 11 N 实付金额(分)(优惠后金额),amount有值时返回


优惠规则discount_rule字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 消费门槛(分),0代表没门槛
discount_amt String 8 N 优惠金额(分)。coupon_type为0或2时必传
rebate String 3 N 折扣,1~100的整数(eg:70表示七折)。coupon_type为1时必传
discount_top String 8 Y 单笔优惠封顶金额,0代表不封顶

3.6 会员充值(付款码支付)

  • URL:member/terminal/rechargebarcodepay
  • Method:POST
  • ContentType: application/json
参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
pay_type String 3 Y 支付方式,010微信,020支付宝,060qq钱包,090口碑,100翼支付,140和包支付(仅限和包通道)
000 自动识别类型
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
terminal_trace String 32 Y 终端流水号,填写商户系统的订单号
terminal_time String 14 Y 终端交易时间,yyyyMMddHHmmss,全局统一时间格式
member_no String 32 Y 会员编号
total_fee String 12 Y 金额,单位分
sub_appid String 16 N 子商户绑定的公众号/小程序 appid(服务商模式)
auth_no String 128 Y 授权码,客户的付款码
sence_no String 64 N 支付宝外部业务号,查询会员使用的付款码,该字段必传,传查询会员用的trace_no
operator_id String 11 N 收银员id
order_body String 128 N 订单描述
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
result_code String 2 N 业务结果 01:成功 02:失败
pay_type String 3 Y 支付方式 010:微信 020:支付宝
trace_no String 32 Y 原请求流水号
terminal_id String 8 Y 终端号
merchant_no String 15 Y 扫呗商户号
merchant_name String 40 N 商户名称
terminal_trace String 32 Y 终端流水号,填写商户系统的订单号
terminal_time String 14 Y 终端交易时间,yyyyMMddHHmmss,全局统一时间格式
total_fee String 12 N 金额,单位分
receipt_fee String 12 N 商家应结算金额,单位分
trade_no String 32 N 会员唯一订单号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

3.7 会员余额支付

支持会员满减活动,会员券,积分同时叠加
URL:member/terminal/balancepay
Method: POST
ContentType: application/json

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
pay_type String 3 Y 支付方式 010:微信 020:支付宝
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
terminal_trace String 32 Y 终端流水号,填写商户系统的订单号
terminal_time String 14 Y 终端交易时间,yyyyMMddHHmmss,全局统一时间格式
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
member_no String 32 Y 会员编号。
total_fee String 12 Y 金额,单位分
activity_no String 32 N 会员活动编号
serial_number String 1 N 优惠规则序号,
和activity_no一起传
coupon_no String 32 N 会员券码
score String 32 N 积分
order_body String 128 N 订单描述
operator_id String 11 N 收银员id
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
result_code String 2 N 业务结果 01:成功 02:失败
pay_type String 3 N 支付方式,010微信,020支付宝,060qq钱包,090口碑,100翼支付
merchant_name String 40 N 商户名称
merchant_no String 15 N 商户号
terminal_id String 8 N 终端号
terminal_trace String 32 Y 终端流水号,填写商户系统的订单号
terminal_time String 14 Y 终端交易时间,yyyyMMddHHmmss,全局统一时间格式
total_fee String 12 N 金额,单位分
receipt_fee String 12 N 实付金额,单位分
trade_no String 32 N 唯一订单号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

##

3.8 会员订单查询

URL:member/terminal/queryorder
Method: POST
ContentType: application/json

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
pay_trace String 32 N 传入支付接口中的支付终端流水号(
terminal_trace),与pay_time同时传递
pay_time String 14 N 传入支付接口中的支付终端交易时间(
terminal_time),与pay_trace同时传递
trace_no String 32 N 请求流水号,不带“-”的uuid,商户侧需保证唯一性
trade_no String 32 N 会员唯一订单号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码:01成功 ,02失败,响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示,“支付成功”,“支付中”,“请求受限”等
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
result_code String 2 N 业务结果:01成功 ,02失败 ,03支付中。支付失败和退款成功状态均返回02,具体状态和原因会在return_msg中给出解释
pay_type String 3 Y 支付方式 010:微信 020:支付宝
merchant_name String 40 N 商户名称
merchant_no String 15 N 商户号
terminal_id String 8 N 终端号
terminal_trace String 32 N 终端流水号,商户系统的查询流水号,扫呗系统原样返回
terminal_time String 14 N 终端交易时间,yyyyMMddHHmmss,全局统一时间格式
trade_no String 32 Y 会员唯一订单号
total_fee String 12 N 金额,单位分
trade_type String 10 N 交易订单类型,
BALABCE_PAY:会员余额付
GENERAL_PAY:普通支付(非余额付)
RECHARGE:会员充值
trade_state String 10 N 交易订单状态,SUCCESS支付成功,REFUND转入退款,NOTPAY未支付,CLOSED已关闭,USERPAYING用户支付中,REVOKED已撤销,NOPAY未支付支付超时,PAYERROR支付失败
user_id String 32 N 付款方用户id,“微信openid”、“支付宝账户”、“qq号”等,返回时不参与签名
receipt_fee String 12 N 实收金额,pay_type为010、020、090时必填
trade_time String 14 N 当前支付终端交易时间yyyy-MM-dd HH:mm:ss
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

3.9 查询优惠活动

  • URL : member/terminal/querydiscoutactivitylist
  • Method :POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
user_pay_type String 1 N 用户支付方式 1.余额支付 2.非余额支付
active_object String 1 N 活动对象 1.新会员 2.老会员
member_no String 32 N 会员编号,若传了该字段,会进行该会员能参与的活动过滤
market_type String 128 N 活动类型:FULL_REDUCTION:会员消费满减 FULL_DISCOUNT:会员消费折扣 CONSUME_REDUCTION:消费立减, 多个,分割
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
activities String - N 活动列表,JSON字符串,需要转义
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

activities字段如下

参数名称 类型 长度 必填 说明
activity_no String 32 Y 活动编号
activity_name String 20 Y 活动名称
activity_pay_type String 1 Y 支付方式 0.不限 1.余额支付 2.非余额支付
market_type String 20 Y 活动类型:FULL_REDUCTION:会员消费满减 FULL_DISCOUNT:会员消费折扣 CONSUME_REDUCTION:消费立减
discounts Array - Y 优惠规则列表

discounts字段如下

参数名称 类型 长度 必填 说明
discount_threshold String 11 Y 优惠门槛金额(分)
discount_detail String 35 Y 优惠。market_type为FULL_REDUCTION、CONSUME_REDUCTION、RECHANGE_DISCOUNT时表示优惠金额(分),且需小于优惠门槛;
market_type为FULL_DISCOUNT时表示折扣eg:70=7折;多个优惠规则需保持一致。
serial_number String 1 Y 优惠规则序号

3.10 查询积分抵扣规则

  • URL : member/terminal/queryscoredeductrule
  • Method :POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
score_use_limit String 1 Y 是否支持积分抵扣 0:不支持 1:支持
use_threshold String 11 N 积分抵扣门槛。
score_use_limit为1时返回
amt_value String 11 N 满足门槛可抵扣金额(分)

score_use_limit为1时返回
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

3.11. 查询单笔会员交易

  • URL : member/terminal/querytradeone
  • Method :POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
member_trade_no String 32 N 交易流水号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
trade_data String - N 交易详情,JSON字符串,需要转义
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

trade_data字段如下

参数名称 类型 长度 必填 说明
id String 11 Y 数据id
trade_type String 1 Y 交易类型 0.会员余额支付 1.会员充值
pay_type String 3 Y 支付方式 010:微信 020:支付宝
total_fee String 11 Y 总金额(单位分)
refund_fee String 11 Y 退款金额(单位分)
balance String 11 Y 交易金额(单位分)
settle_time String 19 Y 交易时间 yyyy-MM-dd HH:mm:ss
createtime String 19 Y 创建时间 yyyy-MM-dd HH:mm:ss
update_time String 19 Y 更新时间 yyyy-MM-dd HH:mm:ss
member_trade_no String 32 Y 交易流水号
storename String 32 Y 门店名称
phone String 32 Y 会员手机号
nick_name String 32 Y 会员昵称
refund_status_code String 1 Y 退款状态,退款成功1,退款失败2
pay_status_code String 1 Y 支付状态,支付成功1,支付失败2,受理成功3, 退款成功5 退款失败6 退款中8
terminal_id String 11 Y 终端号
member_card_no String 11 Y 会员卡号
current_balance String 11 Y 当前余额(单位分)
give_balance String 11 Y 赠送的金额
change_score String 11 Y 变动会员积分
deduct_score String 11 Y 抵扣积分
deduct_amt String 11 Y 抵扣金额
order_body String 11 Y 订单描述
operator_name String 32 Y 操作员名称
out_trade_no String 32 Y 扫呗订单号
out_refund_no String 32 Y 退款的原订单号

3.12 获取优惠凭证

  • URL : member/terminal/getcredential
  • Method :POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
amount String 11 Y 订单金额(分)
member_no String 32 N 会员号
coupon_no String 32 N 券码,
coupon_no和activity_no不可同时为空,若有传券码,该接口会将券冻结
activity_no String 32 N 消费立减活动编号
serial_number String 1 N 优惠规则序号,
activity_no不为空时必传
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
discount_credential String 128 N 优惠凭证(直接透传支付接口)
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

3.13 查询最优解

  • URL:member/terminal/queryoptimalsolution
  • Method: POST
  • ContentType: application/json

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
trace_no String 32 Y 请求流水号,不带“-”的uuid,商户侧需保证唯一性
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
user_id_type String 3 Y 用户标识类型
AUTO: 自动识别
PAYCODE:付款码
PHONE:手机号
OPENID:微信open_id
USERID:支付宝user_id
UNIONID:微信union_id
CARDNO:会员卡号
MEMBERNO:会员编号
DYNAMICCODE:动态会员code
user_id String 32 Y 用户标识
amount String 11 Y 参与优惠金额(分)
freeze_flag String 1 N 是否需要同时冻结查出的最优券 0:不冻结 1:冻结 ,该字段为空不冻结
freeze_time String 11 N 冻结时长(秒)。freeze_flag为1时选填,不可小于300秒,不传默认冻结2小时
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

返回参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码 01:成功 02:失败。响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换
result_code String 2 N 业务结果 01:成功 02:失败
trace_no String 32 Y 原请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
discount_credential String 128 N 优惠凭证(直接透传支付接口)
member_info String - N 会员信息,JSON字符串,需要转义
coupon_info String - N 券信息,JSON字符串,需要转义
activity_info String - N 活动信息,JSON字符串,需要转义

member_info字段如下

参数名称 类型 长度 必填 说明
nick_name String 32 Y 昵称
phone String 11 Y 手机号
member_card_no String 32 Y 卡号

coupon_info字段如下

参数名称 类型 长度 必填 说明
coupon_no String 32 Y 券码
coupon_name String 9 Y 优惠券名称
coupon_type String 1 Y 券类型 0:满减券 1:折扣券 2:兑换券 3:停车券 4:团购券 5:优惠券。4、5只在channel_type为MALLCOO时存在

活动信息activity_info字段如下

参数名称 类型 长度 必填 说明
activity_no String 32 Y 活动编号
activity_name String 20 Y 活动名称
market_type String 20 Y 活动类型:FULL_REDUCTION:会员消费满减 FULL_DISCOUNT:会员消费折扣 CONSUME_REDUCTION:消费立减
serial_number String 1 Y 优惠规则序号,
activity_no不为空时必传

3.14 会员交易退款

  • URL : member/terminal/refund
  • Method :POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
member_trade_no String 32 Y 交易流水号
refund_amt String 11 Y 退款金额
operator_id String 11 Y 用户id
auth_code String 11 N 短信验证码,跨终端退款必填
auth_id String 11 N 退款授权手机号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
refund_trade_no String 32 Y 退款流水号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(终端令牌名称为access_token),32位md5加密转换

3.15 会员信息通知

提供会员信息推送接口标准,合作方按该接口要求编写接收地址,接收推送过去的会员信息,根据自己的业务逻辑做处理。
推送参数:

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,当前版本100
trace_no String 32 Y 请求流水号
inst_no String 15 Y 机构编号,扫呗分配
merchant_no String 15 O 扫呗商户号(与品牌id二选一,查商户下的会员)
brand_id String 11 O 品牌id(与商户号二选一,查品牌下的会员,适用于多商户会员)
event_type String 8 Y 事件类型 新增ADD,更新 UPDATE
member_no String 32 Y 会员编号
member_card_no String 32 Y 会员卡号
out_member_no String 32 N 外部会员号
phone String 11 Y 手机号
nick_name String 8 N 会员昵称
sex Integer 1 N 用户性别 0未知 1.男性 2.女性
score Integer 11 N 积分
level Integer 11 N 会员等级
balance Integer 11 N 会员卡余额(分)
birthday String 11 N 生日yyyy-MM-dd
age Integer 11 N 年龄
register_time String 19 Y 注册时间 yyyy-MM-dd HH:mm:ss
update_time String 19 N 更新时间 yyyy-MM-dd HH:mm:ss
extra_params String 255 N 扩展属性字段,按json格式,如无需要则不填写。
该字段暂未开放
示例值:{'exinfo1':'1234','exinfo2':'3456'}
key_sign String 32 Y 签名串

需返回参数:

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述

3.16 积分通知

用于给合作方推送积分明细
推送参数:

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,当前版本100
trace_no String 32 Y 请求流水号
inst_no String 15 Y 机构编号,扫呗分配
merchant_no String 15 O 扫呗商户号(与品牌id二选一,查商户下的会员)
brand_id String 11 O 品牌id(与商户号二选一,查品牌下的会员,适用于多商户会员)
member_no String 32 O 会员编号
member_card_no String 32 O 会员卡号
out_member_no String 32 O 外部会员号
phone String 11 O 手机号
score_type Integer 4 Y 类型 1.余额支付消费赠送积分 2.储值赠送积分 3.余额支付抵扣扣除 4.积分换券 5.积分过期扣除 6退款扣除 7:会员营销活动赠送 8.会员等级变动赠送 9.券过期未使用退款归还 10.普通支付赠送 11.普通支付扣除 12.手动充值赠送 13.手动核销, 14.生日赠送,15.积分支付
change_type Integer 4 Y 变动类型:0.扣除 1.新增
change_score Integer 11 Y 变动积分
remain_score Integer 11 Y 当前积分
out_trade_no String 32 N 支付系统交易流水号
change_date String 10 Y 变动日期 yyyy-MM-dd
change_time String 19 Y 积分时间 yyyy-MM-dd HH:mm:ss
expire_date String 10 Y 积分有效期 yyyy-MM-dd (在这一天积分就失效了)
remark String 50 N 备注
extra_params String 255 N 扩展属性字段,按json格式,如无需要则不填写。
该字段暂未开放
示例值:{'exinfo1':'1234','exinfo2':'3456'}
key_sign String 32 Y 签名串

需返回参数:

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述

3.17 积分变更

  • URL : member/terminal/score
  • Method :POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
member_no String 32 Y 会员编号
event_type String 32 Y 事件类型:
ADD新增
REDUCE扣减
event_name String 32 N 事件类型名
change_score String 11 Y 变更的积分
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
member_no String 32 Y 会员编号
current_score String 11 Y 最新的积分
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为access_token),32位md5加密转换

3.18 查询会员小程序二维码地址

  • URL : member/terminal/qrurl
  • Method :POST

请求参数

参数名称 类型 长度 必填 说明
api_ver String 3 Y 版本号,默认100
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
trace_no String 32 Y 请求流水号
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为access_token),32位md5加密转换

响应参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 业务响应码,01成功、02失败
return_msg String 128 Y 业务响应描述
result_code String 2 Y 业务处理响应码,01成功、02失败
trace_no String 32 Y 请求流水号
merchant_no String 15 Y 扫呗商户号
terminal_id String 8 Y 终端号
qr_url String 11 Y 二维码地址
key_sign String 32 Y 签名检验串,非空参数字典排序+令牌(机构令牌名称为access_token),32位md5加密转换

© 利楚商服 2020 All rights reserved.