统一收单线下交易预创建

开发环境

POST

/v3/alipay/trade/precreate

alipay.trade

收银员通过收银台或商户后台调用支付宝接口，生成二维码后，展示给用户，由用户扫描二维码完成订单支付。

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'http://dev-cn.your-api-server.com/v3/alipay/trade/precreate' \
--header 'Content-Type: application/json' \
--data-raw ''

响应示例

200 - 示例 1

{
  "out_trade_no": "6823789339978248",
  "qr_code": "https://qr.alipay.com/bavh4wjlxf12tper3a",
  "share_code": "chb4n8A94Qc"
}

请求参数

Body 参数application/json

bkagent_req_info

object (BkAgentReqInfo)

可选

acq_code

string

可选

收单机构在清算组织登记或分配的机构代码

device_type

string

可选

终端设备类型，受理方可参考终端注册时的设备类型填写。

location

string

可选

终端设备实时经纬度信息，格式为纬度/经度，+表示北纬、东经，-表示南纬、西经。

merch_code

string

可选

收单机构在清算组织登记的商户编码

serial_num

string

可选

终端类型填写为 02、 03、04、05、06、08、09 或 10 时，必须填写终端序列号。

business_params

object (BusinessParams)

可选

actual_order_time

string

可选

实际订单时间，在乘车码场景，传入的是用户刷码乘车时间

campus_card

string

校园卡编号

可选

card_type

string

虚拟卡卡类型

可选

enterprise_pay_amount

string

可选

因公付金额，单位：元。

enterprise_pay_info

string

因公付业务信息

可选

good_taxes

string

可选

商户传入的交易税费。需要落地风控使用

mc_create_trade_ip

string

可选

商户端创建订单的 IP，须上传正确的用户端外网 IP，支持 ipv4/ipv6 格式； mc_create_trade_ip和mcCreateTradeIp（旧）参数描述相同，首选mc_create_trade_ip入参，请勿重复入参；如已入参mcCreateTradeIp（旧），无需新增入参mc_create_trade_ip。

tiny_app_merchant_biz_type

string

可选

当需要在商家平台（b.alipay.com）—数据中心中查看对应业务场景下的数据明细可以通过该参数传入支持传入的值：小程序细分业务场景

ext_user_info

object (ExtUserInfo)

可选

cert_no

string

可选

买家证件号。注：need_check_info=T或fix_buyer=T时该参数才有效，支付宝会比较买家在支付宝留存的证件号码与该参数传入的值是否匹配。

cert_type

string

可选

指定买家证件类型。枚举值： IDENTITY_CARD：身份证； PASSPORT：护照； OFFICER_CARD：军官证； SOLDIER_CARD：士兵证； HOKOU：户口本。如有其它类型需要支持，请与蚂蚁金服工作人员联系。注： need_check_info=T或fix_buyer=T时该参数才有效，支付宝会比较买家在支付宝留存的证件类型与该参数传入的值是否匹配。

fix_buyer

string

可选

是否强制校验买家身份。需要强制校验传：T; 不需要强制校验传：F或者不传；当传T时，接口上必须指定cert_type、cert_no和name信息且支付宝会校验传入的信息跟支付买家的信息都匹配，否则报错。默认为不校验。

identity_hash

string

可选

买家加密身份信息。当指定了此参数且指定need_check_info=T时，支付宝会对买家身份进行校验，校验逻辑为买家姓名、买家证件号拼接后的字符串，以sha256算法utf-8编码计算hash，若与传入的值不匹配则会拦截本次支付。注意：如果同时指定了用户明文身份信息（name，cert_type，cert_no中任意一个），则忽略identity_hash以明文参数校验。

min_age

string

可选

允许的最小买家年龄。买家年龄必须大于等于所传数值注： 1. need_check_info=T时该参数才有效 2. min_age为整数，必须大于等于0

mobile

string

可选

指定买家手机号。注：该参数暂不校验

name

string

可选

指定买家姓名。注： need_check_info=T或fix_buyer=T时该参数才有效

need_check_info

string

可选

是否强制校验买家信息；需要强制校验传：T; 不需要强制校验传：F或者不传；当传T时，支付宝会校验支付买家的信息与接口上传递的cert_type、cert_no、name或age是否匹配，只有接口传递了信息才会进行对应项的校验；只要有任何一项信息校验不匹配交易都会失败。如果传递了need_check_info，但是没有传任何校验项，则不进行任何校验。默认为不校验。

extend_params

object (ExtendParams)

可选

card_type

string

卡类型

可选

hb_fq_num

