新零售支付全家桶


付款码支付接口文档

第一步:创建应用并获取 APPID

要在您的应用中接入支付宝开放平台中的能力,您需要先登录支付宝开放平台(open.alipay.com),在开发者中心中创建登记您的应用,并提交审核,审核通过后会为您生成应用唯一标识(APPID),并且可以申请开通开放产品使用权限。通过 APPID 您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》

第二步:配置应用

添加功能

应用创建完成后,系统会自动跳转到应用详情页面。您可以在 功能列表 中点击 添加功能 来添加 当面付 功能。

配置密钥

为了保证交易双方(商户和支付宝)的身份和数据安全,开发者在调用接口前,需要配置双方密钥,对交易数据进行双方校验。密钥包含应用私钥(APP_PRIVATE_KEY)和应用公钥(APP_PUBLIC_KEY)。生成密钥后,开发者需要在开放平台开发者中心进行密钥配置,配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY),配置的详细步骤请参考《配置应用环境》。您还可以通过观看 快速签名教程 学习密钥的配置。密钥的配置旨在对交易数据进行双方校验。具体流程如下图所示:

img

  • 应用公钥(商户自身的 RSA/RSA2 公钥): 支付宝使用该公钥验证该交易是商户发起。
  • 支付宝公钥(支付宝的 RSA/RSA2 公钥):商户使用该公钥验证该结果是支付宝返回的。

说明

支付宝开放平台 SDK 封装了签名和验签过程,只需配置账号及密钥参数,建议开发者使用。开发者还可以通过 自助排查流程验签教程 自助排查配置应用过程中遇到的问题。

上线和签约

开发者在添加功能和配置密钥后,即可将应用提交审核,预计会有一个工作日的审核时间,请耐心等待,详细步骤可参考 上线应用

应用上线完成后,要使用当面付功能,您还需要完成签约。当面付功能需要签约才能生效,请点击功能列表右侧 签约,提交相关信息;完成签约后,需要一个工作日左右的时间审核(审批结果会以短信和邮件形式告知),待审核完毕后,功能的状态会变成“已生效”,您的应用即可使用当面付功能。

详细步骤可以参考 签约功能,第三方应用可以 代替商户签约。当面付除了可以在开放平台签约外,还支持在 支付宝商家中心 签约。

第三步:搭建和配置开发环境

下载服务端 SDK

为了帮助开发者调用开放接口,我们提供了开放平台服务端 SDK,包含 JAVA、PHP、Python、NodeJS 和 .NET五种语言版本,封装了签名、验签和 HTTP 接口请求等基础功能。请先下载对应语言版本的 SDK 并引入您的开发工程。

接口调用配置

在 SDK 调用前需要进行初始化,以 JAVA 代码为例:

AlipayClient   alipayClient   =   new   DefaultAlipayClient ( URL ,  APP_ID ,  APP_PRIVATE_KEY ,  FORMAT ,  CHARSET ,  ALIPAY_PUBLIC_KEY ,  SIGN_TYPE );

关键参数说明:

配置参数 示例值解释 获取方式/示例值
URL 支付宝网关(固定) https://openapi.alipay.com/gateway.do
APP_ID APPID 即创建应用后生成 详情见 第一步:创建应用并获取 APPID
APP_PRIVATE_KEY 开发者应用私钥,由开发者自己生成 详见 第二步:配置应用 > 配置密钥
FORMAT 参数返回格式,只支持 json 格式 json(固定)
CHARSET 请求和签名使用的字符编码格式,支持 GBK 和 UTF-8 开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY 支付宝公钥,由支付宝生成 详见 第二步:配置应用 > 配置密钥
SIGN_TYPE 商户生成签名字符串所使用的签名算法类型,目前支持 RSA2 和 RSA,推荐商家使用 RSA2。 RSA2

接下来,开发者就可以用 alipayClient 来调用具体的 API 了。alipayClient 只需要初始化一次,后续调用不同的 API 都可以使用同一个 alipayClient 对象。

注意:

ISV/开发者可以通过“第三方应用授权”得到商户授权令牌(app_auth_token)作为请求参数传入,商户签约完成后,可实现代商户发起请求的能力;具体方法请参考 第三方应用授权)。

第四步:接入设计

在开始开发前,您需要明确接入的方式或者所需物料等。应用接入方式分为两类:门店直连方式和商户系统商后台转发 方式。

开发者可以点击下载 支付宝支付物料 或者直接进行 物料系统申请

门店直连方式

商家收银台直接通过公网向支付宝发起收款;个人商户或者单独门店建议采用直连方式接入。具体流程如下图所示:

img

商户/系统商后台转发方式

商家收银台先请求到商家后台,再请求到支付宝;有多家门店的商户,大型商户, 自有商户后台的商户建议采用该方式接入。具体流程如下图所示:

img

安全设计

支付宝为了保证交易安全而采取的一系列安全手段以保证交易安全。点击了解 更多安全设计指南

  • 采用 HTTPS 协议传输交易数据,防止数据被截获,解密。
  • 采用 RSA/RSA2 非对称密钥,明确交易双方的身份,保证交易主体的正确性和唯一性。
  • 条码定时刷新,防止被拍照。
  • 防止截屏(截屏后二维码失效)。

