首页 > 分享 > 统一收单下单并支付页面接口

统一收单下单并支付页面接口

花匠小妙招
2024-12-03 18:21

PC场景下单并支付

公共请求参数

参数类型是否必选最大长度描述示例值app_idString必选32

支付宝分配给开发者的应用ID

2014072300007148

methodString必选128

接口名称

alipay.trade.page.pay

formatString可选40

仅支持JSON

JSON

return_urlString可选256

HTTP/HTTPS开头字符串

https://m.alipay.com/Gk8NF23

charsetString必选10

请求使用的编码格式，如utf-8,gbk,gb2312等

utf-8

sign_typeString必选10

商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2

RSA2

signString必选344

商户请求参数的签名串，详见签名

详见示例

timestampString必选19

发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"

2014-07-24 03:07:50

versionString必选3

调用的接口版本，固定为：1.0

1.0

notify_urlString可选256

支付宝服务器主动通知商户服务器里指定的页面http/https路径。

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

app_auth_tokenString可选40

详见应用授权概述

biz_contentString必选

请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档

业务请求参数

展开所有属性

out_trade_no必选string(64)

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

【示例值】20150320010101001

total_amount必选price(11)

【描述】订单总金额，单位为元，精确到小数点后两位，取值范围为 [0.01,100000000]。金额不能为0。

【示例值】88.88

subject必选string(256)

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

【示例值】Iphone6 16G

product_code必选string(64)

【描述】销售产品码，与支付宝签约的产品码名称。注：目前电脑支付场景下仅支持FAST_INSTANT_TRADE_PAY

【示例值】FAST_INSTANT_TRADE_PAY

qr_pay_mode可选string(2)

【描述】PC扫码支付的方式。
支持前置模式和跳转模式。
前置模式是将二维码前置到商户的订单确认页的模式。需要商户在自己的页面中以 iframe 方式请求支付宝页面。具体支持的枚举值有以下几种：
0：订单码-简约前置模式，对应 iframe 宽度不能小于600px，高度不能小于300px；
1：订单码-前置模式，对应iframe 宽度不能小于 300px，高度不能小于600px；
3：订单码-迷你前置模式，对应 iframe 宽度不能小于 75px，高度不能小于75px；
4：订单码-可定义宽度的嵌入式二维码，商户可根据需要设定二维码的大小。
跳转模式下，用户的扫码界面是由支付宝生成的，不在商户的域名下。支持传入的枚举值有：
2：订单码-跳转模式

【枚举值】

订单码-简约前置模式: 0

订单码-前置模式: 1

订单码-迷你前置模式: 3

【示例值】1

qrcode_width可选number(4)

【描述】商户自定义二维码宽度。
注：qr_pay_mode=4时该参数有效

【示例值】100

goods_detail可选GoodsDetail[]

子属性

alipay_goods_id可选string(32)

【描述】支付宝定义的统一商品编号

【示例值】20010001

goods_category可选string(24)

categories_tree可选string(128)

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

【示例值】124868003|126232002|126252004

show_url可选string(400)

【描述】商品的展示地址

【示例值】http://www.alipay.com/xxx.jpg

time_expire可选string(32)

【描述】订单绝对超时时间。
格式为yyyy-MM-dd HH:mm:ss。超时时间范围：1m~15d。
注：time_expire和timeout_express两者只需传入一个或者都不传，两者均传入时，优先使用time_expire。

【示例值】2016-12-31 10:05:01

sub_merchant可选SubMerchant

【描述】二级商户信息。
直付通模式和机构间连模式下必传，其它场景下不需要传入。

子属性

merchant_id必选string(16)

【描述】间连受理商户的支付宝商户编号，通过间连商户入驻后得到。间连业务下必传，并且需要按规范传递受理商户编号。

【示例值】2088000603999128

merchant_type可选string(32)

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

【示例值】alipay

extend_params可选ExtendParams

子属性

sys_service_provider_id可选string(64)

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

【示例值】2088511833207846

hb_fq_seller_percent可选string(3)

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

【示例值】100

industry_reflux_info可选string(512)

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

【示例值】{"scene_code":"metro_tradeorder","channel":"xxxx","scene_data":{"asset_name":"ALIPAY"}}

specified_seller_name可选string(32)

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

【示例值】XXX的跨境小铺

royalty_freeze可选string(16)

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

