快速接入

本文档展示了如何从零开始,使用开放平台服务端 SDK 快速接入现金红包功能。


注意:

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


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


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


注意:

为了保证开发者的资金安全,如果您接入的应用类型为 移动应用,则需要进行 Bundle ID 校验(iOS 应用)或 应用签约 校验(安卓应用)。



Bundle ID或应用签名 获取方式如下:

  • Bundle ID :在Apple APP Store首页上,点按“我的APP”-选择需要配置的APP查看,把bundle ID   复制填入。
  • 应用签名:查看Android Studio 的最底部选项卡-点开倒数第2个选项卡“Terminal”-输入命令行keytool -list -v -keystore F:\XXXXX.jks(根据实际情况填写)-输入密钥库的口令(.jks文件的password)-把SHA1 复制填写。

第二步:配置应用

添加功能

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


配置密钥


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


bac61c43babca4e02cad34a7e1a5d652.jpg


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


说明

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


上线和签约


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

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


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


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

下载服务端 SDK


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


注意:

当前只有在 4.4.2.ALL 及以上版本的 JAVA 、4.1.0 及以上版本的 PHP 和 4.0.0及以上版本的.Net 的 SDK 才支持公钥证书签名方式,其它语言版本需要开发者 自行实现签名和验签。使用公钥证书模式的SDK需依赖下述三个JAR包:


在 PHP 语言中,请注意:

response 调用方式和普通公钥调用方式一致,仍然使用 execute() 、sdkExecute() 与 pageExecute() 。


在 .Net 语言中,请注意:

  • .Net 语言 response 的 Execute() 方法需改成 CertificateExecute();
  • sdkExecute() 与 pageExecute() 调用方式仍然与普通公钥一致。


接口调用配置


在 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根证书文件路径

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

第四步:接口调用


注意:

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


C2C 现金红包


应用于 C2C 现金红包场景:A 用户在商户的 app 上发放红包并使用支付宝 APP 支付;B 用户绑定支付宝账号后领取红包;超时未领取的红包资金原路退回 A 用户。


支付宝 app 发红包接口 alipay.fund.trans.app.pay


场景描述

在商户 APP 上集成支付宝 APP 支付 SDK,用户在商户 APP上发红包时唤起支付宝钱包进行支付。


接口调用流程



接口说明

  1. 红包支付客户端 SDK 的返回结果可用于用户交互引导,但商户服务端单据的最终的支付结果请以蚂蚁消息alipay.fund.trans.order.changed 为准;
  2. 支付宝会对发起请求的时间戳进行校验,会拒绝超过一定时间段创建的请求(会基于安全的考虑进行间隔调整);
  3. 具体接入方式可以参考以下文档:


使用 SDK 快速接入

以 JAVA 语言为例,调用 alipay.fund.trans.app.pay 支付宝 APP 发红包接口的示例代码如下:


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);
AlipayFundTransAppPayRequest request = new AlipayFundTransAppPayRequest();
request.setBizContent("{" +
"\"out_biz_no\":\"2018062800001\"," +
"\"trans_amount\":8.88," +
"\"product_code\":\"STD_RED_PACKET\"," +
"\"biz_scene\":\"PERSONAL_PAY\"," +
"\"remark\":\"拼手气红包\"," +
"\"order_title\":\"群聊拼手气红包\"," +
"\"request_time\":\"2019-06-23 19:15\"," +
"\"time_expire\":\"2018-03-23 19:15\"," +
"\"refund_time_expire\":\"2018-11-08 10:00\"," +
"\"business_params\":\"{\\\"sub_biz_scene\\\":\\\"REDPACKET\\\",\\\"payer_binded_alipay_uid:\\\"2088302510459335\\\"}\"," +
"  }");
AlipayFundTransAppPayResponse response = alipayClient.sdkExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}


关键入参


参数

字段类型最大长度是否必填

示例

参数说明

out_biz_no

String

64

2018062800001

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

trans_amount

String

16

8.88

红包金额

product_code

String

64

STD_RED_PACKET

业务产品码,固定STD_RED_PACKET

biz_scene

String

64

PERSONAL_PAY

业务场景,本场景固定PERSONAL_PAY

remark

String

200

拼手气红包

备注

order_title

String

128

钉钉拼手气红包

支付标题,支付收银台显示用,付款方在支付宝账单中可见

time_expire

