商家扣款（创建交易订单）

接口说明

接口名称 pay_order
接口模式 直连
异步通知 是

应用场景

商户确认服务完成后，结束计费，先创建分期单，再通过本接口向指定用户发起扣款交易；发起扣款交易时，需保证交易金额、用户协议号、业务订单号、分期单号准确。

重发注意：

  • 若扣款时报错，而交易单状态（txnState）为“WAIT_PAYING”，则可原参重发扣款，如“买家余额不足”、“没有可用的支付工具”。示例：若因买家余额不足扣款失败时，待买家充值后，系统不会自动扣款，需商户原单号（outTradeNo）再次发起扣款。
  • 若扣款时报错，而交易单状态（txnState）为“PAY_ERROR-支付失败”，如需再次扣款，则仅需更换新的单号（outTradeNo）保持其他参数不变再请求扣款。

接口参数

  • 请求：
字段名 变量名 必填 类型 示例值 描述
代理商商户号 agentMerId S(16) 否 100003789 宝付支付分配的商户号
代理商终端号 agentTerId S(16) 否 213003567 宝付支付分配的终端号
交易商户号 merId S(16) 是 102002369 宝付支付分配的商户号
交易终端号 terId S(16) 是 100003123 宝付支付分配的终端号
商户交易单号 outTradeNo 是 S(32) 20210315155012 商户系统内部交易订单号，同一个商户号下唯一
用户实际付款金额 txnAmt 是 I 100 交易金额，单位：分，如：1元则传入100
交易时间 txnTime 是 T 20210315155012 订单交易时间
订单总金额 totalAmt 是 I 100 如包含营销信息，则订单总金额=用户实际付款金额+营销总金额，反之订单总金额=用户实际付款金额
订单有效时间 timeExpire 否 I 72460 订单支付的有效时间，单位：分钟，不传此参数则宝付支付默认有效时间30分钟
产品类型 prodType 是 E ORDINARY 详见附录：产品类型固定值：ORDINARY
支付方式 payCode 是 E ALIPAY_PAY_CREDIT 固定值：ALIPAY_PAY_CREDIT
支付方式属性 payExtend 是 C 详见：【支付属性】
扣费商户号 feeMerId 否 S(16) 100000 该笔交易承担手续费的商户号，默认从交易商户号收取。
二级商户号 subMchId 是 S(64) 在微信/支付宝报备的二级商户号
服务端通知地址 notifyUrl 否 S(256) https://www.example.com/return_url 付款成功后请求商户侧服务端地址
页面端跳转地址 pageUrl 否 S(128) https://www.example.com/caallback_url 支付完成后跳转的地址：必须是https协议
禁止贷记卡支付 forbidCredit 是 S(1) 0 固定值：0；1：禁止、0：不禁止
附加字段 attach 否 S(128) 预留字段
请求方保留域 reqReserved 否 S(128) 预留字段
风控信息 riskInfo 否 C JSON格式。详见：【风控信息】

风控信息

字段名 变量名 必填 类型 示例值 描述
用户ip地址 clientIp 是 S(64) 100000 付款用户ip地址
交易商户终端经纬度 locationPoint 否 S(128) 100,100 包含经度和纬度，英文逗号分隔

支付方式属性

