统一收单交易支付接口 支付宝 V3版本

支付宝预授权

新当面资金授权

周期扣款

当面付-付款码支付

参数

是否必选

是否必选

是否必选

是否必选

类型

最大长度

描述

示例值

公共请求参数

authorization

√

必选

√

必选

√

必选

√

必选

String

1024

请求身份信息，参考验签规则。在header参数中传递

content-type

√

可选

√

可选

√

可选

√

可选

String

32

报文内容格式，默认需要使用appliaction/json，加密请求使用text/plain，参考请求规则。在header参数中传递

appliaction/json

x-http-method-override

√

可选

√

可选

√

可选

√

可选

String

16

HTTP方法，对于部分不支持PUT、PATCH、DELETE等操作的情况，可以使用POST发送请求，并通过该参数传输实际需要使用的HTTP Method，参考请求规则。在header参数中传递

PUT

alipay-request-id

√

可选

√

可选

√

可选

√

可选

String

32

调用方的requestId，用于定位一次请求，需要每次请求保持唯一。排查问题时可以提供该字段，参考请求规则。在header参数中传递。

0ba7cddb1665744697169391253118

alipay-encrypt-type

√

可选

√

可选

√

可选

√

可选

String

16

加密算法，请求使用加密能力时，需要指定加密算法，参考加解密规则。在header参数中传递

AES

alipay-root-cert-sn

√

可选

√

可选

√

可选

√

可选

String

128

支付宝根证书序列号。证书模式时，可传入该参数，支付宝服务端会校验序列号，确保调用方的证书未被篡改，参考验签规则。在header参数中传递

687b59193f3f462dd5336e5abf83c5d8_02941eef3187dddf3d3b83462e1dfcf6

alipay-app-auth-token

√

可选

√

可选

√

可选

√

可选

String

128

应用授权令牌，参考代调用规则。在header参数中传递

201509BBeff9351ad1874306903e96b91d248A36

业务请求参数

notify_url

√

可选

√

可选

√

可选

√

可选

String

1024

支付宝服务器主动通知商户服务器里指定的页面http/https路径。在body参数中传递

http://api.test.alipay.net/atinterface/receive_notify.htm

out_trade_no

√

必选

√

必选

√

必选

√

必选

String

64

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

20150320010101001

total_amount

√

必选

√

必选

√

必选

√

必选

Price

11

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

88.88

subject

√

必选

√

必选

√

必选

√

必选

String

256

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

XX租车租金

auth_code

√

必选

String

64

支付授权码。 当面付场景传买家的付款码（25~30开头的长度为16~24位的数字，实际字符串长度以开发者获取的付款码长度为准）或者刷脸标识串（fp开头的35位字符串）。支付授权码。 当面付场景传买家的付款码（25~30开头的长度为16~24位的数字，实际字符串长度以开发者获取的付款码长度为准）或者刷脸标识串（fp开头的35位字符串）。

28763443825664394

scene

√

必选

String

32

支付场景。 枚举值： bar_code：当面付条码支付场景； security_code：当面付刷脸支付场景，对应的auth_code为fp开头的刷脸标识串； 默认值为bar_code。 枚举值 当面付条码支付场景: bar_code 当面付刷脸支付场景，对应的auth_code为fp开头的刷脸标识串: security_code

bar_code

product_code

√

必选

√

必选

√

必选

√

可选

String

64

产品码。 商家和支付宝签约的产品码。 支付宝预授权场景传：PRE_AUTH_ONLINE；新当面资金授权场景传：PRE_AUTH；

PRE_AUTH_ONLINE

agreement_params

√

必选

AgreementParams

代扣信息。 代扣业务需要传入的协议相关信息，使用本参数传入协议号后scene和auth_code不需要再传值。

agreement_no

√

可选

String

64

支付宝系统中用以唯一标识用户签约记录的编号（用户签约成功后的协议号 ）

20170322450983769228

auth_confirm_no

√

可选

String

10

鉴权确认码，在需要做支付鉴权校验时，该参数不能为空

423979

apply_token

