快速接入

本文档展示了如何从零开始,使用开放平台服务端 SDK 快速接入单笔转账到账户功能。

注意:

文档中的代码示例和 Demo 是用来阐述 API 基本使用方法,仅针对普适场景,供开发者参考,特殊情况还请开发者自行扩展,确保符合自身业务需求。


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


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


第二步:配置应用

添加功能


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

配置密钥


为了保证交易双方(商户和支付宝)的身份和数据安全,开发者在调用接口前,需要配置双方密钥,对交易数据进行双方校验。由于单笔转账到账户产品涉及到资金转账接口,为了保障资金安全,开放平台要求开发者使用“公钥证书”模式配置密钥并调用接口。开发者通过开放平台工具生成密钥并完成配置后,可以获取应用私钥、应用公钥证书、支付宝公钥证书、支付宝根证书文件。开发者务必妥善保管私钥及证书文件不泄露,切勿将私钥以明文保存在系统代码中密钥的配置旨在对交易数据进行校验,具体流程如下图所示:


bac61c43babca4e02cad34a7e1a5d652.jpg


  • 应用公钥证书: 支付宝使用该公钥证书验证该交易是商户发起。
  • 支付宝公钥证书:商户使用该公钥证书验证该结果是支付宝返回的。


说明

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


上线和签约


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

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


详细步骤可以参考 签约功能


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

下载服务端 SDK


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

注意:

公钥证书模式的 SDK 目前只支持 JAVA 、PHP和.NET语言(请使用最新版本),其它语言版本需要开发者自行实现签名和验签。使用公钥证书模式的JAVA版SDK需依赖下述三个JAR包:

  • bcprov-jdk15on-1.62.jar
  • fastjson-1.2.50.jar
  • commons-logging-1.1.1.jar


接口调用配置


在 SDK 调用前需要进行初始化(下述为JAVA语言示例代码),alipayClient对象初始化完成后,开发者就可以用 alipayClient 来调用具体的 API 了。alipayClient 只需要初始化一次,后续调用不同的 API 都可以使用同一个 alipayClient 对象。

try{
CertAlipayRequest certAlipayRequest = new CertAlipayRequest();
certAlipayRequest.setServerUrl(gateway);
certAlipayRequest.setAppId(app_id);
certAlipayRequest.setPrivateKey(app_privateKey);
certAlipayRequest.setFormat("json");
certAlipayRequest.setCharset(charset);
certAlipayRequest.setSignType(sign_type);
certAlipayRequest.setCertPath(app_cert_path);
certAlipayRequest.setAlipayPublicCertPath(alipay_cert_path);
certAlipayRequest.setRootCertPath(alipay_root_cert_path);
DefaultAlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
//todo 构建request内容
XXXRequest request = new XXXRequest();
//
xxxResponse response =  alipayClient.certificateExecute(request);
}catch (Exception e){
  //
}


CertAlipayRequest关键属性说明:

属性名称

示例值解释

获取方式/示例值

ServerUrl

支付宝网关地址(固定)

https://openapi.alipay.com/gateway.do

AppId

APPID 即创建应用后生成

详情见创建应用并获取 APPID

PrivateKey

开发者应用私钥,由开发者自己生成

详见配置密钥

Format

参数返回格式,只支持 json 格式

json(固定)

Charset

请求和签名使用的字符编码格式,支持 GBK和 UTF-8

开发者根据实际工程编码配置

SignType

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

RSA2

CertPath

开发者应用公钥证书路径

证书存放路径由开发者自定义,程序需对该路径有读权限。证书获取详见开放平台证书升级指南

AlipayPublicCertPath

支付宝公钥证书文件路径

证书存放路径由开发者自定义,程序需对该路径有读权限。证书获取详见开放平台证书升级指南

RootCertPath

支付宝CA根证书文件路径

证书存放路径由开发者自定义,程序需对该路径有读权限。证书获取详见开放平台证书升级指南

第四步:接口调用

注意:支付宝将来可能会对接口、消息做优化升级,即新增接口、消息的返回参数,开发者的系统逻辑需要兼容此类升级。

单笔转账至支付宝接口 alipay.fund.trans.uni.transfer

场景描述

请求发起方将他的支付宝账户中的资金转账给收款方支付宝账户中。

调用流程

image.png



image.png

关键入参

参数

字段类型

最大长度

是否必填

示例

参数说明

out_biz_no

String

64

20190619000000001