字段名 变量名 必填 类型 示例值 描述
商品名称 subject 是 S(256) Iphone6 16G 商品标题
商品名称 body 是 S(128) Iphone6 16G 订单描述
产品代码 product_code 是 S(32) GENERAL_WITHHOLDING 固定值：GENERAL_WITHHOLDING
宝付业务订单号 component_order_no 是 S(32) 250303101010190004080008 创建业务订单时宝付返回的业务订单号
宝付分期单号 installment_order_no 是 S(32) 250306101010190004200743 创建分期单时宝付返回的分期单号
商户自定义用户协议号 out_agreement_no 是 S(32) 20250317173233801223 创建业务订单时商户生成的用户协议号
地区信息 area_info 是 S(6) 510812 商户所在地地区信息，6位定长，精确到区县编码维度，与国家统计局一致。注：取值范围可参考《省市区结构说明》，详见地址：http://www.stats.gov.cn/tjsj/tjbz/tjyqhdmhcxhfdm/
终端信息 terminal_info 否 C json格式 商户侧受理终端信息，支付方式为：ALIPAY_MICROPAY，该字段必填
>详见：【支付宝终端信息】
商户门店编号 store_id 否 NJ_001
分期数 hb_fq_num 否 S(5) 12 使用花呗分期比传
手续费比例 hb_fq_seller_percent 否 I 99 使用花呗分期需要卖家承担的 手续费 比例的百分值，传入 100 代表 100%
可用渠道 enable_pay_channels 否 S(64) pcredit,moneyFund,debitCardExpress 可用渠道,用户只能在指定渠道范围内支付，多个渠道以逗号分割
禁用渠道 disable_pay_channels 否 S(64) pcredit,moneyFund,debitCardExpress 禁用渠道,用户不可用指定渠道支付，多个渠道以逗号分割
外部买家信息 ext_user_info 否 C 指定外部买家信息，基于上送信息进行校验，不上送则不校验。
详见：【支付宝外部买家信息】
订单详情信息 goods_detail 否 C [{ “goods_id”: “apple-01”, “alipay_goods_id”: “20010001”, “goods_name”: “ipad”, “quantity”: “2”, “price”: “2000”,”goods_category”: “34543238”, “categories_tree”: “124868003|126232002|126252004”, “body”: “特价手机”, “show_url”: “http://www.alipay.com/xxx.jpg" },{ “goods_id”: “apple-01”, “alipay_goods_id”: “20010001”, “goods_name”: “ipad”, “quantity”: “2”, “price”: “2000”, “goods_category”: “34543238”, “categories_tree”: “124868003|126232002|126252004”, “body”: “特价手机”, “show_url”: “http://www.alipay.com/xxx.jpg" }] JSON数组，订单包含的商品列表信息。
详见【支付宝订单详情信息】

支付宝终端信息

字段名 变量名 必填 类型 示例值 描述
时经纬度信息 location 否 S(32) +37.12/-121.213 受理终端设备实时经纬度信息，格式为纬度/经度，+表示北纬、东经，-表示南+37.12/-121.213 2纬、西经。
终端产品入网认证编号 network_license 否 S(5) P3100 银行卡受理终端产品入网认证编号。该编号由“中国银联标识产品企业资质认证办公室”为通过入网认证的终端进行分配
终端设备类型 terminal_type 是 S(2) 终端设备类型，受理方可参考终端注册时的设备类型填写，取值详见《终端设备类型枚举》
终端设备的硬件序列号 serial_num 否 S(50) 123456798989 终端设备的硬件序列号
终端设备编号 terminal_id 是 S(8) 89048765 终端设备的硬件序列号
加密随机数 encrypt_rand_num 否 S(10) 仅在被扫支付类交易报文中出现：若付款码为 19 位数字，则取后 6 位；若付款码码为 EMV 二维码，则取其 tag 57 的卡号/token 号的后 6 位
密文数据 secret_text 否 S(16) 仅在被扫支付类交易报文中出现：64bit的密文数据，对终端硬件序列号和加密随机因子加密后的结果。本子域取值为：64bit 密文数据进行base64 编码后的结果。
终端应用程序的版本号 app_version 否 S(8) 应用程序变更应保证版本号不重复。当长度不足时，右补空格。
商户端终端设备 IP 地址 terminal_ip 否 S(64) 商户端终端设备 IP 地址。注：如经、维度信息未上送，该字段必送。
基站国家信息 mobile_country_cd 否 S(3) 460 基站信息，移动国家代码，由国际电联(ITU) 统一 分 配 的 移 动 国 家 代 码（MCC），中国为 460
基站信息 mobile_net_num 否 S(2) 01 基站信息，移动网络号码，由国际电联(ITU) 统 一 分 配 的 移 动 网 络 号 码（MNC）移动：00、02、04、07；联通：01、06、09；电信：03、05、11
ICCID icc_id 否 S(20) ICCID，SIM 卡卡号
位置区域码1 location_cd1 否 S(4) LAC(移动、联通)，16进制
基站编号1 lbs_num1 否 S(12) CID(移动、联通)，16进制
基站信号1 lbs_signal1 否 S(4) CID(移动、联通)，16进制
位置区域码2 location_cd2 否 S(4) 位置区域码2 LAC(移动、联通)，16进制
基站编号2 lbs_num2 否 S(12) CID(移动、联通)，16进制
基站信号2 lbs_signal2 否 S(4) SIG(移动、联通)，16 进 制
位置区域码3 location_cd3 否 S(4) LAC(移动、联通)，16进制
基站编号3 lbs_num3 否 S(12) CID(移动、联通)，16进制
基站信号3 lbs_signal3 否 S(4) SIG(移动、联通)，16 进 制
电信系统识别码 telecom_sys_id 否 S(4) SID（电信），电信系统识别码,每个地级市只有一个 SID
电信网络识别码 telecom_net_id 否 S(4) NID（电信），电信网络识别码,由电信各由地级分公司分配。每个地级市可能有 1 到 3 个 NID
电信基站 telecom_lbs 否 S(4) BID（电信），电信网络中的小区识别码，等效于基站
电信基站信号 telecom_lbs_signal 否 S(4) SIG（电信），16 进制

支付宝外部买家信息

字段名 变量名 必填 类型 示例值 描述
姓名 name 否 S(16) need_check_info=T时生效
实名认证信息。请求时使用SM2签名算法，使用国密加密该字段，其中初始向量为：www.ivbaofoo.com。
请求时使用RSA签名算法，使用3DES加密算法，其初始向量为：iv.baofu
手机号码 mobile 否 S(20) 手机号码（该字段暂不参与校验)
实名认证信息。请求时使用SM2签名算法，使用国密加密该字段，其中初始向量为：www.ivbaofoo.com。
请求时使用RSA签名算法，使用3DES加密算法，其初始向量为：iv.baofu
证件类型 cert_type 否 S(32)
证件号 cert_no 否 S(64) 实名认证信息。请求时使用SM2签名算法，使用国密加密该字段，其中初始向量为：www.ivbaofoo.com。
请求时使用RSA签名算法，使用3DES加密算法，其初始向量为：iv.baofu
允许支付的最小买家年龄 min_age 否 S(3) 买家年龄必须大于等于所传数值need_check_info=T时生效，且年龄为大于0的整数
是否强制校验身份信息 need_check_info 否 S(1) F 是否强制校验身份信息：T：强制校验，F：不强制

支付宝订单详情信息

字段名 变量名 必填 类型 示例值 描述
商品的编号 goods_id 是 S(32) apple-01 商品的编号
支付宝定义的统一商品编号 alipay_goods_id 否 S(32) 20010001 支付宝定义的统一商品编号
商品名称 goods_name 是 S(256) ipad 商品名称
商品数量 quantity 是 I 2 商品数量
商品单价 price 是 I 2000 商品单价，单位为元
商品类目 goods_category 否 S(24) 34543238 商品类目
商品类目树 categories_tree 否 S(128) 124868003|126232002|126252004 商品类目树，从商品类目根节点到叶子节点的类目 id 组成，类目 id值使用|分割
商品描述信息 body 否 S(1000) 特价手机 商品描述信息
商品的展示地址 show_url 否 S(400) http://www.alipay.com/xxx.jpg 商品的展示地址
  • 返回
字段名 变量名 必填 类型 示例值 描述
代理商商户号 agentMerId S(16) 否 100003789 宝付支付分配的商户号
代理商终端号 agentTerId S(16) 否 213003567 宝付支付分配的终端号
交易商户号 merId S(16) 是 102002369 宝付支付分配的商户号
交易终端号 terId S(16) 是 100003123 宝付支付分配的终端号
商户交易单号 outTradeNo 是 S(64) 20210315155012 商户系统内部交易订单号，同一个商户号下唯一
交易单状态 txnState 否 E WAIT_PAYING 详见：【交易订单状态】
宝付交易号 tradeNo 否 S(32) 12312312312 与商户订单号对应的宝付侧唯一交易号
请求渠道订单号 reqChlNo 否 S(64) 宝付请求渠道订单号
支付方式 payCode 是 E 原样返回
渠道返回参数 chlRetParam 否 C 根据不同的支付方式返回相应的业务参数，作为商户侧唤起支付，详见：【渠道返回参数】
业务结果 resultCode 是 S(16) SUCCESS 业务处理结果
错误代码 errCode 否 S(32) 当业务结果FAIL时，返回错误代码
错误描述 errMsg 否 S(128) 当业务结果为FAIL时，返回错误描述
作者：lilizhi  创建时间：2025-03-21 18:43
最后编辑：lilizhi  更新时间：2025-06-17 14:16