String

16

2018-03-23 00:00

支付超时时间,格式为yyyy-MM-dd HH:mm。如果不传,默认30min。

refund_time_expire

String

16

2018-03-24 00:00

退款超时时间,格式 yyyy-MM-dd HH:mm。到指定时间后,系统会自动触发退款,并原路退回到付款账户。如果指定了退款时间,必须早于签约产品的最晚退款时间。

business_params

String

2048

{"sub_biz_scene":"REDPACKET","payer_binded_alipay_uid:"2088302510459335","payee_show_name":"钉钉红包"}

业务扩展字段,JSON格式。支持如下属性:

1、sub_biz_scene 子场景,必填,传REDPACKET

2、payer_binded_alipay_uid 创建红包的商户会员绑定的支付宝用户UID,必填,可通过会员授权拿到支付宝用户UID

3、payee_show_name,收款方显示名称,可选,付款方在支付宝账单中可见



关键出参


参数名称

具体类型

是否必填

最大长度

示例

描述

out_biz_no

String

64

201806300001

商户端的唯一订单号

order_id

String

32

20190703110075000006530004756875

该笔转账在支付宝系统内部的单据ID

status

String

64

SUCCESS

SUCCESS:转账成功;

WAIT_PAY:转账订单等待支付;

CLOSED:订单超时关闭;


响应示例


{
"alipay_fund_trans_app_pay_response":{
    "code":"10000",
    "msg":"Success",
"out_biz_no":"201806300001",
"order_id":"20190703110075000006530004756875",
"status":"SUCCESS"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


红包打款接口 alipay.fund.trans.uni.transfer


场景描述

B用户点击红包进行领取后,商户通过本接口向B用户的绑定支付宝账户中打款。


接口调用流程



接口说明

  1. 如果返回系统异常或未明确的错误码,请保持原始请求信息重试。
  2. 接口限制 tps 10。
  3. 商户服务器必须安装 CA 证书才可使用。


使用 SDK 快速接入

以 JAVA 语言为例,调用 alipay.fund.trans.uni.transfer 统一转账接口的示例代码如下:


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\":23.00," +
"\"product_code\":\"STD_RED_PACKET\"," +
"\"biz_scene\":\"PERSONAL_COLLECTION\"," +
"\"order_title\":\"群聊拼手气红包\"," +
"\"original_order_id\":\"20190620110075000006640000063056\"," +
"\"payee_info\":{" +
"\"identity\":\"2088123412341234\"," +
"\"identity_type\":\"ALIPAY_USER_ID\"," +
"\"name\":\"黄龙国际有限公司\"," +
"    }," +
"\"remark\":\"群聊拼手气红包\"," +
"\"business_params\":\"{\\\"sub_biz_scene\\\":\\\"REDPACKET\\\",\\\"payer_show_name\\\":\\\"钉钉红包\\\"}\"," +
"  }");
AlipayFundTransUniTransferResponse response = alipayClient.certificateExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}


关键入参


参数

字段类型

最大长度

是否必填

示例

参数说明

out_biz_no

String

64

2018062800001

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

trans_amount

String

16

6.88

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

product_code

String

64

STD_RED_PACKET

销售产品码,固定STD_RED_PACKET

biz_scene

String

64

PERSONAL_COLLECTION

业务场景,本场景固定PERSONAL_COLLECTION

original_order_id

String

64

20190703110075000006530004756875

原支付宝业务单号。C2C现金红包红包领取时,传红包支付时返回的支付宝单号;B2C现金红包不需要该参数。

payee_info

Participant


Participant类型,收款方信息

identity

String

64

2088123412341234


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

identity_type

String

64

ALIPAY_USER_ID

参与方的标识类型,目前支持如下枚举:

ALIPAY_USER_ID 支付宝的会员ID

name

String

256

参与方真实姓名,如果非空,将校验收款支付宝账号姓名一致性。

order_title



群聊拼手气红包

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

remark



群聊拼手气红包

业务备注

business_params



{"sub_biz_scene":"REDPACKET","payer_show_name":"钉钉红包"}

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

1、sub_biz_scene, 子业务场景,必传,取值REDPACKET;

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


关键出参


名称具体类型是否必填最大长度示例值描述
out_biz_noString64201808080001
商户订单号
order_idString

64

20180629110070000002040007320562
支付宝转账订单号

pay_fund_order_id

String

64

20190801110070001506380000251556

支付宝支付资金流水号

statusString32SUCCESS
转账单据状态。如 SUCCESS 表示成功


响应示例


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


红包资金退回接口 alipay.fund.trans.refund


场景描述

将剩余的未领取的红包资金退回红包发送方。


接口调用流程


接口说明

  1. 如果返回系统异常或未明确的错误码,请保持原始请求信息重试。
  2. 服务端接入方案:通过SDK集成接入,点此查看
  3. From蚂蚁消息接入说明:点此查看


使用 SDK 快速接入

以 JAVA 语言为例,调用 alipay.fund.trans.refund 资金退还接口的示例代码如下:


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();
AlipayFundTransRefundRequest request = new AlipayFundTransRefundRequest();
request.setBizContent("{" +
"\"order_id\":\"20190703110075000006530004756875\"," +
"\"out_request_no\":\"2019063050784123\"," +
"\"refund_amount\":0.15," +
"\"remark\":\"红包超时未领退回\"," +
"  }");
AlipayFundTransRefundResponse response = alipayClient.certificateExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}