string

可选

使用花呗分期要进行的分期数

hb_fq_seller_percent

string

可选

使用花呗分期需要卖家承担的手续费比例的百分值，传入100代表100%

industry_reflux_info

string

可选

行业数据回流信息, 详见：地铁支付接口参数补充说明

royalty_freeze

string

可选

是否进行资金冻结，用于后续分账，true表示资金冻结，false或不传表示资金不冻结

specified_seller_name

string

可选

特殊场景下，允许商户指定交易展示的卖家名称

sys_service_provider_id

string

可选

系统商编号该参数作为系统商返佣数据提取的依据，请填写系统商签约协议的PID

trade_component_order_id

string

可选

公域商品交易业务订单ID

royalty_info

object (RoyaltyInfo)

可选

royalty_detail_infos

array[object (RoyaltyDetailInfos) {10}]

可选

分账明细的信息，可以描述多条分账指令，json数组。

royalty_type

string

可选

分账类型卖家的分账类型，目前只支持传入ROYALTY（普通分账类型）。

settle_info

object (SettleInfo)

可选

settle_detail_infos

array[object (SettleDetailInfo) {7}]

可选

结算详细信息，json数组，目前只支持一条。

settle_period_time

string

可选

该笔订单的超期自动确认结算时间，到达期限后，将自动确认结算。此字段只在签约账期结算模式时有效。取值范围：1d～365d。d-天。该参数数值不接受小数点。

sub_merchant

object (SubMerchant)

可选

merchant_id

string

可选

支付宝二级商户编号。间连受理商户的支付宝商户编号，通过间连商户入驻接口后由支付宝生成。直付通和机构间连业务场景下必传。

merchant_type

string

可选

二级商户编号类型。枚举值： alipay:支付宝分配的间联商户编号；目前仅支持alipay，默认可以不传。

alipay_store_id

string

可选

支付宝店铺编号。指商户创建门店后支付宝生成的门店ID。

示例值:

2016052600077000000015640104

body

string

可选

订单附加信息。如果请求时传递了该参数，将在异步通知、对账单中原样返回，同时会在商户和用户的pc账单详情中作为交易描述展示

示例值:

Iphone6 16G

buyer_logon_id

string

买家支付宝账号

可选

示例值:

15901825620

code_type

string

可选

码类型，如果请求时传入了share_code，将在响应参数返回吱口令；如果为空，则默认为订单码

示例值:

share_code

disable_pay_channels

string

可选

禁用渠道,用户不可用指定渠道支付，多个渠道以逗号分割注，与enable_pay_channels互斥渠道列表

示例值:

pcredit,moneyFund,debitCardExpress

discountable_amount

string

可选

可打折金额。参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]。如果同时传入了【可打折金额】、【不可打折金额】和【订单总金额】，则必须满足如下条件：【订单总金额】=【可打折金额】+【不可打折金额】。如果订单金额全部参与优惠计算，则【可打折金额】和【不可打折金额】都无需传入。

示例值:

80.00

enable_pay_channels

string

可选

指定支付渠道。用户只能使用指定的渠道进行支付，多个渠道以逗号分割。与disable_pay_channels互斥，支持传入的值：渠道列表。注：如果传入了指定支付渠道，则用户只能用指定内的渠道支付，包括营销渠道也要指定才能使用。该参数可能导致用户支付受限，慎用。

示例值:

pcredit,moneyFund,debitCardExpress

goods_detail

array[object (GoodsDetail) {11}]

可选

订单包含的商品列表信息.json格式. 其它说明详见：“商品明细说明”

alipay_goods_id

string

可选

支付宝定义的统一商品编号

body

string

商品描述信息

可选

categories_tree

string

可选

商品类目树，从商品类目根节点到叶子节点的类目id组成，类目id值使用|分割

goods_category

string

商品类目

可选

goods_id

string

可选

商品的编号，该参数传入支付券上绑定商品goods_id, 倘若无支付券需要消费，该字段传入商品最小粒度的商品ID（如：若商品有sku粒度，则传商户sku粒度的ID）

goods_name

string

商品名称

可选

out_item_id

string

可选

商家侧小程序商品ID，指商家提报给小程序商品库的商品。当前接口的extend_params.trade_component_order_id字段不为空时该字段必填，且与交易组件订单参数保持一致。了解小程序商品请参考：https://opendocs.alipay.com/pre-open/06uila?pathHash=87297d0a

out_sku_id

string

可选

price

string

商品单价，单位为元

可选

quantity

integer

商品数量

可选

show_url

string

