AliPay支付宝标准快速付款接口文档专用纯网关V151.docx

AliPay支付宝标准快速付款接口文档专用纯网关V151.docx

《AliPay支付宝标准快速付款接口文档专用纯网关V151.docx》由会员分享，可在线阅读，更多相关《AliPay支付宝标准快速付款接口文档专用纯网关V151.docx（32页珍藏版）》请在冰豆网上搜索。

AliPay支付宝标准快速付款接口文档专用纯网关V151

纯网关接口文档

副标题：

网银直连

修订历史

版本号

作者

修订章节

修订原因

修订日期

V1.0

技术支持团队

全版修改

加强文档结构的合理性

2008-11-17

V1.1

甘宁

订正部分接口参数和描述信息，例如：

即时支付支持错误通知地址（error_notify_url）

更新签约接口容

接口升级、增加查询签约接口

2009-8-2

V1.2

甘宁

重新整理流程以及文档说明

使文档阅读性更强

2009-12-8

V1.3

甘宁

增加“公用回传参数”

满足用户自定义参数的要求

2010-3-18

V1.4

甘宁

通知中增加网银流水

满足商户网银支付需求

2010-3-29

V1.5

甘宁

请求参数列表

支持自定义超时可以使用时间区间

2010-9-13

V1.5.1

甘宁

增加4.3.2的信用卡简码

信用卡大额支付也支持纯网关

2010-10-26

说明：

本接口将支付宝即时到帐接口用作纯网关的功能做详细介绍。

在集成时处理机制和原有支付宝即时到帐一样，请求时必须增加默认支付方式（paymethod）和默认网银（defaultbank）2个参数

1前言

1.1概述

本接口主要用在外部集成网银直连（纯网关）功能

1.2术语

名称

说明

外部商户、合作伙伴、商户

和支付宝进行业务合作的商户

通知页

参数名称Notify_url，所指定的互联网HTTP地址，当代扣完成之后，支付宝发送信息到该页面去，即调用该页面，该页面中的程序自动运行，并判断请求与处理获取到的信息

合作伙伴ID

签约后，为商家自动分配的唯一编号。

分润

分润指将某一部分费用分给其它的

页面跳转

执行操作后跳转到其它页面

2接口功能及参数介绍

2.1标准即时到账接口（适用于纯网银）

2.1.1功能描述

调用此接口，根据用户传过来的参数创建交易，买家再付款。

目前该接口的交易全部为即时到帐纯网银支付接口，即只要买家一付款，钱就会从买家银行卡转到卖家的支付宝账号。

同时该接口还支持分润，商家传过来分润的账号和金额，系统会自动打款到该账号上。

2.1.2交互流程

2.1.3交互模式

请求/响应交互模式，页面跳转

2.1.4接口详细说明

2.1.4.1请求参数列表

特别注意：

a.）此接口只支持https请求，支付宝是以https进行验证

b.）按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收。

c.）本接口支持重复调用，但是提交数据必须一样才可以。

d.）在请求时必须增加默认支付方式和默认网银2个参数

协议参数

接口名称

service

String

create_direct_pay_by_user

N

合作伙伴ID

partner

String（16）

合作伙伴在支付宝的用户ID与支付宝签约后自动生成

N

通知URL

notify_url

URL（String（190））

针对该交易的交易状态同步通知接收URL。

N

返回URL

return_url

URL

结果返回URL，仅适用于立即返回处理结果的接口。

支付宝处理完请求后，立即将处理结果返回给这个URL。

N

错误通知地址

（需要支付宝功能人员开通）

error_notify_url

URL（String（190））

如果在交易过程中出错（如签名错误等），则通过此URL将错误码返回给合作伙伴系统

Y

签名

sign

String

见签名机制，MD5加密算法后得出的结果

N

签名方式

sign_type

String

见签名方式，现今默认是MD5加密，无需更改该参数的值

N

参数编码字符集