关键入参


参数

字段类型

最大长度

是否必填

示例

参数说明

order_id

String

64

20190703110075000006530004756875

发红包时支付宝返回的支付宝订单号order_id。

out_request_no

String

64

2019063050784123

标识一次资金退回请求,一笔资金退回失败后重新提交,要采用原来的资金退回单号。总退款金额不能超过用户实际支付金额。

refund_amount

String

16

0.15

需要退款的金额,该金额不能大于原支付订单金额,单位为元,支持两位小数。

remark

String

200

红包超时未领退回

资金退回备注


关键出参


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

20180629110070001502040007320578

退款的支付宝系统内部单据id
order_idString64

20190703110075000006530004756875

发红包时支付宝返回的支付宝订单号order_id。
out_request_noString642019063050784123
标识一次资金退回请求,一笔资金退回失败后重新提交,要采用原来的资金退回单号。总退款金额不能超过用户实际支付金额。
statusString64SUCCESS
SUCCESS:退款成功
refund_amountString160.15
本次退款的金额,单位为元,支持两位小数
refund_dateString202019-01-01 08:08:08
退款资金退回时间

响应示例


{
"alipay_fund_trans_refund_response":{
    "code":"10000",
    "msg":"Success",
"refund_order_id":"20180629110070001502040007320578",
"order_id":"20190703110075000006530004756875",
"out_request_no":"2019063050784123",
"status":"SUCCESS",
"refund_amount":"0.15",
"refund_date":"2019-01-01 08:08:08"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


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


场景描述

查询发送红包、红包打款、红包退回订单的信息。


接口调用流程

接口说明

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 快速接入

以 JAVA 语言为例,调用 alipay.fund.trans.common.query 转账业务单据查询接口的示例代码如下:


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\":\"STD_RED_PACKET\"," +
"\"biz_scene\":\"PERSONAL_PAY\"," +
"\"out_biz_no\":\"2019063050784144\"," +
"\"order_id\":\"20190703110075000006530004756875\"" +
"  }");
AlipayFundTransCommonQueryResponse response = alipayClient.certificateExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}


关键入参


参数

字段类型

最大长度

是否必填

示例

参数说明

order_id

String

64

特殊必填

20190703110075000006530004756875

支付宝转账单据号:

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

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

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

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

pay_fund_order_id

String

64

特殊必填

20190801110070001506380000251556

支付宝支付资金流水号:

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

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

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

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

out_biz_no

String

64

特殊必填

2019063050784144

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

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

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

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

product_code

String

64

特殊必填

STD_RED_PACKET

销售产品码,固定STD_RED_PACKET,如果传了out_biz_no,则该字段必传。

biz_scene

String

64

特殊必填

PERSONAL_PAY

描述特定的业务场景,如果传递了out_biz_no则该字段为必传。可取的业务场景如下:

PERSONAL_PAY,C2C现金红包-发红包

PERSONAL_COLLECTION,C2C现金红包-领红包


关键出参


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

64

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

2019063050784144

商户订单号

pay_fund_order_id

String

64

20190801110070001506380000251556

支付宝支付资金流水号(转账成功才返回)

pay_date

String

20

2013-01-01 08:08:08

支付时间,格式为yyyy-MM-dd HH:mm:ss,转账失败不返回。