√

可选

String

64

鉴权申请token，其格式和内容，由支付宝定义。在需要做支付鉴权校验时，该参数不能为空。

MDEDUCT0068292ca377d1d44b65fa24ec9cd89132f

seller_id

√

可选

√

可选

String

28

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

2088102146225135

auth_no

√

必选

√

必选

String

64

资金预授权单号。 支付宝预授权和新当面资金授权场景下必填。

2016110310002001760201905725

auth_confirm_mode

√

可选

√

可选

String

32

预授权确认模式。 适用于支付宝预授权和新当面资金授权场景。枚举值： COMPLETE：转交易完成后解冻剩余冻结金额； NOT_COMPLETE：转交易完成后不解冻剩余冻结金额； 默认值为NOT_COMPLETE。 枚举值 转交易完成后解冻剩余冻结金额: COMPLETE 转交易完成后不解冻剩余冻结金额: NOT_COMPLETE

COMPLETE

goods_detail

√

可选

√

可选

√

可选

√

可选

GoodsDetail[]

订单包含的商品列表信息，json格式。

goods_id

√

必选

√

必选

√

必选

√

必选

String

65

商品的编号

apple-01

goods_name

√

必选

√

必选

√

必选

√

必选

String

256

商品名称

ipad

quantity

√

必选

√

必选

√

必选

√

必选

Number

32

商品数量

1

price

√

必选

√

必选

√

必选

√

必选

Price

9

商品单价，单位为元

2000

goods_category

√

可选

√

可选

√

可选

√

可选

String

24

商品类目

34543238

categories_tree

√

可选

√

可选

√

可选

√

可选

String

128

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

124868003|126232002|126252004

show_url

√

可选

√

可选

√

可选

√

可选

String

400

商品的展示地址

http://www.alipay.com/xxx.jpg

extend_params

√

可选

√

可选

√

可选

√

可选

ExtendParams

业务扩展参数

sys_service_provider_id

√

可选

√

可选

√

可选

√

可选

String

64

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

2088511833207846

specified_seller_name

√

可选

√

可选

√

可选

√

可选

String

32

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

XXX的跨境小铺

card_type

√

可选

√

可选

√

可选

√

可选

String

32

卡类型

S0JP0000

business_params

√

可选

BusinessParams

商户传入业务信息，具体值要和支付宝约定，应用于安全，营销等参数直传场景，格式为json格式

mc_create_trade_ip

√

可选

String

128

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

127.0.0.1

promo_params

√

可选

√

可选

√

可选

√

可选

PromoParam

优惠明细参数，通过此属性补充营销参数。 注：仅与支付宝协商后可用。

actual_order_time

√

可选

√

可选

√

可选

√

可选

String

32

存在延迟扣款这一类的场景，用这个时间表明用户发生交易的时间，比如说，在公交地铁场景，用户刷码出站的时间，和商户上送交易的时间是不一样的。

2018-09-25 22:47:33

store_id

√

可选

√

可选

√

可选

String

32

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

NJ_001

operator_id

√

可选

String

28

商户操作员编号。

yx_001

terminal_id

√

可选

√

可选

√

可选

String

32

商户机具终端编号。

NJ_T_001

pay_params

√

可选

PayParams

支付相关参数

async_type

√

可选

String

64

普通异步支付, 传入该参数时，如果满足受理条件，会先同步受理支付，然后在异步调度推进支付 NORMAL_ASYNC: 普通异步，受理成功之后，会在交易关单之前通过一定的策略重试 NEAR_REAL_TIME_ASYNC: 准实时异步，受理成功之后，会准实时发起1次调度

NORMAL_ASYNC

query_options

√

可选

√

可选

√

可选

√

可选

String[]

1024

返回参数选项。 商户通过传递该参数来定制同步需要额外返回的信息字段，数组格式。如：["fund_bill_list","voucher_detail_list","discount_goods_detail"] 枚举值 资金明细信息: fund_bill_list 优惠券信息: voucher_detail_list 因公付金额信息: enterprise_pay_info 惠营宝回票金额信息: hyb_amount 商品优惠信息: discount_goods_detail 平台优惠金额: discount_amount 商家优惠金额: mdiscount_amount

