预下单

入口

    {api_domain}/upay/v2/precreate

签名验证

请见签名机制文档

请求参数说明

参数 参数名称 类型 必填 描述 范例
terminal_sn 收钱吧终端ID String(32) Y 收钱吧终端ID "23420593829"
client_sn 商户系统订单号 String(32) Y 必须在商户系统内唯一;且长度不超过32字节 "18348290098298292838"
total_amount 交易总金额 String(10) Y 以分为单位,不超过10位纯数字字符串,超过1亿元的收款请使用银行转账 "1000"
payway 支付方式 String Y 内容为数字的字符串 2:支付宝
3:微信
sub_payway 二级支付方式 String N 内容为数字的字符串,如果要使用WAP支付,则必须传 "3";使用小程序支付,则必须传"4" "3"
payer_uid 付款人id String(64) N 消费者在支付通道的唯一id,wap支付,小程序支付必传微信WAP支付必须传open_id,支付宝WAP支付必传用户授权的userId "okSzXt_KIZVhGZe538aOKIMswUiI"
subject 交易简介 String(64) Y 本次交易的概述 "pizza"
operator 门店操作员 String(32) Y 发起本次交易的操作员 "Obama"
description 商品详情 String(255) N 对商品或本次交易的描述
longitude 经度 String N 经纬度必须同时出现
latitude 纬度 String N 经纬度必须同时出现
extended 扩展参数集合 String(256) N 收钱吧与特定第三方单独约定的参数集合,json格式,最多支持24个字段,每个字段key长度不超过64字节,value长度不超过256字节
小程序扫码点餐订单必传参数:{"attach":"OrderSource=FoodOrder"}
{ "goods_tag": "beijing"}
goods_details 商品详情 JSON N goods_details的值为数组,每一个元素为json,包含五个字段:
goods_id商品的编号;
goods_name商品名称;
quantity商品数量;
price商品单价,单位为分;
promotion_type优惠类型,0:没有优惠,收钱吧不处理单品信息 1: 支付机构优惠,收钱吧处理单品信息并上送到支付机构
"goods_details": [{"goods_id": "wx001","goods_name": "苹果笔记本电脑","quantity": 1,"price": 2,"promotion_type": 0},{"goods_id":"wx002","goods_name":"tesla","quantity": 1,"price": 2,"promotion_type": 1}]
reflect 反射参数 String(64) N 任何调用者希望原样返回的信息 "{ \"tips\": \"200\" }"
notify_url 回调 String(128) N 支付回调的地址 例如:www.baidu.com 如果支付成功通知时间间隔为1s,5s,30s,600s

商户系统订单号必须在商户系统内唯一,支付失败订单的二次预下单请求,请创建新的商户订单号

请求参数中关于goods_details说明

字段名称 数值格式 长度 字段描述
goods_id String必填 32 商品的编号
goods_name String必填 32 商品名称,如ipad
quantity Number必填 10 商品数量,如10
price Number必填 9 商品单价,单位为分,如2000
promotion_type Number必填 1 优惠类型,0表示没有优惠,1表示支付机构优惠,为1会把相关信息送到支付机构

花呗分期交易请求参数

参数 参数名称 类型 必填 描述 范例
hb_fq_num 花呗分期数 String Y 目前支持3/6/12期,前置参数为extended.extend_params "extended":{"extend_params": {"hb_fq_num": "12"}}
hb_fq_seller_percent 花呗分期卖家承担手续费比例 String Y 商家承担手续费传入100,用户承担手续费传入0,前置参数为extended.extend_params "extended": {"extend_params": {"hb_fq_seller_percent": "0"}}

同步返回参数说明

参数 参数名称 类型 必填 描述 范例
sn 收钱吧唯一订单号 String(16) Y 收钱吧系统内部唯一订单号 7892259488292938
client_sn 商户订单号 String(64) Y 商户系统订单号 7654321132
trade_no 支付服务商订单号 String(64) N 支付通道交易凭证号 2013112011001004330000121536
status 流水状态 String(32) Y 本次操作产生的流水的状态 CREATED
order_status 订单状态 String(32) Y 当前订单状态 CREATED
payway 支付方式 String(2) Y 一级支付方式,取值见附录《支付方式列表》 1
sub_payway 二级支付方式 String(2) Y 二级支付方式,取值见附录《二级支付方式列表》 3
qr_code 二维码内容 String(128) N 预下单成功后生成的二维码 https://qr.alipay.com/bax00069h45nvvfc3tu9803a
total_amount 交易总额 String(10) Y 本次交易总金额 10000
net_amount 实收金额 String(10) Y 如果没有退款,这个字段等于total_amount。否则等于total_amount减去退款金额 0
subject 交易概述 String(64) Y 本次交易概述 Pizza
operator 操作员 String(32) Y 门店操作员 张三丰
reflect 反射参数 String(64) N 透传参数 "{ \"tips\": \"200\" }"
wap_pay_request 支付通道返回的调用WAP支付需要传递的信息 String(1024) N WAP支付、小程序支付一定会返回;  

返回的状态码请参考附录

请求示例

    {
        "total_amount": "1", 
        "subject": "收钱吧", 
        "payway": "1",  
        "sub_payway":"2", 
        "extended":  
        {
            "extend_params": 
            {
                "hb_fq_seller_percent": "0",
                "hb_fq_num": "3"
            }
        },
        "terminal_sn": "101234641234111234",
        "client_sn": "6918981703584786",
        "operator": "Roy"
    }

预下单返回示例

预下单成功

    {
        "result_code": "200",
        "biz_response": {
            "result_code": "PRECREATE_SUCCESS",
            "data": {
                "sn": "7894259244096169",
                "client_sn": "765432112",
                "status": "IN_PROG",
                "order_status": "CREATED",
                "total_amount": "1",
                "net_amount": "1",
                "operator ": "张三丰",
                "subject ": "coca cola",
                "qr_code": "https://qr.alipay.com/bax8z75ihyoqpgkv5f"
            }
        }
    }

预下单接口接入常见问题

1.对于支付结果的获取,建议如何处理?

  • 为了保证第三方系统可稳定、高效收到订单处理结果,我们建议开发者使用主动轮询加回调的方式处理。
  • 回调的通知间隔是1s, 5s, 30s, 600s。

2.主动轮询获取订单状态

  • 在得到预下单成功的结果后,即可向收钱吧服务器发起轮询请求。在响应中,预下单成功的标识为:biz_response.result_code="PRECREATE_SUCCESS" or biz_response.data.order_status="CREATED")。
  • 收钱吧目前所有预下单的订单有效支付时长约为4分钟,在订单有效期内,开发者可按以下建议发起轮询:
    • 第0-1分钟,轮询间隔为10s, 5s, 5s, 10s, 10s, 10s, 10s;
    • 第1-2分钟,轮询间隔为20s;
    • 第2-3分钟,轮询间隔为30s;
    • 第3-4分钟,轮询间隔为30s;
    • 第6分钟,做最后一次轮询。

如果第三方系统已通过轮询或者回调获得了支付结果,可停止轮询。

results matching ""

    No results matching ""