statusString64SUCCESS
转账单据状态。可能出现的状态如下:SUCCESS:转账成功;WAIT_PAY:等待支付;CLOSED:订单超时关闭


响应示例


{
"alipay_fund_trans_common_query_response":{
    "code":"10000",
    "msg":"Success",
"order_id":"20190703110075000006530004756875",
"out_biz_no":"2019063050784144",
  "pay_fund_order_id":"20190801110070001506380000251556",
  "pay_date":"2019-08-01 08:08:08",
"status":"SUCCESS",
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}



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


场景描述

单笔转账支付接口支付宝单据状态变更后触发通知。


接口调用流程


5217d18b6aae36a8caad11d7c20ade6b.png


消息参数


参数具体类型是否必填最大长度示例值描述
out_biz_noString64201806300001商户端的唯一订单号
product_codeString32STD_RED_PACKET销售产品码,商家和支付宝签约的产品码。固定值 STD_RED_PACKET:现金红包
biz_sceneString32PERSONAL_PAY描述特定的业务场景,如果传递了out_biz_no则该字段为必传。可取的业务场景如下: 1、PERSONAL_PAY,C2C现金红包-发红包; 2、PERSONAL_COLLECTION,C2C现金红包-领红包 ;3、DIRECT_TRANSFER,B2C现金红包
origin_interfaceString64alipay.fund.trans.app.pay请求来源的接口
order_idString6420190624110075000006530000014566支付宝系统的单据唯一ID
pay_fund_order_idString64

20190801110070001506380000251556

支付宝支付资金流水号(转账成功时才返回)

statusString16SUCCESS

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

SUCCESS:转账成功; WAIT_PAY:等待支付; CLOSED:订单超时关闭


alipay.fund.trans.app.pay涉及的状态: WAIT_PAY SUCCESS CLOSED alipay.fund.trans.uni.transfer、alipay.fund.trans.refund涉及的状态:SUCCESS

action_typeString32FINISH

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

CREATE-创建;

FINISH- 订单处理已完结; CLOSE-超时关闭 ;

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


响应值

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


消息示例


ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"out_biz_no":"201806300001","product_code":"STD_RED_PACKET","biz_scene":"PERSONAL_PAY","origin_interface":"alipay.fund.trans.app.pay","order_id":"20190624110075000006530000014566","pay_fund_order_id":"20190801110070001506380000251556","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)


蚂蚁消息:资金退回成功通知 alipay.fund.trans.refund.success


场景描述

资金退回成功后触发的通知


接口调用流程


5217d18b6aae36a8caad11d7c20ade6b.png


消息参数


参数具体类型是否必填最大长度示例值描述
order_idString6420190624110075000006530000014566该笔支付在支付宝系统内部的单据ID
refund_order_idString6420190625110070000006800000071477该笔退款在支付宝系统内部的单据ID
out_request_noString64refund201906270001商户请求资金退回的请求单号,支付宝会对该参数做唯一性控制
refund_amountString168.88需要退款的金额,该金额不能大于订单金额,单位为元,支持两位小数
statusString64SUCCESSSUCCESS:退款成功
refund_dateString202019-01-01 08:08:08退款完成时间


响应值

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


消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"order_id":"20190624110075000006530000014566","refund_order_id":"20190625110070000006800000071477","out_request_no":"refund201906270001","refund_amount":"8.88","status":"SUCCESS","refund_date":"2019-01-01 08:08:08"
}
&msg_method=alipay.fund.trans.refund.success&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)

B2C 现金红包


应用于B2C现金红包的场景:商户向B用户发放营销红包,B用户领取红包到自己的支付宝账户中。


发放红包


在营销等业务场景下,商户通过调用统一转账接口 alipay.fund.trans.uni.transfer 直接给用户发放红包。


接口调用流程


image.png


接入说明

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

2、接口限制 tps 10

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


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

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


使用 SDK 快速接入