["voucher_detail_list"]

公共响应参数

alipay-timestamp

√

可选

√

可选

√

可选

√

可选

String

32

unix时间戳，用于验签及问题排查，参考验签规则。在header参数中传递

1666004496123

alipay-signature

√

可选

√

可选

√

可选

√

可选

String

512

支付宝响应报文签名，参考验签规则。在header中返回

alipay-traceid

√

可选

√

可选

√

可选

√

可选

String

64

支付宝traceId ，用于排查问题使用，参考请求规则。在header中返回

0ba7cddb1665744697169391253118

alipay-nonce

√

可选

√

可选

√

可选

√

可选

String

64

支付宝nonce标记，每次请求会生成不同的nonce，可用于防重放判断，参考请求规则。在header中返回

515cf24c2f78b13564e94c2a495695ab

业务响应参数

trade_no

√

必选

√

必选

√

必选

√

必选

String

64

支付宝交易号

2013112011001004330000121536

out_trade_no

√

必选

√

必选

√

必选

√

必选

String

64

商户订单号

6823789339978248

buyer_logon_id

√

必选

√

必选

√

必选

√

必选

String

100

买家支付宝账号

159****5620

total_amount

√

必选

√

必选

√

必选

√

必选

Price

11

交易金额

120.88

receipt_amount

√

必选

√

必选

√

必选

√

必选

String

11

实收金额

88.88

buyer_pay_amount

√

特殊可选

√

特殊可选

√

特殊可选

√

可选

Price

11

买家付款的金额

8.88

point_amount

√

特殊可选

√

特殊可选

√

特殊可选

√

可选

Price

11

使用集分宝付款的金额

8.12

invoice_amount

√

特殊可选

√

特殊可选

√

特殊可选

√

可选

Price

11

交易中可给用户开具发票的金额

12.50

gmt_payment

√

必选

√

必选

√

必选

√

必选

Date

32

交易支付时间

2014-11-27 15:45:57

fund_bill_list

√

必选

√

必选

√

必选

√

必选

TradeFundBill[]

交易支付使用的资金渠道。 只有在签约中指定需要返回资金明细，或者入参的query_options中指定时才返回该字段信息。

fund_channel

√

必选

√

必选

√

必选

√

必选

String

32

交易使用的资金渠道，详见 支付渠道列表

ALIPAYACCOUNT

amount

√

必选

√

必选

√

必选

√

必选

Price

32

该支付工具类型所使用的金额

10

real_amount

√

可选

√

可选

√

可选

√

可选

Price

11

渠道实际付款金额

11.21

store_name

√

特殊可选

√

特殊可选

√

特殊可选

√

可选

String

512

发生支付交易的商户门店名称

证大五道口店

discount_goods_detail

√

特殊可选

√

特殊可选

√

特殊可选

√

可选

String

5120

本次交易支付所使用的单品券优惠的商品优惠信息。 只有在query_options中指定时才返回该字段信息。

[{"goods_id":"STANDARD1026181538","goods_name":"雪碧","discount_amount":"100.00","voucher_id":"2015102600073002039000002D5O"}]

buyer_user_id

√

必选

√

必选

√

必选

√

必选

String

28

买家在支付宝的用户id

2088101117955611

async_payment_mode

√

特殊可选

√

特殊可选

√

特殊可选

String

20

异步支付模式，目前有五种值： ASYNC_DELAY_PAY(异步延时付款); ASYNC_REALTIME_PAY(异步准实时付款); SYNC_DIRECT_PAY(同步直接扣款); NORMAL_ASYNC_PAY(纯异步付款); QUOTA_OCCUPYIED_ASYNC_PAY(异步支付并且预占了先享后付额度); 枚举值 异步延时付款: ASYNC_DELAY_PAY 异步准实时付款: ASYNC_REALTIME_PAY 同步直接扣款: SYNC_DIRECT_PAY 纯异步付款: NORMAL_ASYNC_PAY 异步支付并且预占了先享后付额度: QUOTA_OCCUPYIED_ASYNC_PAY