第五步:调用接口

开发者需要确认自己的应用在审核通过后显示“已上线”,同时完成当面付功能的签约后,才能顺利调用以下接口。否则会有缺少权限的报错。条码支付的调用流程如下图所示:

img

a. 创建交易并支付(如图,1-1.1.3 步所示)。

b. 根据返回的结果,确定支付状态,从而进行相应处理(包括必要时关闭交易), 如图 opt 区块中所示,第 2 步表示支付成功, 返回支付成功页。

c. 第 3 步表示返回的参数为待用户付款(code=10003)或者系统异常(code=20000)、网络超时等场景下处理方式。

d. 第 4 步表示轮询结束仍未处理成功,需要撤销订单。

e. 第 5 步表示返回支付失败(code=40004) 时, 需要重新检查参数,重新发起支付。

更多请参考 异常处理

支付

商家系统将用户付款码与订单信息一起通过 统一收单交易支付接口(条码支付)alipay.trade.pay 请求到支付宝,并从接口同步返回中获取支付结果。根据公共返回参数中的code,这笔交易可能有四种状态:支付成功(10000),支付失败(40004),等待用户付款(10003)和未知异常(20000)。

结果码 说明 处理方式
10000 支付成功 记录交易结果并在客户端显示支付成功,进入后续的业务处理。
40004 支付失败 记录交易结果并在客户端显示错误信息(display_message)。
10003 等待用户付款 发起轮询流程:等待 5 秒后调用 交易查询接口 alipay.trade.query。 通过支付时传入的商户订单号(out_trade_no)查询支付结果(返回参数 TRADE_STATUS ),如果仍然返回等待用户付款(WAIT_BUYER_PAY),则再次等待5秒后继续查询,直到返回确切的支付结果(成功 TRADE_SUCCESS 或 已撤销关闭TRADE_CLOSED),或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下,必须立即调用 交易撤销接口 alipay.trade.cancel 将这笔交易撤销,避免用户继续支付。
20000 未知异常 调用查询接口确认支付结果,详见 异常处理

以 JAVA 语言为例,统一收单交易支付接口(条码支付)alipay.trade.pay 接入代码如下:

AlipayClient   alipayClient   =   new   DefaultAlipayClient ( "https://openapi.alipay.com/gateway.do" ,  APP_ID ,  APP_PRIVATE_KEY ,  "json" ,  CHARSET ,  ALIPAY_PUBLIC_KEY ,  "RSA2" );  //获得初始化的AlipayClient 
 AlipayTradePayRequest   request   =   new   AlipayTradePayRequest ();  //创建API对应的request类 
 request . setBizContent ( "{"   + 
 "    \"out_trade_no\":\"20150320010101001\","   + 
 "    \"scene\":\"bar_code\","   + 
 "    \"auth_code\":\"28763443825664394\","   + //即用户在支付宝客户端内出示的付款码,使用一次即失效,需要刷新后再去付款 
 "    \"subject\":\"Iphone6 16G\","   + 
 "    \"store_id\":\"NJ_001\","   + 
 "    \"timeout_express\":\"2m\","   + 
 "    \"total_amount\":\"88.88\""   + 
 "  }" );  //设置业务参数 
 AlipayTradePayResponse   response   =   alipayClient . execute ( request );  //通过alipayClient调用API,获得对应的response类 
 System . out . print ( response . getBody ());
 // 根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
out_trade_no 商户订单号,需要保证不重复
scene 条码支付固定传入 bar_code
auth_code 用户付款码,25-30 开头的长度为 16-24 位的数字,实际字符串长度以开发者获取的付款码长度为准;付款码使用一次即失效
subject 订单标题
store_id 商户门店编号
total_amount 订单金额
timeout_express 交易超时时间

关键出参:

参数名称 参数说明
trade_no 支付宝28位交易号

查询交易

以 JAVA 语言为例,交易查询接口 alipay.trade.query 接入代码如下:

AlipayClient   alipayClient   =   new   DefaultAlipayClient ( "https://openapi.alipay.com/gateway.do" ,  APP_ID ,  APP_PRIVATE_KEY ,  "json" ,  CHARSET ,  ALIPAY_PUBLIC_KEY ,  "RSA2" );  //获得初始化的AlipayClient 
 AlipayTradeQueryRequest   request   =   new   AlipayTradeQueryRequest (); //创建API对应的request类 
 request . setBizContent ( "{"   + 
 "    \"out_trade_no\":\"20150320010101001\","   + 
 "    \"trade_no\":\"2014112611001004680073956707\"}" );  //设置业务参数 
 AlipayTradeQueryResponse   response   =   alipayClient . execute ( request ); //通过alipayClient调用API,获得对应的response类 
 System . out . print ( response . getBody ());
 //根据response中的结果继续业务逻辑处理

关键入参:

参数名称 参数说明
out_trade_no 支付时传入的商户订单号,与 trade_no 必填一个
trade_no 支付时返回的支付宝交易号,与 out_trade_no 必填一个

关键出参:

参数名称 参数说明
trade_no 支付宝 28 位交易号
out_trade_no 支付时传入的商户订单号
trade_status 交易当前状态

页面列表

ITEM_HTML