_input_charset

String（默认为GBK）

合作伙伴系统与支付宝系统之间交互信息时使用的编码字符集。

合作伙伴可以通过该参数指定使用何种字符集对传递参数进行编码。

同时，支付宝系统也会使用该字符集对返回参数或通知参数进行编码。

注：

该参数必须在queryString中传递，不论使用的是POST还是GET方式发送请求。

如：

.alipay./cooperate/gateway.do?

_input_charset=utf-8

N

业务参数

商品展示网址

show_url

String（400）

点击商品后跳转的页面

Y

商品名称

subject

String（256）

商品的标题

N

商品描述

body

String（1000）

商品的具体描述，如果是多种商品，请将商品描述字符串累加传给body

Y

外部交易号

out_trade_no

String（64）

合作伙伴交易号（确保在合作伙伴系统中唯一）

N

商品单价

price

Number（13,2）

price:

单位为RMBYuan0.01～100000000.00

total_fee:

单位为RMBYuan

0.01～100000000.00

quantity:

0

规则：

1.如果是多个商品可以汇总后传入，这个时候商品数量默认为1

2.总价和单价不可以同时出现

3.如果使用总价total_fee，则数量为quantity=1.

3.如果使用单价price，则商品数量quantity传递实际商品数量

N

交易金额

total_fee

Number（13,2）

购买数量

quantity

Number（6,0）

支付类型

payment_type

String（4）

默认为：

1（商品购买）；

N

默认支付方式

paymethod

String

bankPay（网银）

N

默认网银

defaultbank

String

见常见银行列表

N

卖家Email

seller_email

String（100）

卖家在支付宝的注册Email或注册ID，两者任何一个。

N

卖家ID

seller_id

String（16）

提成类型

royalty_type

String

（2）

目前只支持一种类型：

卖家给第三方提成（目前参数=10）

Y

提成信息集

royalty_parameters

String（500）

信息格式下面两种都可：

1、收款方Email_1^金额^备注|付款方Email^收款方Email_2^金额^备注

2、收款方Email_1^金额^备注|收款方Email_2^金额^备注

3.（属于多级分润）收款方Email_1^金额^备注|收款方Email_1^收款方Email_2^金额^备注

如有多条则用“|”隔开，最多不能超过10条，备注最多1000个字符，即500个汉字，详见“接口注意事项”

Y

超时时间

it_b_pay

String（3）

商户开通自定义超时功能才有用（支付宝控制权限），定义该交易的超时时间，m表示分钟，h表示小时，d表示天，c表示当天。

商户如果需要改功能，需要告知配置的时间点或者区间，有支付宝技术支持配置。

例如：

1m~15d表示在1分钟和15天之任何一个时间都可以。

备注：

默认15d关闭交易。

当天理论上是当天的0点后关闭，但是由于是定时任务可能有所延迟。

Y

公用回传参数

extra_common_param

String（200）

用于商户回传参数,该值不能包含=&等

特殊字符。

如果用户请求时传递了该参

数，则返回给商户时会回传该参数.

Y

一个完整的支付接入请例：

https:

//.alipay./cooperate/gateway.do?

body=支付宝支付&defaultbank=CMB¬ify_url=

2.1.4.2返回参数列表

此接口有两种返回方式：

注意：

选择具体网银支付方法，进入网银支付页面后才能创建交易，支付完成才返回通知。

需要强调的是部分网银可能不支持支付完成及时跳转，所以商户最好在异步通知中做数据处理或者2个返回处理都集成，增加订单重复接受即可

A.（同步通知）：

系统根据执行的结果将相关订单信息返回（只做返回不需要商户和支付宝系统交互）

输出参数列表

基本信息

是否成功

is_success

String

（1）

表示该次操作是否成功

N

签名

sign

String（32）

见HTTP参数签名机制,

该参数需要获取做签名校验。

N

签名类型

sign_type

String

见签名方式