商户端的唯一订单号,对于同一笔转账请求,商户需保证该订单号唯一。

trans_amount

String

16

1.68

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

product_code

String

64

TRANS_ACCOUNT_NO_PWD

销售产品码,单笔无密转账固定为TRANS_ACCOUNT_NO_PWD

biz_scene

String

64

DIRECT_TRANSFER

业务场景,单笔无密转账固定为DIRECT_TRANSFER

payee_info

Participant


Participant类型,收款方信息

└ identity

String

64

2088123412341234


参与方的标识ID,比如支付宝用户UID。

└ identity_type

String

64

ALIPAY_USER_ID

参与方的标识类型,目前支持如下枚举:1、ALIPAY_USER_ID 支付宝的会员ID

2、ALIPAY_LOGON_ID:支付宝登录号,支持邮箱和手机号格式

└ name

String

256

参与方真实姓名,如果非空,将校验收款支付宝账号姓名一致性。当identity_type=ALIPAY_LOGON_ID时,本字段必填。若传入该属性,则在支付宝回单中将会显示这个属性

order_title



201905代发

转账业务的标题,用于在支付宝用户的账单里显示。

remark



201905代发

业务备注

business_params



{\"payer_show_name\":\"YBpre-B2C单笔\",\"sub_merchant_info\":\"{\\\"subMerchantName\\\":\\\"测试企业名称\\\",\\\"subMerchantMCC\\\":\\\"12345\\\"}\"}

转账业务请求的扩展参数,支持传入的扩展参数如下:

1、payer_show_name,付款方显示名称,可选,收款方在支付宝账单中可见;

2、sub_merchant_info为二级商户信息,可选,对应值为json字符串,subMerchantName是二级商户企业名称,subMerchantMCC是二级商户MCC行业码

关键出参

名称具体类型是否必填最大长度示例值描述
out_biz_noString64

20190619000000001

商户订单号
order_idString

64

20190619110070000006800000025890

支付宝转账订单号

pay_fund_order_id

String

64

20190801110070001506380000251556

支付宝支付资金流水号
statusString32SUCCESS
转账单据状态。
SUCCESS:成功;

trans_date

String

32

2019-08-21 00:00:00

订单支付时间,格式为yyyy-MM-dd HH:mm:ss

接入说明

1、如果返回系统异常或未明确的错误码,请保持原始请求信息重试。

2、接口限制tps为10

3、商户服务器必须安装CA证书才可使用


服务端接入方案:通过SDK集成接入,点此查看

From蚂蚁消息接入说明:点此查看

SDK调用

请求示例


CertAlipayRequest certAlipayRequest = new CertAlipayRequest();
certAlipayRequest.setServerUrl(gateway);
certAlipayRequest.setAppId(app_id);
certAlipayRequest.setPrivateKey(app_privateKey);
certAlipayRequest.setFormat("json");
certAlipayRequest.setCharset(charset);
certAlipayRequest.setSignType(sign_type);
certAlipayRequest.setCertPath(app_cert_path);
certAlipayRequest.setAlipayPublicCertPath(alipay_cert_path);
certAlipayRequest.setRootCertPath(alipay_root_cert_path);
DefaultAlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
AlipayFundTransUniTransferRequest request = new AlipayFundTransUniTransferRequest();
request.setBizContent("{" +
"\"out_biz_no\":\"201806300001\"," +
"\"trans_amount\":1.68," +
"\"product_code\":\"TRANS_ACCOUNT_NO_PWD\"," +
"\"biz_scene\":\"DIRECT_TRANSFER\"," +
"\"order_title\":\"201905代发\"," +
"\"payee_info\":{" +
"\"identity\":\"2088123412341234\"," +
"\"identity_type\":\"ALIPAY_USER_ID\"," +
"\"name\":\"黄龙国际有限公司\"," +
"    }," +
"\"remark\":\"201905代发\"," +
"\"business_params\":\"{\\\"payer_show_name\\\":\\\"服务代理\\\"}\"," +
"  }");
AlipayFundTransUniTransferResponse response = alipayClient.certificateExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}


响应示例