商品的展示地址

可选

merchant_order_no

string

商户的原始订单号

可选

示例值:

20161008001

notify_url

string

通知地址

可选

operator_id

string

商户操作员编号。

可选

示例值:

yx_001

out_trade_no

string

可选

商户订单号。由商家自定义，64个字符以内，仅支持字母、数字、下划线且需保证在商户端不重复。

示例值:

20150320010101001

passback_params

string

可选

公用回传参数。如果请求时传递了该参数，支付宝会在异步通知时将该参数原样返回。

示例值:

merchantBizType%3d3C%26merchantBizNo%3d2016010101111

product_code

string

可选

产品码。商家和支付宝签约的产品码。枚举值（点击查看签约情况）： FACE_TO_FACE_PAYMENT：当面付产品；默认值为FACE_TO_FACE_PAYMENT。

示例值:

FACE_TO_FACE_PAYMENT

qr_code_timeout_express

string

可选

二维码订单相对超时时间。该笔订单允许的最晚付款时间，逾期将关闭交易，从生成二维码开始计时。取值范围：1m～15d。m-分钟，h-小时，d-天，1c-当天（1c-当天的情况下，无论交易何时创建，都在0点关闭）。该参数数值不接受小数点，如 1.5h，可转换为 90m。注：二维码最长有效期是2小时，不管该参数传递的值是多少，超过2小时后二维码都将失效不能再进行扫码支付。

示例值:

90m

seller_id

string

可选

卖家支付宝用户ID。当需要指定收款账号时，通过该参数传入，如果该值为空，则默认为商户签约账号对应的支付宝用户ID。收款账号优先级规则：门店绑定的收款账户>请求传入的seller_id>商户签约账号对应的支付宝用户ID；注：直付通和机构间联场景下seller_id无需传入或者保持跟pid一致；如果传入的seller_id与pid不一致，需要联系支付宝小二配置收款关系；

示例值:

2088102146225135

store_id

string

可选

商户门店编号。指商户创建门店时输入的门店编号。

示例值:

NJ_001

subject

string

可选

订单标题。注意：不可使用特殊字符，如 /，=，& 等。

示例值:

Iphone6 16G

terminal_id

string

商户机具终端编号。

可选

示例值:

NJ_T_001

timeout_express

string

可选

订单相对超时时间。从预下单请求时间开始计算。该笔订单允许的最晚付款时间，逾期将关闭交易。取值范围：1m～15d。m-分钟，h-小时，d-天，1c-当天（1c-当天的情况下，无论交易何时创建，都在0点关闭）。该参数数值不接受小数点，如 1.5h，可转换为 90m。当面付场景默认值为3h；注： 1. 二维码最长有效期是2小时，不管该参数传递的值是多少，超过2小时后二维码都将失效不能再进行扫码支付。 2. time_expire和timeout_express两者只需传入一个或者都不传，如果两者都传，优先使用time_expire。

示例值:

90m

total_amount

string

可选

订单总金额。单位为元，精确到小数点后两位，取值范围：[0.01,100000000] 。

示例值:

88.88

undiscountable_amount

string

可选

不可打折金额。不参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]。如果同时传入了【可打折金额】、【不可打折金额】和【订单总金额】，则必须满足如下条件：【订单总金额】=【可打折金额】+【不可打折金额】。如果订单金额全部参与优惠计算，则【可打折金额】和【不可打折金额】都无需传入。

示例值:

8.88

query_options

array[string]

可选

返回参数选项。商户通过传递该参数来定制需要额外返回的信息字段，数组格式。包括但不限于：["hyb_amount","enterprise_pay_info"]

示例值:

["hyb_amount","enterprise_pay_info"]

time_expire

string

可选

订单绝对超时时间。格式为yyyy-MM-dd HH:mm:ss。注：time_expire和timeout_express两者只需传入一个或者都不传，如果两者都传，优先使用time_expire。

示例值:

{}

示例

返回响应

🟢200common response

application/json

Body

out_trade_no

string

商户的订单号

可选

示例值:

6823789339978248

qr_code

string

可选

当前预下单请求生成的二维码码串，有效时间2小时，可以用二维码生成工具根据该码串值生成对应的二维码

示例值:

https://qr.alipay.com/bavh4wjlxf12tper3a

share_code

string

可选

当前预下单请求生成的吱口令码串，有效时间2小时，可以在支付宝app端访问对应内容

示例值:

chb4n8A94Qc

🔴500请求失败

修改于 2023-11-20 03:28:56

收单退款冲退完成通知

统一收单交易创建接口