以 JAVA 语言为例,调用 alipay.fund.trans.uni.transfer 统一转账接口的示例代码如下:


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\":\"STD_RED_PACKET\"," +
"\"biz_scene\":\"DIRECT_TRANSFER\"," +
"\"order_title\":\"新人注册红包\"," +
"\"payee_info\":{" +
"\"identity\":\"2088123412341234\"," +
"\"identity_type\":\"ALIPAY_USER_ID\"," +
"\"name\":\"黄龙国际有限公司\"," +
"    }," +
"\"remark\":\"新人注册红包\"," +
"\"business_params\":\"{\\\"sub_biz_scene\\\":\\\"REDPACKET\\\",\\\"payer_show_name\\\":\\\"新人红包\\\"}\"," +
"  }");
AlipayFundTransUniTransferResponse response = alipayClient.certificateExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}


关键入参


参数

字段类型

最大长度

是否必填

示例

参数说明

out_biz_no

String

64

20190619000000001

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

trans_amount

String

16

1.68

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

product_code

String

64

STD_RED_PACKET

销售产品码,固定STD_RED_PACKET

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



新人注册红包

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

remark



新人注册红包

业务备注

business_params



{"sub_biz_scene":"REDPACKET","payer_show_name":"新人红包"}

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

1、sub_biz_scene, 子业务场景,必传,取值REDPACKET;

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


关键出参


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

20190619000000001

商户订单号
order_idString

64

20190619110070000006800000025890

支付宝转账订单号

pay_fund_order_id

String

64

20190801110070001506380000251556

支付宝支付资金流水号

statusString32SUCCESS
转账单据状态。
SUCCESS:成功;


响应示例


{
"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"
}


查询红包记录


查询 B2C 红包转账订单的信息,通过 alipay.fund.trans.common.query 接口,开发者可以查询到商家发出的记录和金额等信息。


接口调用流程

接入说明

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 快速接入

以 JAVA 语言为例,调用 alipay.fund.trans.common.query 转账业务单据查询接口的示例代码如下:


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\":\"STD_RED_PACKET\"," +
"\"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("调用失败");
}


关键入参


参数

字段类型

最大长度

是否必填

示例

参数说明

order_id

String

64

特殊必填

20190619110070000006800000025890

支付宝转账单据号:

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

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

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

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

out_biz_no

String

64

特殊必填

20190619000000001

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

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

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

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

pay_fund_order_id

String

64

特殊必填

20190801110070001506380000251556

支付宝支付资金流水号:

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

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

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

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

product_code

String

64

特殊必填

STD_RED_PACKET

销售产品码,固定STD_RED_PACKET,如果传了out_biz_no,则该字段必传。

biz_scene

String

64

特殊必填

DIRECT_TRANSFER

描述特定的业务场景,如果传递了out_biz_no则该字段为必传。本场景固定传DIRECT_TRANSFER


关键出参


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

64

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

20190619000000001

商户订单号

pay_fund_order_id

String

64

20190801110070001506380000251556

支付宝支付资金流水号

(转账成功才返回)

pay_date

String

20

2013-01-01 08:08:08

支付时间,格式为yyyy-MM-dd HH:mm:ss,转账失败不返回。

statusString64SUCCESS
转账单据状态。可能出现的状态如下:SUCCESS:转账成功;WAIT_PAY:等待支付;CLOSED:订单超时关闭


响应示例


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


红包状态变更通知



通过调用 alipay.fund.trans.order.changed 接口,商户在支付宝单据状态变更后(如现金红包发放成功或者被领取后)触发的通知。


接口调用流程


更亲.png



消息参数

参数具体类型是否必填最大长度示例值描述
out_biz_noString64201806300001商户端的唯一订单号
product_codeString32STD_RED_PACKET销售产品码,商家和支付宝签约的产品码。固定值 STD_RED_PACKET:现金红包
biz_sceneString32

DIRECT_TRANSFER

描述特定的业务场景,如果传递了out_biz_no则该字段为必传。固定值:

DIRECT_TRANSFER

origin_interfaceString64

alipay.fund.trans.uni.transfer

请求来源的接口
order_idString6420190624110075000006530000014566支付宝系统的单据唯一ID
pay_fund_order_idString64

20190801110070001506380000251556

支付宝支付资金流水号(转账成功时才返回)

statusString16SUCCESS

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

SUCCESS:转账成功;

action_typeString32FINISH

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

FINISH- 订单处理已完结;

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


响应值

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


消息示例


ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"out_biz_no":"201806300001","product_code":"STD_RED_PACKET","biz_scene":"PERSONAL_PAY","origin_interface":"alipay.fund.trans.app.pay","order_id":"20190624110075000006530000014566","pay_fund_order_id":"20190801110070001506380000251556","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