{
"alipay_fund_trans_uni_transfer_response":{
    "code":"10000",
    "msg":"Success",
  "out_biz_no":"201808080001",
  "order_id":"20190619110070000006800000025890",
  "pay_fund_order_id":"20190801110070001506380000251556",
  "status":"SUCCESS"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


单据查询接口 alipay.fund.trans.common.query

场景描述

查询单笔转账至支付宝账户的订单信息

调用流程

关键入参

参数

字段类型

最大长度

是否必填

示例

参数说明

order_id

String

64

特殊必填

20190619110070000006800000025890

支付宝转账单据号:

本参数和商户转账唯一订单号、支付宝支付资金流水号三者不能同时为空。

当本参数和商户转账唯一订单号、支付宝支付资金流水号三者同时提供时,将用支付宝支付资金流水号进行查询,忽略其余两者;

当本参数和支付宝支付资金流水号同时提供时,将用支付宝支付资金流水号进行查询,忽略本参数。

当本参数和商户转账唯一订单号同时提供时,将用本参数进行查询,忽略商户转账唯一订单号。

pay_fund_order_id

String

64

特殊必填

20190801110070001506380000251556

支付宝支付资金流水号:

本参数和支付宝转账单据号、商户转账唯一订单号三者不能同时为空。

当本参数和支付宝转账单据号、商户转账唯一订单号同时提供时,将用本参数进行查询,忽略本参数;

当本参数和支付宝转账单据号同时提供时,将用本参数进行查询,忽略支付宝转账单据号;

当本参数和商户转账唯一订单号同时提供时,将用本参数进行查询,忽略商户转账唯一订单号;

out_biz_no

String

64

特殊必填

20190619000000001

商户转账唯一订单号:发起转账来源方定义的转账单据ID。

本参数和支付宝转账单据号、支付宝支付资金流水号三者不能同时为空。

当本参数和支付宝转账单据号、支付宝支付资金流水号同时提供时,将用支付宝支付资金流水号进行查询,忽略本参数;

当本参数和支付宝转账单据号同时提供时,将用支付宝转账单据号进行查询,忽略本参数;

product_code

String

64

特殊必填

TRANS_ACCOUNT_NO_PWD

销售产品码如果传了out_biz_no,则该字段必传。单笔无密转账固定为TRANS_ACCOUNT_NO_PWD

biz_scene

String

64

特殊必填

DIRECT_TRANSFER

描述特定的业务场景,如果传递了out_biz_no则该字段为必传。。单笔无密转账固定为DIRECT_TRANSFER


关键出参

名称具体类型是否必填最大长度示例值描述
order_idString

64

20190703110075000006530004756875
支付宝转账单据号,
查询失败不返回。

pay_fund_order_id

String

64

20190801110070001506380000251556

支付宝支付资金流水号,
转账失败不返回。
out_biz_noString64

20190619000000001

商户转账唯一订单号
pay_dateString


2013-01-01 08:08:08支付时间,格式为yyyy-MM-dd HH:mm:ss,转账失败不返回。
statusString64SUCCESS
转账单据状态。
可能出现的状态如下:
SUCCESS:转账成功

接入说明

1、查询入参out_biz_no、order_id与pay_fund_order_id三者不可同时为空,三者优先级为pay_fund_order_id>order_id>out_biz_no,高优先级与低优先级参数同时给出时,用高优先级参数查询,忽略低优先级参数;

2、使用out_biz_no查询时,必须传product_code和biz_scene。


SDK调用

请求示例


CertAlipayRequest certAlipayRequest = new CertAlipayRequest();
certAlipayRequest.setServerUrl(gateway);
certAlipayRequest.setAppId(app_id);
certAlipayRequest.setPrivateKey(app_privateKey);
certAlipayRequest.setFormat("json");
certAlipayRequest.setCharset(charset);
certAlipayRequest.setSignType(sign_type);
certAlipayRequest.setCertPath(app_cert_path);
certAlipayRequest.setAlipayPublicCertPath(alipay_cert_path);
certAlipayRequest.setRootCertPath(alipay_root_cert_path);
DefaultAlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
AlipayFundTransCommonQueryRequest request = new AlipayFundTransCommonQueryRequest();
request.setBizContent("{" +
"\"product_code\":\"TRANS_ACCOUNT_NO_PWD\"," +
"\"biz_scene\":\"DIRECT_TRANSFER\"," +
"\"out_biz_no\":\"20190619000000001\"," +
"\"order_id\":\"20190619110070000006800000025890\"" +
"  }");
AlipayFundTransCommonQueryResponse response = alipayClient.certificateExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}


响应示例


{
"alipay_fund_trans_common_query_response":{
    "code":"10000",
    "msg":"Success",
"order_id":"20190619110070000006800000025890",
"pay_fund_order_id":"20190801110070001506380000251556",
"out_biz_no":"20190619000000001",
"pay_date":"2013-01-01 08:08:08",
"status":"SUCCESS",
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


账户余额查询接口alipay.fund.account.query

场景描述

查询请求发起方的支付宝账户余额

调用流程

image.png

关键入参

参数

字段类型

最大长度

是否必填

示例

参数说明

alipay_user_id

String

18

208818457777488333

蚂蚁统一会员ID

account_type

String

30

ACCTRANS_ACCOUNT

查询的账号类型,固定值为ACCTRANS_ACCOUNT

关键出参

名称具体类型是否必填最大长度示例值描述

available_amount

String

15

26.45

账户可用余额。
单位为元,
精确到小数点后两位

接入说明

1、alipay_user_id必须等于请求发起方的pid;

2、alipay_user_id、account_type必填,且account_type取固定值ACCTRANS_ACCOUNT

SDK调用

请求示例
CertAlipayRequest certAlipayRequest = new CertAlipayRequest();
certAlipayRequest.setServerUrl(gateway);
certAlipayRequest.setAppId(app_id);
certAlipayRequest.setPrivateKey(app_privateKey);
certAlipayRequest.setFormat("json");
certAlipayRequest.setCharset(charset);
certAlipayRequest.setSignType(sign_type);
certAlipayRequest.setCertPath(app_cert_path);
certAlipayRequest.setAlipayPublicCertPath(alipay_cert_path);
certAlipayRequest.setRootCertPath(alipay_root_cert_path);
DefaultAlipayClient alipayClient = new DefaultAlipayClient(certAlipayRequest);
AlipayFundAccountQueryRequest request = new AlipayFundAccountQueryRequest();
request.setBizContent("{" +
"\"alipay_user_id\":\"208818457777488333\"," +
"\"account_type\":\"ACCTRANS_ACCOUNT\"" +
"  }");
AlipayFundAccountQueryResponse response = alipayClient.certificateExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}


响应示例


{
"alipay_fund_account_query_response":{
    "code":"10000",
    "msg":"Success",
"available_amount":"26.45"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


蚂蚁消息:转账单据状态变更通知 alipay.fund.trans.order.changed

场景描述

用于转账单据状态变更后触发的通知

调用流程

image.png

消息参数

参数具体类型是否必填最大长度示例值描述
out_biz_noString64201806300001商户端的唯一订单号
product_codeString32

TRANS_ACCOUNT_NO_PWD

销售产品码,商家和支付宝签约的产品码。单笔无密转账固定为TRANS_ACCOUNT_NO_PWD
biz_sceneString32

DIRECT_TRANSFER

描述特定的业务场景,

单笔无密转账固定为

DIRECT_TRANSFER

origin_interfaceString64

alipay.fund.trans.uni.transfer

请求来源的接口
pay_fund_order_idString6420190801110070001506380000251556支付宝支付资金流水号
order_idString6420190624110075000006530000014566

支付宝转账单据号

statusString16SUCCESS

转账单据状态。可能出现的状态如下:

SUCCESS:转账成功;

action_typeString32FINISH

资金订单的操作类型,取值如下:

FINISH- 订单处理已完结;

trans_amountString2032.00转账金额
pay_dateString202013-01-01 08:08:08支付完成时间

响应值

响应值描述是否重试
fail消息获取失败重试
success消息获取成功不重试

消息示例


ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"pay_fund_order_id":"20190801110070001506380000251556","out_biz_no":"201806300001","product_code":"TRANS_ACCOUNT_NO_PWD","biz_scene":"PERSONAL_PAY","origin_interface":"alipay.fund.trans.app.pay","order_id":"20190624110075000006530000014566","status":"SUCCESS","action_type":"FINISH","trans_amount":"32.00","pay_date":"2013-01-01 08:08:08"
}
&msg_method=alipay.fund.trans.order.changed&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==


消息验签

在公钥证书模式下,支付宝开放平台 SDK 提供了 AlipaySignature.rsaCertCheckV1 方法,可以使用该方法对通知报文验签。


/**
@param params 参数列表(包括待验签参数和签名值sign) key-参数名称 value-参数值
@param alipayPublicCertPath 验签支付宝公钥证书路径
@param charset 验签字符集
**/
boolean AlipaySignature.rsaCertCheckV1(Map<String, String> params, String alipayPublicCertPath, String charset)


onlineServer