条码支付快速接入
更新时间：2020-08-14 16:29:18
本文档展示了如何从零开始，使用支付宝开放平台服务端 SDK 快速接入当面付条码支付功能。
注意：
文档中的代码示例和 Demo 是用来阐述 API 基本使用方法的，仅针对大众场景，供 ISV（系统服务商） 参考，特殊情况还请 ISV 自行扩展，确保符合自身业务需求。
第一步：创建应用并获取 APPID
要在您的应用中接入支付宝开放平台中的能力，您需要先登录支付宝开放平台（open.alipay.com），在开发者中心中创建登记您的应用，并提交审核，审核通过后会为您生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限。通过 APPID 您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。
第二步：配置应用
添加功能
应用创建完成后，系统会自动跳转到应用详情页面。您可以在 功能列表 中点击 添加功能 来添加 当面付 功能。
配置密钥
为了保证交易双方（商户和支付宝）的身份和数据安全，开发者在调用接口前，需要配置双方密钥，对交易数据进行双方校验。密钥包含应用私钥（APP_PRIVATE_KEY）和应用公钥（APP_PUBLIC_KEY）。生成密钥后，开发者需要在开放平台开发者中心进行密钥配置，配置完成后可以获取支付宝公钥（ALIPAY_PUBLIC_KEY），配置的详细步骤请参考《配置应用环境》。您还可以通过观看 快速签名教程 学习密钥的配置。密钥的配置旨在对交易数据进行双方校验。具体流程如下图所示：
应用公钥（商户自身的 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）作为请求参数传入，商户签约完成后，可实现代商户发起请求的能力；具体方法请参考 第三方应用授权）。
第四步：接入设计
在开始开发前，您需要明确接入的方式或者所需物料等。应用接入方式分为两类：门店直连方式和商户 和 系统商后台转发 方式。
开发者可以点击下载 支付宝支付物料 或者直接进行 物料系统申请。
门店直连方式
商家收银台直接通过公网向支付宝发起收款；个人商户或者单独门店建议采用直连方式接入。具体流程如下图所示：
商户/系统商后台转发方式
商家收银台先请求到商家后台，再请求到支付宝；有多家门店的商户，大型商户, 自有商户后台的商户建议采用该方式接入。具体流程如下图所示：
安全设计
支付宝为了保证交易安全而采取的一系列安全手段以保证交易安全。点击了解 更多安全设计指南。
采用 HTTPS 协议传输交易数据，防止数据被截获，解密。
采用 RSA/RSA2 非对称密钥，明确交易双方的身份，保证交易主体的正确性和唯一性。
条码定时刷新，防止被拍照。
防止截屏（截屏后二维码失效）。
第五步：调用接口
开发者需要确认自己的应用在审核通过后显示“已上线”，同时完成当面付功能的签约后，才能顺利调用以下接口。否则会有缺少权限的报错。条码支付的调用流程如下图所示：
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
未知异常
调用查询接口确认支付结果，详见 异常处理。
关键入参：
参数名称
参数说明
out_trade_no
商户订单号，需要保证不重复
scene
条码支付固定传入 bar_code
auth_code
用户付款码，25-30 开头的长度为 16-24 位的数字，实际字符串长度以开发者获取的付款码长度为准；付款码使用一次即失效
subject
订单标题
store_id
商户门店编号
total_amount
订单金额
timeout_express
交易超时时间
关键出参：
参数名称
参数说明
trade_no
支付宝28位交易号
查询交易
关键入参：
参数名称
参数说明
out_trade_no
支付时传入的商户订单号，与 trade_no 必填一个
trade_no
支付时返回的支付宝交易号，与 out_trade_no 必填一个
关键出参：
参数名称
参数说明
trade_no
支付宝 28 位交易号
out_trade_no
支付时传入的商户订单号
trade_status
交易当前状态
撤销交易
开发者可以通过交易撤销接口 alipay.trade.cancel 撤销交易，撤销交易的时效为 24 小时。
处于创建状态的订单，在 24 小时内撤销后，这笔交易会被自动关闭；处于支付成功状态的订单，在24小时内撤销后，这笔交易会自动进行退款。
关键入参：
参数名称
参数说明
out_trade_no
支付时传入的商户订单号，与 trade_no 必填一个
trade_no
支付时返回的支付宝交易号，与 out_trade_no 必填一个
关键出参：
参数名称
参数说明
retry_flag
是否需要重试，Y/N
action
本次撤销触发的交易动作 close：关闭交易，无退款 refund：产生了退款
退款
当商户由于业务原因（如金额错误，用户退款或者对账不平等等）可能需要退款，商家可以使用 交易成功的商户订单号 或 支付宝交易号 进行退款 , 支持全额和部分退款：
退款的途径按照支付途径原路返回；
支付渠道为花呗、余额等退款即时到账；
银行卡的退款时间以银行退款时间为准，一般情况下 2 小时内可到账；
开发者也可以在商家中心（b.alipay.com）中退款；
退款是否成功可以根据同步响应的 fund_change 参数来判断，返回值为 Y 则表示退款成功；
退款接口会根据外部请求号 out_request_no 幂等返回，因此同一笔交易需要多次部分退款时，必须使用不同的 out_request_no。
退款接口 alipay.trade.refund 的调用过程如下图所示：