N

业务参数

接口名称

exterface

String

使用支付宝的服务接口名称，用此参数可以确定是支付宝的服务

Y

通知时间

notify_time

Timestamp

通知时间（支付宝时间），格式：

YYYY-MM-DDhh:

mm:

ss

Y

通知ID

notify_id

String

支付宝通知流水号，合作伙伴可以用这个流水号询问支付宝该条通知的合法性

Y

通知类型

notify_type

String

trade_status_sync

Y

支付宝交易号

trade_no

String（16）

该交易在支付宝系统中的交易流水号

Y

支付类型

payment_type

String（4）

值为1：

商品购买

Y

外部交易号

out_trade_no

String（64）

该交易商户提交给支付宝的的交易流水号

Y

商品描述

body

String（400）

商品描述

Y

商品名称

subject

String（256）

商品名称

Y

总价

total_fee

Number（13,2）

总价

Y

买家Email

buyer_email

String（100）

买家Email

Y

买家ID

buyer_id

String（30）

买家ID

Y

卖家Email

seller_email

String（100）

卖家Email

Y

卖家ID

seller_id

String（30）

卖家ID

Y

交易状态

trade_status

String

见交易状态枚举表

Y

公用回传参数

extra_common_param

String

用于商户回传参数,该值不能包含=&等

特殊字符。

如果用户请求时传递了该参

数，则返回给商户时会回传该参数.

Y

网银流水号

bank_seq_no

String（20）

开通了纯网关和伪网关的商户，在交易成功后可以返回网银流水。

其他不返回该值。

Y

B.异步通知（即notify_url通知）：

支付宝系统根据商户传入的notify_url,定时通知执行结果返回给商户，若通知后没有获取商户返回的success支付宝会重复多次执行通知。

输出参数列表

通知类型

notify_type

String

trade_status_sync

N

通知ID

notify_id

String

支付宝通知流水号，合作伙伴可以用这个流水号询问支付宝该条通知的合法性

N

通知时间

notify_time

Timestamp

通知时间（支付宝时间），格式：

YYYY-MM-DDhh:

mm:

ss

N

签名

sign

String

见签名机制,

该参数需要获取做签名校验。

N

签名方式

sign_type

String

见签名方式

N

订单信息：

支付宝交易号

trade_no

String（16）

该交易在支付宝系统中的交易流水号

Y

外部交易号

out_trade_no

String（64）

该交易在合作伙伴系统的流水号

Y

折扣

discount

Number（13,2）

Y

支付类型

payment_type

String（4）

1

Y

商品名称

subject

String（256）

Y

商品描述

body

String（400）

Y

商品单价

price

Number（13,2）

单位为RMBYuan

0.01～100000000.00

Y

购买数量

quantity

Number（6,0）

>0

Y

交易金额

total_fee

Number（13,2）

单位为RMBYuan

0.01～1000000.00

Y

是否调整总价

is_total_fee_adjust

String

（1）

该交易是否调整过价格

Y

交易创建时间

gmt_create

Timestamp

该笔交易创建的时间

Y

交易付款时间

gmt_payment

Timestamp

该交易买家的付款时间

Y

交易关闭时间

gmt_close

Timestamp

交易关闭时间

Y

退款时间

gmt_refund

Timestamp

卖家退款的时间，退款通知时会发送

Y

公用回传参数

extra_common_param

String

用于商户回传参数,该值不能包含=&等

特殊字符。

如果用户请求时传递了该参

数，则返回给商户时会回传该参数.

Y

网银流水号

bank_seq_no

String（20）

开通了纯网关和伪网关的商户，在交易

成功后可以返回网银流水。

备注：

需要支付宝技术支持人员开启

Y

交易状态信息：

交易状态

trade_status

String

见交易状态枚举表

Y

退款状态

refund_status

String

见交易状态枚举表

Y

买家卖家信息：

卖家Email

seller_email

String（100）