SYNC_DIRECT_PAY

voucher_detail_list

√

特殊可选

√

特殊可选

√

特殊可选

√

特殊可选

VoucherDetail[]

本交易支付时使用的所有优惠券信息。 只有在query_options中指定时才返回该字段信息。

id

√

必选

√

必选

√

必选

√

必选

String

32

券id

2015102600073002039000002D5O

name

√

必选

√

必选

√

必选

√

必选

String

64

券名称

XX超市5折优惠

type

√

必选

√

必选

√

必选

√

必选

String

32

券类型，如： ALIPAY_FIX_VOUCHER - 全场代金券 ALIPAY_DISCOUNT_VOUCHER - 折扣券 ALIPAY_ITEM_VOUCHER - 单品优惠券 ALIPAY_CASH_VOUCHER - 现金抵价券 ALIPAY_BIZ_VOUCHER - 商家全场券 注：不排除将来新增其他类型的可能，商家接入时注意兼容性避免硬编码 枚举值 全场代金券: ALIPAY_FIX_VOUCHER 折扣券: ALIPAY_DISCOUNT_VOUCHER 单品优惠券: ALIPAY_ITEM_VOUCHER 现金抵价券: ALIPAY_CASH_VOUCHER 商家全场券: ALIPAY_BIZ_VOUCHER 注意事项 不排除将来新增其他类型的可能，商家接入时注意兼容性避免硬编码

ALIPAY_FIX_VOUCHER

amount

√

必选

√

必选

√

必选

√

必选

Price

8

优惠券面额，它应该会等于商家出资加上其他出资方出资

10.00

merchant_contribute

√

可选

√

可选

√

可选

√

可选

Price

8

商家出资（特指发起交易的商家出资金额）

9.00

other_contribute

√

可选

√

可选

√

可选

√

可选

Price

8

其他出资方出资金额，可能是支付宝，可能是品牌商，或者其他方，也可能是他们的一起出资

1.00

memo

√

可选

√

可选

√

可选

√

可选

String

256

优惠券备注信息

学生专用优惠

template_id

√

可选

√

可选

√

可选

√

可选

String

64

券模板id

20171030000730015359000EMZP0

purchase_buyer_contribute

√

可选

√

可选

√

可选

√

可选

Price

8

如果使用的这张券是用户购买的，则该字段代表用户在购买这张券时用户实际付款的金额

2.01

purchase_merchant_contribute

√

可选

√

可选

√

可选

√

可选

Price

8

如果使用的这张券是用户购买的，则该字段代表用户在购买这张券时商户优惠的金额

1.03

purchase_ant_contribute

√

可选

√

可选

√

可选

√

可选

Price

8

如果使用的这张券是用户购买的，则该字段代表用户在购买这张券时平台优惠的金额

0.82

advance_amount

√

特殊可选

String

11

先享后付2.0垫资金额,不返回表示没有走垫资，非空表示垫资支付的金额

88.8

charge_flags

√

特殊可选

String

64

费率活动标识，当交易享受活动优惠费率时，返回该活动的标识； 只在机构间联模式下返回，其它场景下不返回该字段； 可能的返回值列表： bluesea_1：蓝海活动标识; industry_special_00：行业特殊费率0； industry_special_01：行业特殊费率1；

industry_special_00

auth_trade_pay_mode

√

特殊可选

√

特殊可选

String

64

预授权支付模式，该参数仅在信用预授权支付场景下返回。信用预授权支付：CREDIT_PREAUTH_PAY 枚举值 信用预授权支付: CREDIT_PREAUTH_PAY

CREDIT_PREAUTH_PAY

mdiscount_amount

√

特殊可选

√

特殊可选

√

特殊可选

√

特殊可选

String

11

商家优惠金额

88.88

discount_amount

√

特殊可选

√

特殊可选

√

特殊可选

√

特殊可选

String

11

平台优惠金额

88.88