【示例值】true

business_params可选string(512)

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

【示例值】{"mc_create_trade_ip":"127.0.0.1"}

promo_params可选string(512)

【描述】优惠参数。为 JSON 格式。注：仅与支付宝协商后可用

【示例值】{"storeIdType":"1"}

integration_type可选string(16)

【描述】请求后页面的集成方式。
枚举值：
ALIAPP：支付宝钱包内
PCWEB：PC端访问
默认值为PCWEB。

【枚举值】

支付宝钱包内: ALIAPP

PC端访问: PCWEB

【示例值】PCWEB

request_from_url可选string(256)

【描述】请求来源地址。如果使用ALIAPP的集成方式，用户中途取消支付会返回该地址。

【示例值】https://

store_id可选string(32)

【描述】商户门店编号。
指商户创建门店时输入的门店编号。

【示例值】NJ_001

merchant_order_no可选string(32)

【描述】商户原始订单号，最大长度限制 32 位

【示例值】20161008001

ext_user_info可选ExtUserInfo

子属性

cert_no可选string(64)

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

【示例值】362334768769238881

min_age可选string(3)

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

【示例值】18

name可选string(16)

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

【示例值】李明

mobile可选string(20)

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

【示例值】16587658765

cert_type可选string(128)

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

【枚举值】

IDENTITY_CARD: IDENTITY_CARD

PASSPORT: PASSPORT

OFFICER_CARD: OFFICER_CARD

【示例值】IDENTITY_CARD

need_check_info可选string(1)

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

【示例值】F

identity_hash可选string(128)

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

【示例值】27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc

invoice_info可选InvoiceInfo

子属性

key_info必选InvoiceKeyInfo(200)

子属性

is_support_invoice必选boolean(5)

invoice_merchant_name必选string(80)

【描述】开票商户名称：商户品牌简称|商户门店简称

【示例值】ABC|003

details必选string(400)

【描述】开票内容
注：json数组格式

【示例值】[{"code":"100294400","name":"服饰","num":"2","sumPrice":"200.00","taxRate":"6%"}]

常见请求示例

JavaC#PHPNode.js