卖家Email

Y

卖家ID

seller_id

String（30）

卖家ID

Y

买家ID

buyer_id

String（30）

买家Email

Y

买家Email

buyer_email

String（100）

买家ID

Y

是否使用红包

use_coupon

String

（1）

买家是否在交易过程中使用了红包

Y

错误通知参数信息（需要在传入参数增加错误通知地址）：

错误代码

error_code

String（

说明接口调用过程中的出错信息

N

2.1.5接口注意事项

●您需使用HTTPS协义,支付宝是以HTTPS的形式进行通知

●请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收

●该接口支持重复调用，即：

一笔订单可以重新支付，但是前提是这笔订单的信息和原来信息一样，否则会报订单号重复

●处理支付宝的返回信息可以异步处理也可以同步处理，前提是防止订单重复接收

●提成数据集：

1.收款方Email_1^金额^备注|付款方Email^收款方Email_2^金额^备注

例如：

gwl251163.^0.02^分润1|gwl251126.^gwl061163.^0.01^分润2

2.收款方Email_1^金额^备注|收款方Email_2^金额^备注

例如：

gwl251163.^0.02^分润1|gwl061163.^0.01^分润2

3.收款方Email_1^金额^备注|收款方Email_1^收款方Email_2^金额^备注

例如：

gwl251163.^0.02^分润1|gwl251163.^gwl061163.^0.01^分润2

2.1.6接口错误代码列表

ILLEGAL_SIGN

签名验证出错

ILLEGAL_ARGUMENT

参数不正确

HAS_NO_PRIVILEGE

没有权限访问该服务

ILLEGAL_SERVICE

Service参数不正确

ILLEGAL_PARTNER

商户ID不正确

HAS_NO_PUBLICKEY

没有上传公钥

USER_NOT_EXIST

会员不存在

OUT_TRADE_NO_EXIST

外部交易号已经存在

TRADE_NOT_EXIST

交易不存在

ILLEGAL_PAYMENT_TYPE

无效支付类型，需要联系支付宝技术支持工程师处理

BUYER_NOT_EXIST

买家不存在

SELLER_NOT_EXIST

卖家不存在

BUYER_SELLER_EQUAL

买家、卖家是同一

ILLEGAL_SIGN_TYPE

签名类型不正确

COMMISION_ID_NOT_EXIST

佣金收取不存在

COMMISION_SELLER_DUPLICATE

收取佣金和卖家是同一

COMMISION_FEE_OUT_OF_RANGE

佣金金额超出围

ILLEGAL_LOGISTICS_FORMAT

无效物流格式

TOTAL_FEE_LESSEQUAL_ZERO

交易总金额小于等于0

TOTAL_FEE_OUT_OF_RANGE

交易总金额超出围

ILLEGAL_FEE_PARAM

非法交易金额格式（参考单价、总价、数量三个组合规则）

DONATE_GREATER_THAN_MAX

小额捐赠总金额超出最大值限制

DIRECT_PAY_AMOUNT_OUT_OF_RANGE

快速付款交易总金额超出最大值限制

DIGITAL_FEE_GREATER_THAN_MAX

虚拟物品交易总金额超出最大值限制

SELF_TIMEOUT_NOT_SUPPORT

不支持自定义超时

COMMISION_NOT_SUPPORT

不支持佣金

VIRTUAL_NOT_SUPPORT

不支持虚拟发货方式

ILLEGAL_CHARSET

字符集不合法

ROYALTY_SELLER_ENABLE_STATUS_FORBID

有提成情况下，卖家状态不正常

ROYALTY_SELLER_NOT_CERTIFY

有提成情况下，卖家未通过认证

ROYALTY_FORAMT_ERROR

提成信息错误，请检查后重新集成

ROYALTY_TYPE_ERROR

提成类型不支持，请检查后重新集成

ROYALTY_PAY_EMAIL_NOT_EXIST

提成付款不存在

ROYALTY_RECEIVE_EMAIL_NOT_EXIST

提成收款不存在

DEFAULT_BANK_MUST_NOT_NULL

默认网银不能为空

LLEGAL_PAYMENT_TYPE

错误的Payment_type参数

ILLEGAL_OUTTIME_ARGUMENT

自定义超时参数错误

CANT_CREDIT_PAY

不能使用信用支付

TRADE_NOT_ALLOWED_PAY

交易不允许付款

NAVIGATION_INCOME_OF_ROYALTY_ACCOUNT

在提成情况下的多级分润，二次分润次序问题或者分润时没有预留支付宝服务费

3签名通用策略

3.1安全方面CheckList

a从集成后的系统健壮性考虑，收到支付宝发出的通知后，合作伙伴系统须判断接收到的交易状态、交易金额是否与自己系统中的参数对应，并处理这些数据信息，使的交易信息与支付宝的交易信息保持一致，可防止掉单情况出现。

如果不判断，存在潜在的风险，合作伙伴自行承担因此而产生的所有损失。

3.2签名方面

3.2.1签名机制

a没有值的参数无需传递，也无需包含到待签名数据中。

b签名时将字符转变成字节流时指定的字符集要与_input_charset保持一致。

c如果传递了_input_charset参数，那么这个参数也应该包含在待签名数据中。

d根据HTTP协议要求，传递参数的值中如果存在特殊字符（如：

&、等），那么该值需要做URLEncoding，这样请求接受方才能接受到正确的参数值。

这种情况下，做签名时使用的应该是原生值而不是encoding之后的值。

例如：

会员查询接口示例中待签名数据是email=testmsn.&partner=00000&service=test，而不是email=test%40msn.&partner=00000&service=test。

3.2.24.2.2签名方式

按照sign_type参数指定的签名算法对待签名数据进行签名【参见：

数字签名构造】

3.3其他方面

1）您必需使用HTTPS协义,支付宝是以HTTPS的形式进行通知

2）请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收

3）如果设置了notify_url，支付宝会发一条通知到notify_url对应的站点

4）通知URL不要如此设置：

.xxx./alipay/notify_url.asp?

id=xxx，即不要带自加的自定义参数，这会导致通知返回时判断失败。

4附录

4.1接口通用机制

4.1.1系统调用

顾名思义，这类接口是为合作伙伴系统获得支付宝系统信息提供服务的，是一种系统间的调用接口。

系统调用示意图

4.1.2页面跳转

顾名思义，这类接口都是一些有页面操作的接口。

通常是用户在合作伙伴页面执行部分操作，然后跳转到支付宝系统记录订单信息及时再转入网银系统页面完成整个操作。

有的甚至可能最后还要再跳回到合作伙伴的下一个页面，继续完成整个操作。

根据处理结果的返回方式，又分为：

⏹立即返回处理结果，即用户在网银系统页面完成操作后，支付宝将处理结果立即返回给合作伙伴的下一步操作页面，让用户继续完成真个操作流程。

所以，调用这类接口时，必须传递参数return_url（即合作伙伴的下一个操作页面）。

立即返回（页面跳转）示意图

⏹异步返回处理结果，即用户从合作伙伴页面跳转到网银支付页面后（支付宝先做记录），在网银系统完成最后操作，用户不用再回到合作作伙伴页面。

这类接口通常是通过通知接口异步获得处理结果。

如果需要异步返回结果，那么必须传递notify_url参数，以指定通知返回的地址。

如果不需要异步返回结果，那么可以不用传递notify_url参数。

（具体流程可以参考：

支付宝主动通知处理流程）

页面跳转（通过通知接口返回结果）示意图

4.1.3支付宝主动通知处理流程

1.支付宝平台系统向外部商户系统发出通知，即访问外部商户提供的通知接收URL（参数notify_url）。

2.外部商户系统接到通知请求，通过notify