package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradePagePayModel; import com.alipay.api.domain.ExtUserInfo; import com.alipay.api.domain.InvoiceKeyInfo; import com.alipay.api.response.AlipayTradePagePayResponse; import com.alipay.api.domain.InvoiceInfo; import com.alipay.api.request.AlipayTradePagePayRequest; import com.alipay.api.domain.ExtendParams; import com.alipay.api.domain.GoodsDetail; import com.alipay.api.domain.SubMerchant; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradePagePay { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePagePayRequest request = new AlipayTradePagePayRequest(); AlipayTradePagePayModel model = new AlipayTradePagePayModel(); // 设置商户订单号 model.setOutTradeNo("20150320010101001"); // 设置订单总金额 model.setTotalAmount("88.88"); // 设置订单标题 model.setSubject("Iphone6 16G"); // 设置产品码 model.setProductCode("FAST_INSTANT_TRADE_PAY"); // 设置PC扫码支付的方式 model.setQrPayMode("1"); // 设置商户自定义二维码宽度 model.setQrcodeWidth(100L); // 设置订单包含的商品列表信息 List<GoodsDetail> goodsDetail = new ArrayList<GoodsDetail>(); GoodsDetail goodsDetail0 = new GoodsDetail(); goodsDetail0.setGoodsName("ipad"); goodsDetail0.setAlipayGoodsId("20010001"); goodsDetail0.setQuantity(1L); goodsDetail0.setPrice("2000"); goodsDetail0.setGoodsId("apple-01"); goodsDetail0.setGoodsCategory("34543238"); goodsDetail0.setCategoriesTree("124868003|126232002|126252004"); goodsDetail0.setShowUrl("http://www.alipay.com/xxx.jpg"); goodsDetail.add(goodsDetail0); model.setGoodsDetail(goodsDetail); // 设置订单绝对超时时间 model.setTimeExpire("2016-12-31 10:05:01"); // 设置二级商户信息 SubMerchant subMerchant = new SubMerchant(); subMerchant.setMerchantId("2088000603999128"); subMerchant.setMerchantType("alipay"); model.setSubMerchant(subMerchant); // 设置业务扩展参数 ExtendParams extendParams = new ExtendParams(); extendParams.setSysServiceProviderId("2088511833207846"); extendParams.setHbFqSellerPercent("100"); extendParams.setHbFqNum("3"); extendParams.setIndustryRefluxInfo("{"scene_code":"metro_tradeorder","channel":"xxxx","scene_data":{"asset_name":"ALIPAY"}}"); extendParams.setSpecifiedSellerName("XXX的跨境小铺"); extendParams.setRoyaltyFreeze("true"); extendParams.setCardType("S0JP0000"); model.setExtendParams(extendParams); // 设置商户传入业务信息 model.setBusinessParams("{"mc_create_trade_ip":"127.0.0.1"}"); // 设置优惠参数 model.setPromoParams("{"storeIdType":"1"}"); // 设置请求后页面的集成方式 model.setIntegrationType("PCWEB"); // 设置请求来源地址 model.setRequestFromUrl("https://"); // 设置商户门店编号 model.setStoreId("NJ_001"); // 设置商户的原始订单号 model.setMerchantOrderNo("20161008001"); // 设置外部指定买家 ExtUserInfo extUserInfo = new ExtUserInfo(); extUserInfo.setCertType("IDENTITY_CARD"); extUserInfo.setCertNo("362334768769238881"); extUserInfo.setName("李明"); extUserInfo.setMobile("16587658765"); extUserInfo.setMinAge("18"); extUserInfo.setNeedCheckInfo("F"); extUserInfo.setIdentityHash("27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc"); model.setExtUserInfo(extUserInfo); // 设置开票信息 InvoiceInfo invoiceInfo = new InvoiceInfo(); InvoiceKeyInfo keyInfo = new InvoiceKeyInfo(); keyInfo.setTaxNum("1464888883494"); keyInfo.setIsSupportInvoice(true); keyInfo.setInvoiceMerchantName("ABC|003"); invoiceInfo.setKeyInfo(keyInfo); invoiceInfo.setDetails("[{"code":"100294400","name":"服饰","num":"2","sumPrice":"200.00","taxRate":"6%"}]"); model.setInvoiceInfo(invoiceInfo); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePagePayResponse response = alipayClient.pageExecute(request, "POST"); // 如果需要返回GET请求，请使用 // AlipayTradePagePayResponse response = alipayClient.pageExecute(request, "GET"); String pageRedirectionData = response.getBody(); System.out.println(pageRedirectionData); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } }

说明：本示例仅供参考。

业务响应参数

pageRedirectionData｜跳转页面数据必选string(16384)

【描述】用于跳转支付宝页面的信息，POST和GET方法生成内容不同：使用POST方法执行，结果为html form表单，在浏览器渲染即可；使用GET方法会得到支付宝URL，需要打开或重定向到该URL。建议使用POST方式。具体使用方法请参考接入指南

【示例值】请参考响应示例

响应示例

<form name="punchout_form" method="post" action="https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.page.pay&format=json&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&app_id=2017060101317939&sign_type=RSA2&timestamp=2014-07-24+03%3A07%3A50"> <input type="hidden" name="biz_content" value="{"time_expire":"2016-12-31 10:05:01","extend_params":"","query_options":"["hyb_amount","enterprise_pay_info"]","settle_info":"","subject":"Iphone6 16G","product_code":"FAST_INSTANT_TRADE_PAY","body":"Iphone6 16G","qr_pay_mode":"1","integration_type":"PCWEB","merchant_order_no":"20161008001","sub_merchant":"","invoice_info":"","ext_user_info":"","timeout_express":"90m","disable_pay_channels":"pcredit,moneyFund,debitCardExpress","agreement_sign_params":"","royalty_info":"","store_id":"NJ_001","request_from_url":"https://","qrcode_width":"100","goods_detail":"","enable_pay_channels":"pcredit,moneyFund,debitCardExpress","out_trade_no":"20150320010101001","total_amount":"88.88","business_params":"{"mc_create_trade_ip":"127.0.0.1"}","promo_params":"{"storeIdType":"1"}"}"> <input type="submit" value="立即支付" style="display:none" > </form> <script>document.forms[0].submit();</script>

说明：本示例仅供参考。

公共错误码

前往查看

业务错误码

错误码错误描述解决方案ACQ.ACCESS_FORBIDDEN无权限使用接口

未签约条码支付或者合同已到期

ACQ.BUYER_BALANCE_NOT_ENOUGH买家余额不足

买家绑定新的银行卡或者支付宝余额有钱后再发起支付

ACQ.BUYER_BANKCARD_BALANCE_NOT_E用户银行卡余额不足

建议买家更换支付宝进行支付或者更换其它付款方式

ACQ.BUYER_ENABLE_STATUS_FORBID买家状态非法

用户联系支付宝小二点这里画板，确认买家状态为什么非法

ACQ.BUYER_PAYMENT_AMOUNT_DAY_LIM买家付款日限额超限

更换买家进行支付

ACQ.BUYER_PAYMENT_AMOUNT_MONTH_L买家付款月额度超限

买家更换账号后，重新付款或者更换其它付款方式

ACQ.BUYER_SELLER_EQUAL买卖家不能相同

更换买家重新付款

ACQ.CONTEXT_INCONSISTENT交易信息被篡改

更换商家订单号后，重新发起请求

ACQ.ERROR_BALANCE_PAYMENT_DISABL余额支付功能关闭

用户打开余额支付开关后，再重新进行支付

ACQ.ERROR_BUYER_CERTIFY_LEVEL_LI买家未通过人行认证

用户联系支付宝小二点这里画板

ACQ.EXIST_FORBIDDEN_WORD订单信息中包含违禁词

修改订单信息后，重新发起请求

ACQ.ILLEGAL_SIGN_VALIDTY_PERIOD无效的签约有效期

更改接口中传入的签约有效期

ACQ.INVALID_PARAMETER参数无效

检查请求参数，修改后重新发起请求

ACQ.MERCHANT_AGREEMENT_NOT_EXIST商户协议不存在

建议商户与支付宝确认签约代扣合同

ACQ.NO_PAYMENT_INSTRUMENTS_AVAIL没用可用的支付工具

更换其它付款方式

ACQ.PARTNER_ERROR应用APP_ID填写错误

联系支付宝小二点这里画板，确认APP_ID的状态

ACQ.PAYMENT_FAIL支付失败

用户刷新条码后，重新发起请求，如果重试一次后仍未成功，更换其它方式付款

ACQ.PAYMENT_REQUEST_HAS_RISK支付有风险

更换其它付款方式

ACQ.RISK_MERCHANT_IP_NOT_EXIST当前交易未传入IP信息，创单失败，请传入IP后再发起支付

检查请求参数是否已经传入用户IP信息

ACQ.SYSTEM_ERROR接口返回错误

请立即调用查询订单API，查询当前订单的状态，并根据订单状态决定下一步的操作，如果多次调用依然报此错误码，请联系支付宝客服。

ACQ.TOTAL_FEE_EXCEED订单总金额不在允许范围内

修改订单金额再发起请求

ACQ.TRADE_BUYER_NOT_MATCH交易买家不匹配

更换商家订单号后，重新发起请求

ACQ.TRADE_HAS_CLOSE交易已经关闭

更换商家订单号后，重新发起请求

ACQ.TRADE_HAS_SUCCESS交易已被支付

确认该笔交易信息是否为当前买家的，如果是则认为交易付款成功，如果不是则更换商家订单号后，重新发起请求

触发通知类型

通知类型描述默认开启tradeStatus.TRADE_CLOSED交易关闭0tradeStatus.TRADE_FINISHED交易完结0tradeStatus.TRADE_SUCCESS支付成功1tradeStatus.WAIT_BUYER_PAY交易创建0

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&merchant_app_id=2088102146225135&buyer_open_id=074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5&fund_bill_list=null&receipt_amount=null&invoice_amount=null&buyer_pay_amount=null&point_amount=null&voucher_detail_list=null&passback_params=null&out_channel_type=null&trade_no=null&app_id=null&out_trade_no=null&out_biz_no=null&buyer_id=null&seller_id=null&trade_status=null&total_amount=null&refund_fee=null&subject=null&body=null&gmt_create=null&gmt_payment=null&gmt_refund=null&gmt_close=null&buyer_logon_id=180****0062&charge_amount=8.88&charge_flags=bluesea_1&settlement_id=2018101610032004620239146945&receipt_currency_type=DC&hyb_amount=10.24&enterprise_pay_info={"invoice_amount":"28.00","is_use_enterprise_pay":"true"}