1
- [文档说明](./1) - [产品介绍](./2) - [支付流程和用户体验](./3) - [快速接入](./4) - [交互流程](./5) - [客户端调用](./6) - [iOS](./6) - [Android](./7) - [集成流程详解](./11) - [iOS](./12) - [导入代码](./12#ImportCode) - [针对Demo的运行注意](./12#RunDemo) - [配置基本信息](./12#Configuration) - [代码示例运行逻辑](./12#CodeLogic) - [Android](./13) - [导入开发资源](./13#AndroidImportResource) - [修改Manifest](./13#ModifyManifest) - [添加混淆规则](./13#AddRules) - [订单数据生成](./13#GenOrder) - [支付接口调用](./13#CallPay) - [支付结果获取和处理](./13#PayResultHandling) - [获取当前开发包版本号](./13#GetSDKVersion) - [接口列表](./8) - [mobile.securitypay.pay](./8) - [请求参数](./8) - [同步通知参数说明](./9#SynchronousResponseParameters) - [服务器异步通知参数说明](./10#ServerAsynchronousNotificationParameters) - [错误码](./14) - [退款接口](./21) - [请求参数](./21#Request) - [同步返回](./21#Response) - [示例](./21#Samples) - [错误码](./22#Errors) - [单笔查询接口](./23) - [请求参数](./23#QueryRequest) - [同步返回](./23#QueryResponse) - [示例](./23#QuerySamples) - [错误码](./24#Errors) - [对账文件下载接口](./25) - [请求参数](./25#Forex_compare_file_Request) - [同步返回](./25#Forex_compare_file_Response) - [示例](./25#Forex_compare_file_Samples) - [错误码](./26) - [结算文件下载接口](./27) - [请求参数](./27#Forex_liquidation_file_Request) - [同步返回](./27#Forex_liquidation_file_Response) - [示例](./27#Forex_liquidation_file_Samples) - [错误码](./28) - [境外二级线上商户报备接口](./37) - [请求参数](./37#request) - [同步返回](./37#sync) - [示例](./37#samples) - [错误码](./37#error) - [汇率查询接口](./29) - [请求参数](./29#Forex_rate_file_Request) - [同步返回](./29#Forex_rate_file_Response) - [示例](./29#Forex_rate_file_Samples) - [错误码](./30) - [异步通知验证接口](./31) - [请求参数](./31#Notify_verify_Request) - [同步返回](./31#Notify_verify_Response) - [示例](./31#Notify_verify_Samples) - [错误码](./32) - [数字签名](./15) - [签名机制](./15) - [生成待签名的字符串](./15#SignatureString) - [签名](./15#SignatureGen) - [使用OpenSSL来产生RSA密钥](./16) - [OpenSSL安装](./16#OpenSSLInstallation) - [RSA密钥对的产生](./16#RSAKeyPairGeneration) - [FAQ](./17) - [国际商户服务网站](./17) - [支持的币种列表](./18) - [分账明细说明](./19) - [退款分账明细说明](./33) - [资源下载](./20) - [支付宝对账文件](./34) - [关于支付宝账单](./34) - [获取账单](./35) - [API](./35#API) - [支付宝国际网站](./35#Global) - [SFTP](./35#SFTP) - [账单详细内容](./36) - [交易文件](./36#TransactionFile) - [结算文件](./36#SettlementFile)
新境外收单 - SDK

文档说明

English Docs

阅读对象


支付宝境外收单移动支付交易创建接口技术文档面向具有一定Android/iOS客户端开发能力,了解Android/iOS客户端的开发和管理人员。

惯例


本文档用到了下面的描述:
说明: 说明包含了成功集成该支付方案的有用建议和重要信息。

联系我们


任何技术问题,请联系支付宝国际技术支持团队.
任何非技术问题,如如何与支付宝签约,请联系支付宝国际业务团队 .

名词解释


1.   请求
手机客户端以字符串形式把需要传输的数据发送给接收方的过程。
2.   返回
支付宝以字符串形式直接把处理结果数据返回给手机客户端。
3.   通知
服务器异步通知。支付宝根据得到的数据处理完成后,支付宝的服务器主动发起通知给商户的网站,同时携带处理完成的结果信息反馈给商户网站。
4.   H5支付
浏览器或者App内嵌的Webview中展示H5页面,并完成支付。
5.   Native支付
唤起支付宝App,展示支付宝App内的Native页面,并完成支付。

 

生成待签名的字符串

需要参与签名的参数

在请求参数列表中,除去sign、sign_type两个参数外,其他需要使用到的参数皆是要签名的参数。(个别接口中参数sign_type也需要参与签名。)
在通知返回参数列表中,除去sign、sign_type两个参数外,凡是通知返回回来的参数皆是要签名的参数。

生成待签名字符串

对于如下的参数数组:

string[] parameters={
  "service=create_forex_trade",
  "partner=2088101568338364",
  "_input_charset=gbk",
  "return_url= http://www.test.com/alipay/return_url.asp",
  "out_trade_no=6741334835157966",
  "subject=test",
  "payment_type=1 ",
  "seller_email=alipay-test01@alipay.com",
  "total_fee=100"
  };
  
对数组里的每一个值从a到z的顺序排序,若遇到相同首字母,则看第二个字母,以此类推。
排序完成之后,再把所有数组值以“&”字符连接起来,如:

_input_charset=gbk&out_trade_no=6741334835157966&partner=2088101568338364&payment_type=1&return_url=http://www.test.com/alipay/return_url.asp&seller_email=alipay-test01@alipay.com&service=create_direct_pay_by_user&subject=贝尔金护腕式&total_fee=100

这串字符串便是待签名字符串。
  • 没有值的参数无需传递,也无需包含到待签名数据中;
  • 签名时将字符转化成字节流时指定的字符集与_input_charset保持一致;
  • 如果传递了_input_charset参数,这个参数也应该包含在待签名数据中;
  • 根据HTTP协议要求,传递参数的值中如果存在特殊字符(如:&、@等),那么该值需要做URL Encoding,这样请求接收方才能接收到正确的参数值。这种情况下,待签名数据应该是原生值而不是encoding之后的值。例如:调用某接口需要对请求参数email进行数字签名,那么待签名数据应该是email=test@msn.com,而不是email=test%40msn.com。

签名

MD5签名

在MD5签名时,需要支付宝安全校验码(Key)参与签名。安全校验码(Key)是以英文字母和数字组成的32位字符串。
商户可登录到商户服务中心(https://global.alipay.com),查询PID和Key。

当拿到请求时的待签名字符串后,需要把安全校验码(Key)直接拼接到待签名字符串后面,形成新的字符串,利用MD5的签名函数对这个新的字符串进行签名运算,从而得到32位签名结果字符串(该字符串赋值于参数sign)。

当获得到通知返回时的待签名字符串后,同理,需要把安全校验码(Key)直接拼接到待签名字符串后面,形成新的字符串,利用MD5的签名函数对这个新的字符串进行签名运算,从而得到32位签名结果字符串。此时这个新的字符串需要与支付宝通知返回参数中的参数sign的值进行验证是否相等,来判断签名是否验证通过。

DSA, RSA签名

在DSA或RSA的签名时,需要私钥和公钥一起参与签名。私钥与公钥皆是客户通过OPENSSL来生成得出的。客户把生成出的公钥与支付宝技术人员配置好的支付宝公钥做交换。因此,在签名时,客户要用到的是客户的私钥及支付宝的公钥。

当拿到请求时的待签名字符串后,把待签名字符串与客户的私钥一同放入DSA或RSA的签名函数中进行签名运算,从而得到签名结果字符串。

当获得到通知返回时的待签名字符串后,把待签名字符串、支付宝提供的公钥、支付宝通知返回参数中的参数sign的值三者一同放入DSA或RSA的签名函数中进行非对称的签名运算,来判断签名是否验证通过。

OpenSSL安装

可以在官网下载 https://www.openssl.org/source/.

RSA密钥对的产生

对于Java开发人员,需要去掉pkcs8密钥里面的开头和结尾的注释,回车和空格。对于.Net和PHP开发人员,不需要做pkcs8的操作
操作完成后,在当前目录下会产生两个文件rsaprivatekey.pem和rsapublickey.pem. 前面一个是私钥文件,后面一个是公钥文件。商家需要保留私钥文件,同时为了签名和验签,需要跟支付宝交换公钥。下面是密钥对的示例。

-----BEGIN RSA  PRIVATE KEY-----MIICXQIBAAKBgQC+L0rfjLl3neHleNMOsYTW8r0QXZ5RVb2p/vvY3fJNNugvJ7lo4+fdBz+LN4mDxTz4MTOhi5e2yeAqx+v3nKpNmPzC5LmDjhHZURhwbqFtIpZD51mOfno2c3MDwlrsVi6mTypbNu4uaQzw/TOpwufSLWF7k6p2pLoVmmqJzQiD0QIDAQABAoGAakB1risquv9D4zX7hCv9MTFwGyKSfpJOYhkIjwKAik7wrNeeqFEbisqv35FpjGq3Q1oJpGkem4pxaLVEyZOHONefZ9MGVChT/MNH5b0FJYWl392RZy8KCdq376Vt4gKVlABvaV1DkapL+nLh7LMo/bENudARsxD55IGObMU19lkCQQDwHmzWPMHfc3kdY6AqiLrOss+MVIAhQqZOHhDe0aW2gZtwiWeYK1wB/fRxJ5esk1sScOWgzvCN/oGJLhU3kipHAkEAysNoSdG2oWADxlIt4W9kUiiiqNgimHGMHPwp4JMxupHMTm7D9XtGUIiDijZxunHv3kvktNfWj3Yji0661zHVJwJBAM8TDf077F4NsVc9AXVs8N0sq3xzqwQD/HPFzfq6hdR8tVY5yRMb4X7+SX4EDPORKKsgnYcur5lk8MUi7r072iUCQQC8xQvUne+fcdpRyrR4StJlQvucogwjTKMbYRBDygXkIlTJOIorgudFlrKP/HwJDoY4uQNl8gQJb/1LdrKwIe7FAkBl0TNtfodGrDXBHwBgtN/t3pyi+sz7OpJdUklKE7zMSBuLd1E3O4JMzvWP9wEE7JDb+brjgK4/cxxUHUTkk592-----END RSA  PRIVATE KEY-----
-----BEGIN PRIVATE  KEY-----MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAN0yqPkLXlnhM+2H/57aHsYHaHXazr9pFQun907TMvmbR04wHChVsKVgGUF1hC0FN9hfeYT5v2SXg1WJSg2tSgk7F29SpsF0I36oSLCIszxdu7ClO7c22mxEVuCjmYpJdqb6XweAZzv4Is661jXP4PdrCTHRdVTU5zR9xUByiLSVAgMBAAECgYEAhznORRonHylm9oKaygEsqQGkYdBXbnsOS6busLi6xA+iovEUdbAVIrTCG9t854z2HAgaISoRUKyztJoOtJfI1wJaQU+XL+U3JIh4jmNx/k5UzJijfvfpT7Cv3ueMtqyAGBJrkLvXjiS7O5ylaCGuB0Qz711bWGkRrVoosPM3N6ECQQD8hVQUgnHEVHZYtvFqfcoq2g/onPbSqyjdrRu35a7PvgDAZx69Mr/XggGNTgT3jJn7+2XmiGkHM1fd1Ob/3uAdAkEA4D7aE3ZgXG/PQqlm3VbE/+4MvNl8xhjqOkByBOY2ZFfWKhlRziLEPSSAh16xEJ79WgY9iti+guLRAMravGrs2QJBAOmKWYeaWKNNxiIoF7/4VDgrcpkcSf3uRB44UjFSn8kLnWBUPo6WV+x1FQBdjqRviZ4NFGIP+KqrJnFHzNgJhVUCQFzCAukMDV4PLfeQJSmna8PFz2UKva8fvTutTryyEYu+PauaX5laDjyQbc4RIEMU0Q29CRX3BA8WDYg7YPGRdTkCQQCG+pjU2FB17ZLuKRlKEdtXNV6zQFTmFc1TKhlsDTtCkWs/xwkoCfZKstuV3Uc5J4BNJDkQOGm38pDRPcUDUh2/-----END PRIVATE  KEY-----
-----BEGIN PUBLIC  KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQWiDVZ7XYxa4CQsZoB3n7bfxLDkeGKjyQPt2FUtm4TWX9OYrd523iw6UUqnQ+Evfw88JgRnhyXadp+vnPKP7unormYQAfsM/CxzrfMoVdtwSiGtIJB4pfyRXjA+KL8nIa2hdQy5nLfgPVGZN4WidfUY/QpkddCVXnZ4bAUaQjXQIDAQAB-----END PUBLIC  KEY-----

如何上传商家公钥

请联系支付宝国际技术支持(overseas_support@service.alibaba.com),帮助上传公钥。

商户可以在支付宝国际网站上进行退款,查询交易和下载对账文件等的操作:

Abbreviation

Currency

Decimal Number

AUD

澳元

2

CAD

加拿大元

2

CHF

瑞士法郎

2

DKK

丹麦克朗

2

EUR

欧元

2

GBP

英镑

2

HKD

港币

2

JPY

日元

0

KRW

韩元

0

NOK

挪威克朗

2

NZD

新西兰元

2

SEK

瑞典克朗

2

SGD

新币

2

THB

泰铢

2

USD

美元

2

分账明细参数为json格式,包含以下参数:

参数

类型(字节长度)

参数说明

是否可为空

样例

transIn

String

接受分账资金的支付宝账户ID。
以2088开头的纯16位数字。

不可空

2088101126708402

amount

String

分账的金额。格式必须符合相应币种的要求,比如:日元为整数,人民币最多2位小数。当分账币种是CNY时,此金额代表的是人民币;如果分账币种是外币时,此金额则是外币。但分账商户实际收到的金额始终是人民币,如果分账明细中是外币,分账商户得到的人民币实际是通过汇率进行计算得到的。数值(小数点后最多2位)

不可空

0.10

currency

String

分账币种。如果total_fee不为空,则分账币种必须是外币,且与结算币种一致;如果rmb_fee不为空,则分账币种必须是人民币。人民币填写“CNY”,外币请参见“币种列表”。

不可空

USD

desc

String

分账描述信息。

可空

分账测试1

格式结构:
[
{入账支付宝用户号:入账支付宝用户号1, 分账金额:分账金额1,分账币种:分账币种1, 分账描述:分账描述1}
,
{入账支付宝用户号:入账支付宝用户号2, 分账金额:分账金额2,分账币种:分账币种2, 分账描述:分账描述2}
,

]
示例:

参数赋值:
split_fund_info=[{"transIn":"2088101126708402","amount":"0.10","currency":"USD","desc":"  Split _test1"},{"transIn":"2088101126707869","amount":"0.10","currency":"USD","desc":"Split_test2"}]

商户可以使用这个单笔退款接口来操作退款.

请求参数

参数

类型 (长度是字节)

描述

可选

示例

基本参数

service

String

接口名称

N

forex_refund

partner

String(16)

境外商户在支付宝的用户ID. 2088开头的16位数字

N

2088001159940003

_input_charset

String

请求数据的编码集,支持UTF-8。

N

UTF-8

sign_type

String

签名算法 DSA, RSA, and MD5.

N

RSA

sign

String

签名值

N

e5815a4556db338ed237f7d3fd222184

Business Parameter

out_return_no

String(64)

外部退款请求的ID

N

 

out_trade_no

String(64)

境外商户交易号(确保在境外商户系统中唯一)

N

return_amount

Number(8,2)

外币退款金额

Y

100.30

currency

String(10)

外币币种

N

USD

gmt_return

String(14)

YYYYMMDDHHMMSS 北京时间(+8)

N

 

return_rmb_amount

Number(15)

人民币退款金额

Y

 

reason

String(100)

退款原因

Y

test

product_code

String(32)

网站支付: NEW_OVERSEAS_SELLER 手机浏览器或支付宝钱包支付: NEW_WAP_OVERSEAS_SELLER

N

NEW_OVERSEAS_SELLER

 

split_fund_info

String(1 600)

分账信息,json 格式,具体请参见“退款分账明细说明

Y

 

 

is_sync

String(1)

退款请求同步或异步处理。取值:Y或N。默认值:N,异步处理。如果该值为Y,notify_url将无意义

Y

Y

 

  1. 退款总金额不能超过原始的支付金额。
  2. 退款必须在一定的时间范围内申请(合同里面确定,默认是3个月)

同步返回

同步返回是xml格式的。

参数

类型 (长度是字节)

描述

可选

示例

is_success

String

返回状态, ‘T’ or ‘F’

N

T

error

String

错误消息

Y

REPEATED_REFUNDMENT_REQUEST

示例

请求示例

https://intlmapi.alipay.com/gateway.do?reason=refund+test&return_amount=0.1&sign_type=MD5&gmt_return=20130812094000&out_trade_no=iamdjc456&currency=HKD&sign=8e9004797d3c7112b907bd184d775662&_input_charset=UTF-8&out_return_no=test005&service=forex_refund&partner=2088701998606387

同步返回示例

成功返回
<?xml version="1.0" encoding="GBK"?>
<alipay>
    <is_success>T</is_success>    
</alipay>
错误返回:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
</alipay>

错误代码

基本上API接口的调用的检查是在支付宝的2个级别进行的

第一个级别是在支付宝网关。在这里会进行一些基础的校验,如签名,商家ID是否有效或者是否有权限使用某个接口等。如果校验失败,就会返回相应的错误码,归类在下面的网关错误中。

一旦网关校验通过了,接口请求就会被转发到内部系统进行进一步的处理。 这里会进行业务逻辑的校验。如果校验失败,就会返回相应的错误码,归类在业务错误代码中。

业务错误

错误代码

含义

REFUNDMENT_VALID_DATE_EXCEED

超过退款周期 不能退款

SYSTEM_EXCEPTION

系统异常

ILLEGAL_ARGUMENT

参数错误

REPEATED_REFUNDMENT_REQUEST

重复退款请求

RETURN_AMOUNT_EXCEED

退款金额超过支付金额

CURRENCY_NOT_SAME

退款币种与支付币种不一致

PURCHASE_TRADE_NOT_EXIST

交易不存在

网关错误

如果请求参数里面有错误,支付宝网关会报错。整个流程还是在支付宝这端而不会返回到商户端。

错误代码

含义

ILLEGAL_SIGN

签名错误

ILLEGAL_SERVICE

接口参数不正确

ILLEGAL_PARTNER

商户PID不对

ILLEGAL_SIGN_TYPE

签名方法错误

ILLEGAL_PARTNER_EXTERFACE

商家无权使用该接口

ILLEGAL_DYN_MD5_KEY

动态密钥信息错误

ILLEGAL_ENCRYPT

加密不正确

ILLEGAL_USER

用户ID不正确

ILLEGAL_EXTERFACE

接口配置错误

ILLEGAL_AGENT

代理商不正确

HAS_NO_PRIVILEGE

无权访问

INVALID_CHARACTER_SET

字符集不正确

系统错误

当出现系统错误提示时,请联系支付宝技术支持协助处理

错误代码

含义

SYSTEM_ERROR

支付宝系统错误

SESSION_TIMEOUT

Session 超时

ILLEGAL_TARGET_SERVICE

错误的target_service

ILLEGAL_ACCESS_SWITCH_SYSTEM

partner不允许访问该类型的系统

EXTERFACE_IS_CLOSED

接口已关闭

 

通过单笔交易查询接口,商户可以根据支付宝交易订单号或商户网站唯一订单号查询交易详细信息。

请求参数

参数

类型(长度范围)

参数说明

是否可为空

样例

基本参数

service

String

接口名称。

不可空

single_trade_query

partner

String(16)

签约的支付宝账号对应的支付宝唯一用户号。
以2088开头的16位纯数字组成。

不可空

2088001159940003

_input_charset

String

商户网站使用的编码格式,如utf-8、gbk、gb2312等。

不可空

GBK

sign

String

参数值

不可空

d8ed9f015214e7cd59bfadb6c945a87b

sign_type

String

签名方式只支持DSA、RSA、MD5。

不可空

MD5

业务参数

trade_no

String(64)

支付宝根据商户请求,创建订单生成的支付宝交易号。
最短16位,最长64位。
建议使用支付宝交易号进行查询,用商户网站唯一订单号查询的效率比较低。

可空

2010121502730740

out_trade_no

String(64)

支付宝合作商户网站唯一订单号(确保在商户系统中唯一)。

可空

210909550602881

同步返回

参数

类型(长度范围)

参数说明

是否可为空

样例

基本参数

is_success

String

请求是否成功。请求成功不代表业务处理成功。

  • T代表成功
  • F代表失败

不可空

T

sign

String

签名值

不可空

tphoyf4aoio5e6zxoaydjevem2c1s1zo

sign_type

String

签名方式只支持DSA、RSA、MD5。

不可空

MD5

error

String

只有当查询交易失败后,才返回错误代码。

可空

TRADE_NOT_EXIST

业务参数

buyer_email

String

买家支付宝账号。

不可空

tianc002@alipay.com

buyer_id

String

买家支付宝账号对应的支付宝唯一用户号。

不可空

2088002007274897

trade_status

String

交易状态包含:

  • TRADE_FINISHED
  •  WAIT_BUYER_PAY
  • TRADE_CLOSED
  • 不可空

    TRADE_FINISHED

    is_total_fee_adjust

    String

    • 调整过-T;
    • 没有调整过-F。

    不可空

    F

    out_trade_no

    String

    支付宝合作商户网站唯一订单号(确保在商户系统中唯一)。

    可空

    20080108-5

    trade_no

    String(64)

    支付宝根据商户请求,创建订单生成的支付宝交易号。
    最短16位,最长64位。

    不可空

    2010073000019942

    subject

    String

    商品的标题/交易标题/订单标题/订单关键字等。

    不可空

    Cannon相机

    flag_trade_locked

    String

    • 1表示冻结;
    • 0表示未冻结。

    不可空

    0

    body

    String

    对一笔交易的具体描述信息。如果是多种商品,请将商品描述字符串累加传给body。

    不可空

    Canon最新款卡片机

    gmt_create

    Date

    交易创建的时间。
    格式为yyyy-MM-dd HH:mm:ss。

    不可空

    2008-01-08 20:36:12

    seller_email

    String

    卖家的支付宝账号。

    不可空

    tianc001@alipay.com

    seller_id

    String

    卖家支付宝账号对应的支付宝唯一用户号。
    以2088开头的纯16位数字。

    不可空

    2088002007272365

    total_fee

    String

    单位:RMB。交易金额大于0元。
    担保交易单笔交易金额不能超过100万,精确到小数点后两位。

    不可空

    325

    price

    String

    单位为:RMB Yuan。取值范围为[0.01,1000000.00],精确到小数点后两位。

    可空

    10.00

    quantity

    String

    购买数量。

    可空

    1

    use_coupon

    String

    • 使用过-T;
    • 未使用过-F。

    可空

    T

    discount

    String

    折扣。

    可空

    0.00

    gmt_last_modified_time

    Date

    交易额最新修改时间。
    格式为yyyy-MM-dd HH:mm:ss。

    可空

    2008-01-08 20:39:30

    gmt_payment

    Date

    交易付款的时间。
    格式为yyyy-MM-dd HH:mm:ss。

    可空

    2008-01-08 20:39:30

    to_buyer_fee

    String

    累计的已经退款金额。

    可空

    1.00

    to_seller_fee

    String

    累计的已打款给卖家的金额。

    可空

    20.00

    payment_type

    String

    收款类型。取值范围请参见“收款类型 ”。

    可空

    1

    operator_role

    String

    • B:买家
    • S:卖家

    可空

    B

     

    示例

    请求示例

    https://mapi.alipay.com/gateway.do?service=single_trade_query&sign=d8ed9f015214e7cd59bfadb6c945a87b&trade_no=2010121502730740&partner=2088721091300630&out_trade_no=2009011803596246&sign_type=MD5

    返回示例

    成功返回
    <alipay>
    <is_success>T</is_success>
    <request>
    <param name="_input_charset">UTF-8</param>
    <param name="service">single_trade_query</param>
    <param name="partner">2088721091300630</param>
    <param name="out_trade_no">2009011803596246</param>
    <param name="sendFormat">normal</param>
    </request>
    <response>
    <trade>
    <body>hello</body>
    <buyer_email>intltest059@service.alipay.com</buyer_email>
    <buyer_id>2088122921745555</buyer_id>
    <discount>0.00</discount>
    <flag_trade_locked>0</flag_trade_locked>
    <gmt_create>2017-06-15 16:25:31</gmt_create>
    <gmt_last_modified_time>2017-06-15 16:25:58</gmt_last_modified_time>
    <gmt_payment>2017-06-15 16:25:58</gmt_payment>
    <is_total_fee_adjust>F</is_total_fee_adjust>
    <operator_role>B</operator_role>
    <out_trade_no>2009011803596246</out_trade_no>
    <payment_type>100</payment_type>
    <price>0.02</price>
    <quantity>1</quantity>
    <seller_email>test@126.com</seller_email>
    <seller_id>2088721091300630</seller_id>
    <subject>world</subject>
    <to_buyer_fee>0.00</to_buyer_fee>
    <to_seller_fee>0.02</to_seller_fee>
    <total_fee>0.02</total_fee>
    <trade_no>2017061521001003550204235677</trade_no>
    <trade_status>TRADE_FINISHED</trade_status>
    <use_coupon>F</use_coupon>
    </trade>
    </response>
    <sign>6283ce0cf5aaa812d9c1d29719d53e8d</sign>
    <sign_type>MD5</sign_type>
    </alipay>
    错误输出
    <?xml version="1.0"  encoding="utf-8"?>
      <alipay>
      <is_success>F</is_success>
      <error>ILLEGAL_SIGN</error>
      </alipay>

    基本上API接口的调用的检查是在支付宝的2个级别进行的

    第一个级别是在支付宝网关。在这里会进行一些基础的校验,如签名,商家ID是否有效或者是否有权限使用某个接口等。如果校验失败,就会返回相应的错误码,归类在下面的网关错误中。

    一旦网关校验通过了,接口请求就会被转发到内部系统进行进一步的处理。 这里会进行业务逻辑的校验。如果校验失败,就会返回相应的错误码,归类在业务错误代码中。

    业务错误码

    错误代码(error_code)

    含义

    TRADE_NOT_EXIST

    交易不存在,请检查提供的商户网站唯一订单号或者支付宝交易号是否正确

    ILLEGAL_SIGN

    签名不正确

    ILLEGAL_DYN_MD5_KEY

    动态密钥信息错误

    ILLEGAL_ENCRYPT

    加密不正确

    ILLEGAL_ARGUMENT

    参数不正确

    ILLEGAL_SERVICE

    Service参数不正确

    ILLEGAL_USER

    客户ID不正确

    ILLEGAL_PARTNER

    商户ID不正确

    ILLEGAL_EXTERFACE

    接口配置不正确

    ILLEGAL_PARTNER_EXTERFACE

    商户接口信息不正确

    ILLEGAL_SECURITY_PROFILE

    未找到匹配的密钥配置

    ILLEGAL_AGENT

    代理ID不正确

    ILLEGAL_SIGN_TYPE

    签名类型不正确

    ILLEGAL_CHARSET

    字符集不合法

    ILLEGAL_CLIENT_IP

    客户端IP地址无权访问服务

    HAS_NO_PRIVILEGE

    无权访问

    ILLEGAL_DIGEST_TYPE

    摘要类型不正确

    ILLEGAL_DIGEST

    文件摘要不正确

    ILLEGAL_FILE_FORMAT

    文件格式不正确

    ILLEGAL_ENCODING

    不支持该编码类型

    EXTERFACE_IS_CLOSED

    接口已关闭

    ILLEGAL_REQUEST_REFERER

    防钓鱼检查不支持该请求来源

    ILLEGAL_ANTI_PHISHING_KEY

    防钓鱼检查非法时间戳参数

    ANTI_PHISHING_KEY_TIMEOUT

    防钓鱼检查时间戳超时

    ILLEGAL_EXTER_INVOKE_IP

    防钓鱼检查非法调用IP

    System Errors

    当出现系统错误提示时,请联系支付宝技术支持协助处理。


    错误代码(error_code)

    含义

    SYSTEM_ERROR

    支付宝系统错误

    SESSION_TIMEOUT

    session超时

    ILLEGAL_TARGET_SERVICE

    错误的target_service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    partner不允许访问该类型的系统

    ILLEGAL_SWITCH_SYSTEM

    切换系统异常

    收款类型

    枚举名

    枚举说明

    01

    红包结算金预收款

    02

    红包结算金

    03

    提醒收款

    04

    自动发货商品

    1

    商品购买

    2

    服务购买

    3

    网络拍卖

    4

    捐赠

    5

    邮费补偿

    6

    奖金

    7

    基金购买

    8

    机票购买

    9

    收AA款

    10

    团购

    11

    电子客票

    12

    彩票

    13

    拍卖

    14

    手机支付类型

    15

    鲜花礼品

    16

    代理商电子客票

    17

    党费

    18

    外汇

    19

    自动直充

    20

    境外收单退款

    21

    即时到账退款

    22

    业务保证金

    24

    送礼金

    25

    交房租

    26

    motopay类型

    23

    购物车支付

    27

    团购担保交易付款

    交易状态

    枚举名

    枚举说明

    WAIT_BUYER_PAY

    等待买家付款

    WAIT_SELLER_SEND_GOODS

    买家已付款,等待卖家发货

    WAIT_BUYER_CONFIRM_GOODS

    卖家已发货,等待买家确认

    TRADE_FINISHED

    交易成功结束

    TRADE_CLOSED

    交易中途关闭(已结束,未成功完成)

    WAIT_SYS_CONFIRM_PAY

    支付宝确认买家银行汇款中,暂勿发货

    WAIT_SYS_PAY_SELLER

    买家确认收货,等待支付宝打款给卖家

    TRADE_REFUSE

    立即支付交易拒绝

    TRADE_REFUSE_DEALING

    立即支付交易拒绝中

    TRADE_CANCEL

    立即支付交易取消

    TRADE_PENDING

    等待卖家收款

    TRADE_SUCCESS

    支付成功

    BUYER_PRE_AUTH

    买家已付款(语音支付)

    COD_WAIT_SELLER_SEND_GOODS

    等待卖家发货(货到付款)

    COD_WAIT_BUYER_PAY

    等待买家签收付款(货到付款)

    COD_WAIT_SYS_PAY_SELLER

    签收成功等待系统打款给卖家(货到付款)

    交易附加状态

    枚举名

    枚举说明

    ZHIFUBAO_CONFIRM

    客服代买家确认收货

    ZHIFUBAO_CANCEL_FP

    客服代付款方取消快速支付

    DAEMON_CONFIRM_CANCEL_PRE_AUTH

    超时程序取消预授权

    DAEMON_CONFIRM_CLOSE

    超时程序因买家不付款关闭交易

    商家经常需要对交易进行对账。商家可以通过这个接口下载最长10天时间范围内的交易来对账。

    请求参数

    参数

    类型 (长度是字节)

    描述

    可选

    示例

    基本参数

     

    service

    String

    接口名

    N

    forex_compare_file

    partner

    String(16)

    境外商户在支付宝的用户ID.以2088开头的16位数字

    N

    2088001159940003

    sign_type

    String

    签名方法
    DSA, RSA, MD5.

    N

    RSA

    sign

    String

    签名值

    N

    e5815a4556db338ed237f7d3fd222184

    业务参数

    start_date

    String

    交易的开始日期、格式为YYYYMMDD

    N

     

    end_date

    String

    交易的结束日期、格式为YYYYMMDD

    N

     

    • 开始日期和结束日期最长10天
    • 当天的交易不会显示在下载的文件中
    • 现在这个接口只支持txt格式的文件下载。这个文件没有列标题。文件里的每个字段以“|”分割

    同步返回

    返回格式

    返回内容可能是以下几种格式:

    下载文件格式

    序号

    参数名

    类型

    备注

    •  

    外部交易号

    String(64)

    境外商户交易号(确保在境外商户系统中唯一)

    •  

    交易金额

    Number(8,2)

    商品的金额(外币)

    •  

    币种

    String(10)

    显示币种简称,具体参考附录:货币表

    •  

    付款时间

    String(14)

    YYYYMMDDHHMMSS 格式,状态为“失败”和“待处理”的情况,这个域为空

    •  

    清算时间

    String(14)

    YYYYMMDDHHMMSS 格式,如果没有清算,这个域为空

    •  

    交易类型

    String(1)

    正常交易:P
    申请退款:R

    •  

    手续费

    Number(8,2)

    收取的手续费

    •  

    状态

    String(1)

    正常交易记录状态:已付款:P    已清算:L
    申请退款记录状态:待处理:W   失败:F 
    “待处理”表示提交的退款申请支付宝系统还没有及时处理,“失败”表示提交的退款申请没有通过。

    •  

    备注

    String(50)

    备注信息(可选),如果记录为“失败”或“待处理”状态的退款记录,备注里增加退款申请时间,YYYYMMDDHHMMSS格式

    •  

    分账外币金额

    Number(8,2)

    该笔交易或退款对应的境内分账、退分账外币金额

    •  

    分账人民币金额

    Number(8,2)

    该笔交易或退款对应的境内分账、退分账人民币金额

    示例

    请求示例

    https://mapi.alipay.com/gateway.do?sign_type=MD5&sign=bb4c92c7cb7fc8a5280fe5f9f7ac309c&_input_charset=UTF-8&end_date=20150524&service=forex_compare_file&partner=2088002007018916&start_date=20150520

    返回示例

    成功返回

    成功的http返回是一个带交易记录的txt文件:

    业务逻辑出错:
    File download failed: Over 10 days to Date period
    网关错误:
    <?xml version="1.0" encoding="UTF-8"?>
    <alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
    </alipay>

    示例下载文件

    23342347424|112.11|USD|20070616090001||P|2.24|P|Unliquidated
    23342343423|102.32|USD|20070615090001|2007622090001|P|2.04|L|Liquidated

    基本上API接口的调用的检查是在支付宝的2个级别进行的。

    第一个级别是在支付宝网关。在这里会进行一些基础的校验,如签名,商家ID是否有效或者是否有权限使用某个接口等。如果校验失败,就会返回相应的错误码,归类在下面的网关错误中。

    一旦网关校验通过了,接口请求就会被转发到内部系统进行进一步的处理。 这里会进行业务逻辑的校验。如果校验失败,就会返回相应的错误码,归类在业务错误代码中。

    业务错误代码

    错误码

    含义

    Over limit balance amount record

    超过文件最大记录数20000条

    System exception

    系统异常

    Merchant ID incorrect

    商户ID不对

    Finish date not ahead of today

    结束日期必须小于今天

    No balance amount data in the period

    选择日期范围内没有交易

    Over 10 days to date period

    超过最长10天的限制

    Finish date ahead of begin date

    结束日期必须晚于开始日期

    Illegal date period

    日期不能为空

    Date format incorrect YYYYMMDD

    日期格式错误 ,必须是YYYYMMDD

    Internet connected exception ,please try later

    网络异常

    网关错误

    如果请求参数里面有错误,支付宝网关会报错。整个流程还是在支付宝这端而不会返回到商户端。


    错误码

    含义

    SYSTEM_EXCEPTION

    系统异常

    ILLEGAL_ARGUMENT

    接口参数不正确

    ILLEGAL_SIGN

    签名不正确

    ILLEGAL_SERVICE

    Service 参数不正确

    ILLEGAL_PARTNER

    商家ID不正确

    ILLEGAL_SIGN_TYPE

    签名类型错误

    ILLEGAL_PARTNER_EXTERFACE

    商家无权使用该接口

    ILLEGAL_DYN_MD5_KEY

    动态密钥信息错误

     

    ILLEGAL_ENCRYPT

    加密不正确

     

    ILLEGAL_USER

    用户ID不正确

     

    ILLEGAL_EXTERFACE

    接口配置错误

     

    ILLEGAL_AGENT

    代理商不正确

     

    HAS_NO_PRIVILEGE

    无权访问

     

    INVALID_CHARACTER_SET

     

    字符集不正确

    系统错误

    当出现系统错误提示时,请联系支付宝技术支持协助处理


    错误码

    含义

    SYSTEM_ERROR

    支付宝系统错误

    SESSION_TIMEOUT

    Session 超时

    ILLEGAL_TARGET_SERVICE

    错误的target_service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    partner不允许访问该类型的系统

    EXTERFACE_IS_CLOSED

    接口已关闭

    商家可以通过这个接口来查看上次结算以来的交易结算信息。

    请求参数

    参数

    类型 (长度是字节)

    描述

    可选

    示例

    基本参数

    service

    String

    接口名

    N

    forex_liquidation_file

    partner

    String(16)

    境外商户在支付宝的用户ID. 2088开头的16位数字

    N

    2088001159940003

    sign_type

    String

    签名算法: DSA, RSA, MD5.

    N

    RSA

    sign

    String

    签名值

    N

    e5815a4556db338ed237f7d3fd222184

    业务参数

    start_date

    String

    交易的开始日期,格式为YYYYMMDD

    N

     

    end_date

    String

    交易的结束日期,格式为YYYYMMDD

    N

    • 开始日期和结束日期最长10天
    • 当天的交易不会显示在下载的文件中
    • 现在这个接口只支持txt格式的文件下载。这个文件没有列标题。文件里的每个字段以“|”分割

    同步返回

    返回格式

    返回内容可能是以下几种格式:

    结算文件格式

    序号

    域名

    类型

    备注

    •  

    外部交易号

    String(64)

    境外商户交易号(确保在境外商户系统中唯一)

    •  

    交易金额

    Number(8,2)

    商品的金额(外币)

    •  

    币种

    String(10)

    显示币种简称,具体参考附录:货币表

    •  

    付款时间

    String(14)

    YYYYMMDDHHMMSS 格式,状态为“失败”和“待处理”的情况,这个域为空

    •  

    清算时间

    String(14)

    YYYYMMDDHHMMSS 格式,如果没有清算,这个域为空

    •  

    交易类型

    String(1)

    正常交易:P
    申请退款:R

    •  

    手续费

    Number(8,2)

    收取的手续费

    •  

    状态

    String(1)

    正常交易记录状态: 已清算:L
    正常退款记录状态: 已清算:L

    •  

    备注

    String(50)

    交易项的名称,不支持特殊符号。

    •  

    分账外币金额

    Number(8,2)

    该笔交易或退款对应的境内分账、退分账外币金额

    •  

    分账人民币金额

    Number(8,2)

    该笔交易或退款对应的境内分账、退分账人民币金额

    示例

    请求示例

    https://mapi.alipay.com/gateway.do?sign_type=MD5&sendFormat=normal&sign=bb4c92c7cb7fc8a5280fe5f9f7ac309c&_input_charset=UTF-8&end_date=20150524&service=forex_liquidation_file&partner=2088002007018916&start_date=20150520

    返回示例

    成功返回

    成功的http返回是一个带交易记录的txt文件::

    This interface enables the merchant reconcile the settled transactions with the settlement of the funds in the previous settlement cycle.

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    forex_liquidation_file

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    N

    RSA

    sign

    String

    Signature value.

    N

    e5815a4556db338ed237f7d3fd222184

    Business Parameter

    start_date

    String

    The start date of the reconciliation period, formatted as YYYYMMDD

    N

     

    end_date

    String

    The end date of the reconciliation period, formatted as   YYYYMMDD

    N

     

    • The starting and end dates should be provided within a 10-day interval.
    • There is a time delay such that the transactions in the current day will not be listed in the return of this API call.
    • Currently the interface only supports .TXT file to be downloaded. The file contains no headings for data fields. Each data field is separated by “|”, following the order given in the specification.

    Sync Response

    Response format

    The responses could be in different formats for different use cases

    File Format for the Settlement file in the Response

    Order

    Field name

    Type

    Description

    1

    Partner transaction ID

    String(32)

    The  Unique transaction ID passed by the merchants in the payment transaction

    2

    Amount

    Number(8,2)

    The amount of fund in foreign currency.

    3

    Currency

    String(10)

    Abbreviated currency names.

    4

    Payment Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if the status being “failed” or “waiting”.

    5

    Settlement Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if unliquidated

    6

    Transaction type

    String(1)

    Normal transaction: P
    Refund transaction: R

    7

    Service charge

    Number(8,2)

    The amount of service charge.

    8

    Status

    String(1)

    Normal transaction:
    L: Liquidated
    Refund transaction:
    L: Liquidated

    9

    Remark

    String(50)

    The name of the items. It should not contain special symbols.

    10

    Split foreign currency amount

    Number(8,2)

    This trade's split foreigh currency amount or this refund's split refund foreigh currency amount.

    11

    Split RMB amount

    Number(8,2)

    This trade's split RMB amount or this refund's split refund RMB amount.

    Samples

    Request Sample

    https://mapi.alipay.com/gateway.do?sign_type=MD5&sendFormat=normal&sign=bb4c92c7cb7fc8a5280fe5f9f7ac309c&_input_charset=UTF-8&end_date=20150524&service=forex_liquidation_file&partner=2088002007018916&start_date=20150520

    Response Samples

    Success response

    The response is HTTP response with an attached file, which is the settlement file with the transactions included.
    The sample is for illustration of the browser download.

    Error response from the biz logic:

    File download failed: Over 10 days to Date period

    Error response from the Gateway:

    <?xml version="1.0" encoding="UTF-8"?>
    <alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
    </alipay>

    An example of settlement report file:

    23342343423|102.32|USD|20070615090001|2007622090001|P|2.04|L|Liquidated

    业务逻辑错误返回:
    File download failed: Over 10 days to Date period
    网关错误返回:
    <?xml version="1.0" encoding="UTF-8"?>
    <alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
    </alipay>

    示例结算文件

    下面是一个示例结算文件:

    23342343423|102.32|USD|20070615090001|2007622090001|P|2.04|L|Liquidated

    基本上API接口的调用的检查是在支付宝的2个级别进行的

    第一个级别是在支付宝网关。在这里会进行一些基础的校验,如签名,商家ID是否有效或者是否有权限使用某个接口等。如果校验失败,就会返回相应的错误码,归类在下面的网关错误中。

    一旦网关校验通过了,接口请求就会被转发到内部系统进行进一步的处理。 这里会进行业务逻辑的校验。如果校验失败,就会返回相应的错误码,归类在业务错误代码中。

    业务逻辑错误

    错误码

    含义

    Over limit balance amount record

    超过文件最大记录数20000条

    System exception

    系统异常

    Merchant ID incorrect

    商户ID不对

    Finish date not ahead of today

    结束日期必须小于今天

    No balance amount data in the period

    选择日期范围内没有交易

    Over 10 days to date period

    超过最长10天的限制

    Finish date ahead of begin date

    结束日期必须晚于开始日期

    Illegal date period

    日期不能为空

    Date format incorrect YYYYMMDD

    日期格式错误 ,必须是YYYYMMDD

    Internet connected exception ,please try later

    网络异常

    网关错误

    如果请求参数里面有错误,支付宝网关会报错。整个流程还是在支付宝这端而不会返回到商户端。

    错误

    含义

    SYSTEM_EXCEPTION

    系统异常

    ILLEGAL_ARGUMENT

    接口参数不正确

    ILLEGAL_SIGN

    签名不正确

    ILLEGAL_SERVICE

    Service 参数不正确

    ILLEGAL_PARTNER

    商家ID不正确

    ILLEGAL_SIGN_TYPE

    签名类型错误

    ILLEGAL_PARTNER_EXTERFACE

    商家无权使用该接口

    ILLEGAL_DYN_MD5_KEY

    动态密钥信息错误

     

    ILLEGAL_ENCRYPT

    加密不正确

     

    ILLEGAL_USER

    用户ID不正确

     

    ILLEGAL_EXTERFACE

    接口配置错误

     

    ILLEGAL_AGENT

    代理商不正确

     

    HAS_NO_PRIVILEGE

    无权访问

     

    INVALID_CHARACTER_SET

     

    字符集不正确

    系统错误

    当出现系统错误提示时,请联系支付宝技术支持协助处理


    错误码

    含义

    SYSTEM_ERROR

    支付宝系统错误

    SESSION_TIMEOUT

    Session 超时

    ILLEGAL_TARGET_SERVICE

    错误的target_service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    partner不允许访问该类型的系统

    EXTERFACE_IS_CLOSED

    接口已关闭

     

    商家可以使用这个接口来查询支付宝参考汇率。

  • 货币间的汇率会在北京时间每日9:00到11:00间变动一次;
  • 汇率每日获取上限为100次。
  • 请求参数

    字段名

    变量名

    类型

    说明

    可空

    基本参数

    接口名称

    service

    String

    service=forex_rate_file

    N

    境外商户

    partner

    String(16)

    境外商户在支付宝的用户ID

    N

    签名

    sign

    String

    签名值

    N

    签名方式

    sign_type

    String

    签名方式,MD5, RSA, DSA

    N

    • 接口下载的是一个txt文件
    • 文件内容没有列标题并且数据字段之间用”|”分割
    • 只能下载当天的参考汇率,并不是交易发生时的真实汇率。真实汇率以交易时的页面展示为准。

    同步返回

    返回格式

    返回内容可能是以下几种格式:

    返回的文件格式

    序号

    域名

    类型

    备注

    1

    日期

    String(8)

    汇率发布的日期:YYYYMMDD

    2

    时间

    String(6)

    汇率发布的时间点:HHMMSS

    3

    币种符号

    String(3)

    货币的符号,请参考币种表

    4

    汇率

    String(14)

     

    示例

    请求示例

    https://mapi.alipay.com/gateway.do?sign_type=MD5&sendFormat=normal&sign=590a9fbbed8a5b9a86b426795445f9f0&service=forex_rate_file&partner=2088101122136241

    示例汇率文件:

    20160504|100030|CHF|6.829600|
    20160504|100030|EUR|7.491500|
    20160504|100030|THB|0.185877|
    20160504|100030|DKK|1.007800|
    20160504|100030|SGD|4.815600|
    20160504|100030|GBP|9.476100|
    20160504|100030|HKD|0.838800|
    20160504|100030|NOK|0.803000|
    20160504|100030|CAD|5.124900|
    20160504|100030|KRW|0.005814|
    20160504|100030|NZD|4.496100|
    20160504|100030|JPY|0.060934|
    20160504|100030|AUD|4.877600|
    20160504|100030|SEK|0.809800|
    20160504|090530|USD|6.534600|

     

    返回示例

    成功返回

    成功的返回是一个带汇率信息的txt文件:

    业务逻辑错误返回:
    File download failed: Over 10 days to Date period
    网关错误返回:
    <?xml version="1.0" encoding="UTF-8"?>
    <alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
    </alipay>

    基本上API接口的调用的检查是在支付宝的2个级别进行的

    第一个级别是在支付宝网关。在这里会进行一些基础的校验,如签名,商家ID是否有效或者是否有权限使用某个接口等。如果校验失败,就会返回相应的错误码,归类在下面的网关错误中。

    一旦网关校验通过了,接口请求就会被转发到内部系统进行进一步的处理。 这里会进行业务逻辑的校验。如果校验失败,就会返回相应的错误码,归类在业务错误代码中。

    业务错误代码

    Returned result

    Description

    System exception

    系统异常

    Merchant ID incorrect

    商家ID不对

    File empty

    空文件

    网关错误

    如果请求参数里面有错误,支付宝网关会报错。整个流程还是在支付宝这端而不会返回到商户端。

    错误代码

    含义

    ILLEGAL_ARGUMENT

    参数错误

    ILLEGAL_SIGN

    签名错误

    ILLEGAL_SERVICE

    接口参数不正确

    ILLEGAL_PARTNER

    商户PID不对

    ILLEGAL_SIGN_TYPE

    签名方法错误

    ILLEGAL_PARTNER_EXTERFACE

    商家无权使用该接口

    ILLEGAL_DYN_MD5_KEY

    动态密钥信息错误

    ILLEGAL_ENCRYPT

    加密不正确

    ILLEGAL_USER

    用户ID不正确

    ILLEGAL_EXTERFACE

    接口配置错误

    ILLEGAL_AGENT

    代理商不正确

    HAS_NO_PRIVILEGE

    无权访问

    INVALID_CHARACTER_SET

    字符集不正确

    系统错误

    当出现系统错误提示时,请联系支付宝技术支持协助处理


    Returned result

    Description

    SYSTEM_ERROR

    支付宝系统错误

    SESSION_TIMEOUT

    Session 超时

    ILLEGAL_TARGET_SERVICE

    错误的target_service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    partner不允许访问该类型的系统

    EXTERFACE_IS_CLOSED

    接口已关闭

    验证此次通知信息是否是支付宝服务器发来的信息,以帮助校验反馈回来的数据的真假性。

    获取支付宝返回数据之一的通知校验ID(notify_id),按照支付宝要求的格式拼接成要请求的链接,如:

    https://mapi.alipay.com/gateway.do?service=notify_verify&partner=2088002396712354&notify_id=RqPnCoPT3K9%252Fvwbh3I%252BFioE227%252BPfNMl8jwyZqMIiXQWxhOCmQ5MQO%252FWd93rvCB%252BaiGg

    通过访问这个请求链接,利用编程方法来模拟http请求与支付宝服务器进行交互,获得支付宝服务器上处理的结果。
    如果获得的信息是true,则校验成功;如果获得的信息是其他,则校验失败。

    请求参数

    参数

    类型

    说明

    可空

    示例

    基本参数

    service

    String

    接口名

    N

    notify_verify

    partner

    String(16)

    境外商户在支付宝的用户ID. 2088开头的16位数字

    N

    2088001159940003

    业务参数

    notify_id

    String(34)

    支付宝通知流水号,境外商户可以用这个流水号询问支付宝该条通知的合法性

    N

    • 正确的验证异步通知的顺序是:
      • 收到异步通知后,先不要回复‘success’。否则会影响支付宝系统的行为(支付宝系统会对所有已经回复了 ‘success’的异步通知的验证请求返回false)
      • 调用这个接口来验证notify id.
        • 如果输入参数是无效的,支付宝会返回 ‘Invalid’
        • 如果异步通知是支付宝发出的并且验证请求是在异步通知发出后的1分钟内发起的,则返回‘True’
        • 如果该通知不是支付宝发送的,支付宝会返回 ‘False’
        • 如果验证请求在异步通知发送一分钟之后,支付宝会返回 ‘False’
        • 如果商家已经对异步通知返回了 ‘true’, 支付宝会返回 ‘False’
      • 异步通知一旦验证成功,商家需要回复 ‘Success’

    同步返回

    返回是一个状态字符串.

    返回示例

    如传入的参数无效,则返回:

    Invalid

    如异步通知是来自支付宝的并且是过去1分钟内的,则返回:

    
    True
    

    如异步通知不是来自支付宝或者已经超过了一分钟,则返回:

    
    False
    

    示例

    请求示例

    https://intlmapi.alipay.com/gateway.do?service=notify_verify&partner=2088101122136241&notify_id=4465b04e84cb6bacc2bd1b52232c0b8gjg&sign=ciSBXc7gjCfXW8KMBxFiFH2cbMZtFelfTOGKqY2NF7q98RnH3E%2BiF5Cj%2Fu%2Bl8py1D%2FOsE%2FAva1ls8A6Tw1MzhG6ideJSgh4FxWmAjEnlczdfLj%2FqzA6qGzxdKGEXaSDFmTGglOembXUqK8g8ajICD%2BBH7xoxBRY7vtfylEXtojs%3D&sign_type=RSA

    基本上API接口的调用的检查是在支付宝的2个级别进行的

    第一个级别是在支付宝网关。在这里会进行一些基础的校验,如签名,商家ID是否有效或者是否有权限使用某个接口等。如果校验失败,就会返回相应的错误码,归类在下面的网关错误中。

    一旦网关校验通过了,接口请求就会被转发到内部系统进行进一步的处理。 这里会进行业务逻辑的校验。如果校验失败,就会返回相应的错误码,归类在业务错误代码中。

    网关错误

    如果请求参数里面有错误,支付宝网关会报错。整个流程还是在支付宝这端而不会返回到商户端。

    错误码

    含义

    SYSTEM_EXCEPTION

    系统异常

    ILLEGAL_ARGUMENT

    接口参数不正确

    ILLEGAL_SIGN

    签名不正确

    ILLEGAL_SERVICE

    Service 参数不正确

    ILLEGAL_PARTNER

    商家ID不正确

    ILLEGAL_SIGN_TYPE

    签名类型错误

    ILLEGAL_PARTNER_EXTERFACE

    商家无权使用该接口

    ILLEGAL_DYN_MD5_KEY

    动态密钥信息错误

    ILLEGAL_ENCRYPT

    加密不正确

    ILLEGAL_USER

    用户ID不正确

    ILLEGAL_EXTERFACE

    接口配置错误

    ILLEGAL_AGENT

    代理商不正确

    HAS_NO_PRIVILEGE

    无权访问

    INVALID_CHARACTER_SET

    字符集不正确

    系统错误

    当出现系统错误提示时,请联系支付宝技术支持协助处理

    错误码

    含义

    SYSTEM_ERROR

    支付宝系统错误

    SESSION_TIMEOUT

    Session 超时

    ILLEGAL_TARGET_SERVICE

    错误的target_service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    partner不允许访问该类型的系统

    EXTERFACE_IS_CLOSED

    接口已关闭

    支付宝国际为境外收单与境外当面付商户提供的账单。商家可以通过获取这些账单对交易进行对账。 账单中包含商户每日的交易文件和结算文件,结算文件仅在当日有结算时才会生成。通过SFTP站点或支付宝国际网站下载时,当日有结算的前提下还会有结算汇总文件。

    结算时间

    交易文件生成时间

    结算文件生成时间

    注意:

    • 周五00:00 到周日23:59的对账文件在下周一生成
    • 节假日前一天起,连同节假日期间的对账文件,会在假期后第一个工作日生成

    账单下载途径有:API,支付宝国际网站,和SFTP。各渠道获取的对账文件在命名和字段数目上有所不同。具体见下文。

    API

    商家平台集成新境外收单API后,通过调用相关接口即可得到对账账单文件。

    对账文件下载接口用于获取交易文件。

    结算文件下载接口用于获取结算文件。

    支付宝国际网站(global.alipay.com)

    访问并登录支付宝国际网站– My Alipay – My Transaction。你可以在线查看交易文件和结算文件,也可以通过点击Download Files下载。

    注意:

    SFTP

    如需要通过SFTP获取对账记录,请完成以下步骤:

    1. 申请SFTP账号
    2. 商户集成上线后,可将PID和访问支付宝SFTP站点的IP地址(注意,必须是非内网IP地址)发至支付宝国际技术支持中心申请。支付宝国际技术支持中心将在5个工作日内为您配置好SFTP账单对应的登陆账号。

    3. 账户获取成功后连接站点访问
    4. 下载Winscp。填入以下信息进行访问:

      • 端口:22
      • 主机名称:根据网络情况选择sftp.alipay.com(国内) / isftp.alipay.com(美国)
      • 用户名及密码
    • 90天内未使用的SFTP账户将会被关闭;
    • 超过一周的SFTP账单会被不定期删除,商户尽量在3天内处理账单。如果商户因未及时处理账单,发现账单已经被清理,请联系Global Merchant Technical Support

    账单中包含商户交易文件和结算文件。SFTP和支付宝国际网站下载的结算文件还包含结算汇总文件。API, SFTP和支付宝国际网站下载的文件有所差别。下面对交易和结算文件的文件命名方式,详细内容和差别进行说明。

    交易文件

    交易文件包含了所选时间内的交易记录。

    取决于交易文件的下载方式,文件名可能含有不同的部分。详情请见下表:

    方式

    Partner ID

    日期

    文件类型

    文件后缀

    示例

    API

    支付宝分配的唯一ID

    YYYYMMDD + 6位随机码

    /

    .txt

    2088021017666931_20180531143440.txt

    支付宝国际网站

    支付宝分配的唯一ID

    YYYYMMDD,YYYYMM或YYYYMMDD + 6位随机码

    /

    .csv、.txt、.xls

    2088611221573217_20180621151516.xls

    SFTP

    支付宝分配的唯一ID

    YYYYMMDD

    固定值:transaction

    .csv

    2088721149955614_fptrade_20180823.csv

    交易文件可能包含的所有内容如下表所示:

    序号

    字段名称

    说明

    1

    Partner_transaction_id

    商户交易号(即:支付时请求参数中的Out_trade_no或者退款时的out_return_no)

    2

    Amount

    交易金额(外币)

    3

    Rmb_amount

    交易金额(人民币)

    4

    Currency

    币种

    5

    Fee

    手续费(外币)

    6

    Rate

    汇率

    7

    Payment_time

    支付时间

    8

    Settlement_time

    结算时间

    9

    Type

    交易类型

    10

    Status

    状态(正常交易记录状态:
    已付款:P
    已清算:L 申请退款记录状态:
    待处理:W
    失败:F)

    11

    Original_partner_transaction_ID

    原始商户交易号(即:支付时上传的out_trade_no)。
    注:非默认字段。如需添加此字段请联系Alipay Overseas Support进行配置。

    12

    Transaction_ID

    支付宝交易号。
    注:非默认字段。如需添加此字段请联系Alipay Overseas Support进行配置。

    13

    Distribute_amount

    分账外币金额

    14

    Distribute_rmb_amount

    分账人民币金额

    15

    Remarks

    备注

    16

    Settlement

    结算金额(外币)

    17

    Rmb_settlement

    结算金额(人民币)

    API、支付宝国际网站、SFTP下载的交易文件所含内容的不同之处,如下表所示:

    序号

    字段名称

    SFTP

    API

    Global在线

    Global离线

    1

    Partner_transaction_id

    2

    Amount

    3

    Rmb_amount

    4

    Currency

    5

    Fee

    6

    Rate

    7

    Payment_time

    8

    Settlement_time

    9

    Type

    10

    Status

    11

    Original_partner_transaction_ID

    12

    Transaction_ID

    13

    Distribute_amount

    14

    Distribute_rmb_amount

    15

    Remarks

    16

    Settlement

    17

    Rmb_settlement

    结算文件

    结算文件包含了所选时间内的结算记录。

    注意:

    支付宝国际网站Download Files页面和SFTP下载的结算文件为文件压缩包,压缩包中包含结算概要文件和具体结算文件。 压缩包的文件命名规则为:<PID>_<日期>.zip,例如:2088021******931_20180508.zip

    结算概要文件

    从支付宝国际网站Download Files页面和SFTP下载的结算文件都含有名为settlebatch 的结算概要文件。Settlebatch文件名包含以下部分:

    Partner ID

    文件类型

    日期

    文件后缀

    示例

    支付宝分配的唯一ID

    固定值:settlebatch

    YYYYMMDD

    .csv

    2088021******931_settlebatch_20180531.csv

    Settlebatch可能包含以下字段:

    序号

    字段名称

    说明

    1

    settle_batch_no

    支付宝内部文件序号

    2

    settle_date

    结算时间

    3

    Amount

    交易金额(外币)

    4

    Fee

    手续费(外币)

    5

    Settlement

    结算金额(外币)

    6

    Currency

    币种

    结算文件

    结算文件包含了所选时间内结算详情。

    取决于文件的下载方式,文件名可能含有不同的部分。详情请见下表:

    方式

    Partner ID

    文件类型

    日期

    系统分配ID

    文件后缀

    示例

    API

    支付宝分配的唯一ID

    /

    YYYYMMDD + 6位随机码

    /

    .txt

    2088021017666931_20180531143440.txt

    支付宝国际网站

    支付宝分配的唯一ID

    固定值:settle

    YYYYMMDD,YYYYMM或YYYYMMDD + 6位随机码

    系统自动分配的唯一ID

    .csv、.txt、.xls

    2088721631012256_settle_20171106_50002017080100032007000005107441.csv

    SFTP

    支付宝分配的唯一ID

    固定值:settle

    YYYYMMDD

    系统自动分配的唯一ID

    .csv

    2088721631012256_settle_20171106_50002017080100032007000005107441.csv

    结算文件可能包含的所有内容如下表所示:

    序号

    字段名称

    说明

    1

    Partner_transaction_id

    商户交易号(即:支付时请求参数中的Out_trade_no或者退款时的out_return_no)

    2

    Transaction_ID

    支付宝交易号。
    注:非默认字段。如需添加此字段请联系Alipay Overseas Support进行配置。

    3

    Original_partner_transaction_ID

    原始商户交易号(即:支付时上传的out_trade_no)。
    注:非默认字段。如需添加此字段请联系Alipay Overseas Support进行配置。

    4

    Amount

    交易金额(外币)

    5

    Rmb_amount

    交易金额(人民币)

    6

    Currency

    币种

    7

    Fee

    手续费(外币)

    8

    Rate

    汇率

    9

    Payment_time

    支付时间

    10

    Settlement_time

    结算时间

    11

    Type

    交易类型

    12

    Status

    交易状态

    13

    Distribute_amount

    分账外币金额

    14

    Distribute_rmb_amount

    分账人民币金额

    15

    Remarks

    备注

    16

    Settlement

    结算金额(外币)

    17

    Rmb_settlement

    结算金额(人民币)

    18

    Stem_From

    交易来源于何种类型商户:

  • M:境外收单商户;
  • T:天猫国际商户。
  • 在线查看到的结算文件,和通过API、支付宝国际网站、SFTP获得的结算文件,内容不完全相同。具体如下表所示:

    序号

    字段名称

    SFTP

    API

    Global离线

    1

    Partner_transaction_id

    2

    Transaction_ID

    3

    Original_partner_transaction_ID

    4

    Amount

    5

    Rmb_amount

    6

    Fee

    7

    Distribute_amount

    8

    Distribute_rmb_amount

    9

    Settlement

    10

    Rmb_settlement

    11

    Currency

    12

    Rate

    13

    Payment_time

    14

    Settlement_time

    15

    Type

    16

    Status

    17

    Remarks

    18

    Stem_From

    境外线上二级商户同步接口用于机构同步二级商户到支付宝系统中完成商户信息报备。关于二级商户报备接口的更多信息,请参见关于二级商户报备接口的常见问题

    请求参数

    参数

    类型(字节长度)

    描述

    可选

    示例

    基本参数

    service

    String

    接口名称

    不可空

    alipay.overseas.secmerchant.online.maintain

    partner

    String(16)

    合作者身份ID。签约的支付宝账号对应的支付宝唯一用户号。

    以2088开头的16位纯数字组成。

    不可空

    2088101142878662

    _input_charset

    String

    参数编码字符集。商户网站使用的编码格式,如utf-8、gbk、gb2312等。

    不可空

    gbk

    sign_type

    String

    签名方式。DSA、RSA、MD5三个值可选,必须大写。

    不可空

    MD5

    sign

    String

    请参见签名机制

    不可空

    2118ac8fad6bc1d9e88a6cd017c18d37

    timestamp

    String

    时间戳。接口的调用时间,支付宝会在一定时间内失效此调用(默认半小时)。此时间目前以北京时间为准,格式为 :yyyy-MM-dd HH:mm:ss。

    不可空

    2012-12-21 17:11:16

    业务参数

    secondary_merchant_name

    String(64)

    二级商户名称

    不可空

    secMerchantName

    secondary_merchant_id

    String(64)

    二级间连商户ID

    不可空

    63472327348

    secondary_merchant_industry

    String(4)

    行业类型,用于区分不同行业。请参见 MCC list

    不可空

    MCC list

    register_country

    String(2)

    注册国家,非空,ISO3166二位字母编码。请参见 ISO 3166

    不可空

    HK

    register_address

    String(256)

    二级商户注册地址

    可空

    HANGZHOU

    site_infos

    String

    商户网址名称,json格式,最长5个网站或app url。详见 site_infos

    添加或删除URL,请重新传入此参数。

    不可空

    二级商户网站或APP URL,格式: [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"w ebsit"},

    {"site_type":"APP","site_url":"https://alipay.com","site_name":"we bsit"}]

    二级参数

    site_infos

    参数

    类型(字节长度)

    描述

    可选

    示例

    site_type

    String

    网站类型,网址或者APP下载地址只能是WEB或者APP,字母区分大小写。

    不可空

    WEB

    site_url

    String(256)

    网址URL。

  • 当site_type为WEB时,传入的URL格式为:http/https + SLD + TLD,例如: https://www.alipay.com
  • 当site_type为APP时,传入以http/https开始的APP下载URL,例如:https://itunes.apple.com/cn/app/id333206289
  • 不可空

    https://www.alipay.com

    site_name

    String(512)

    站点名称

    可空

    xx 店

    部分参数类型为String,未指明长度范围,表明系统不校验该参数的长度。

    同步返回

    响应将以XML格式返回。

    参数

    类型(字节长度)

    描述

    可选

    示例

    基本参数

    is_success

    String

    请求是否成功。请求成功不代表业务处理成功。

  • T代表成功
  • F代表失败
  • 不可空

    T

    sign_type

    String

    签名方式,DSA、RSA、MD5三个值可选,必须大写。

    可空

    MD5

    sign

    String

    请参见签名机制

    可空

    3afc92ac4708425ab74ecb2c4e58ef56

    error

    String

  • 请求成功时,不存在本参数;
  • 请求失败时,本参数为错误代码,请参见接入错误系统错误
  • 可空

    PARAM_ILLEGAL

    同步返回的参数随支付宝服务端的演化,可能会返回更多的节点,需要程序使用方对文档说明以外的节点予以忽略。

    示例

    请求示例

    用于签名的字符串

    partner=2018283223743743&secendary_merchant_name=merchantname &secendary_merchant_id=23647324&sign=2118ac8fad6bc1d9e88a6cd017c18d37&secondary_merchant_industry= 4039&_input_charset=GBK&register_address=HANGZHOU&service=alipay.overseas.secmerchant.online.maintain& amp;timestamp=1438432738473843&site_infos= [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]

    生成的跳转url

    http://mapi.alipay.com/gateway.do?_input_charset=UTF-8&service=alipay.overseas.secmerchant.online.maintain&partner=20881332189403823&timestamp=2018-10-09 16:04:16&secondary_merchant_name=test1&secondary_merchant_id=100510000031&secondary_merchant_industry=5935&register_country=HK&register_address=HANGZHOU&site_infos= [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]&sign=8457f906bf89a5e444a6e5c28f8da499&sign_type=MD5

    本样例仅供参考,支付宝网关为 https://mapi.alipay.com/gateway.do?

    返回示例

    业务正常受理并报备成功:

    
    <?xml version="1.0" encoding="utf-8"?>
    <alipay>
    <is_success>T</is_success>
    <request>
        <param name="secondary_merchant_industry">5935</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">8457f906bf89a5e444a6e5c28f8da499</param>
        <param name="site_infos">
            [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]
        </param>
        <param name="secondary_merchant_id">100510000031</param>
        <param name="register_address">HANGZHOU</param>
        <param name="partner">2088131089302823</param>
        <param name="service">alipay.overseas.secmerchant.online.maintain</param>
        <param name="secondary_merchant_name">test1</param>
        <param name="register_country">HK</param>
        <param name="sign_type">MD5</param>
        <param name="timestamp">2018-10-09 16:04:16</param>
    </request>
    <response>
        <alipay>
            <result_code>SUCCESS</result_code>
        </alipay>
    </response>
    </alipay>
    

    请求成功,业务处理失败:

    
    <alipay>
    <is_success>F</is_success>
    <error>PARAM_ILLEGAL</error>
    <sign>ba101b7ffb43afde9ba63c0de335218e</sign>
    <sign_type>MD5</sign_type>
    </alipay>
    

    请求失败或者接入数据错误时输出:

    
    <?xml version="1.0" encoding="utf-8"?>
    <alipay>
        <is_success>F</is_success>
        <error>ILLEGAL_PARTNER</error>
    </alipay>
    

    错误码

    业务错误码

    错误代码

    描述

    MCC_CAN_NOT_MODIFY

    传入的MCC码与原MCC不一致。请检查MCC参数是否是原MCC。

    REGISTER_COUNTRY_FORBIDDEN

    如果注册国家在反洗钱国家范围内,则不允许报备。

    PARAM_ILLEGAL

    参数格式不合法,如超长或者非空的参数未传等。请根据接口文档检查参数格式。

    SYSTEM_ERROR

    支付宝系统错误

    接入错误

    错误代码

    描述

    ILLEGAL_SIGN

    签名不正确

    ILLEGAL_DYN_MD5_KEY

    动态密钥信息错误

    ILLEGAL_ENCRYPT

    加密不正确

    ILLEGAL_ARGUMENT

    参数不正确

    ILLEGAL_SERVICE

    Service参数不正确

    ILLEGAL_USER

    用户ID不正确

    ILLEGAL_PARTNER

    合作伙伴ID不正确

    ILLEGAL_EXTERFACE

    接口配置不正确

    ILLEGAL_PARTNER_EXTERFACE

    合作伙伴接口信息不正确

    ILLEGAL_SECURITY_PROFILE

    未找到匹配的密钥配置

    ILLEGAL_AGENT

    代理ID不正确

    ILLEGAL_SIGN_TYPE

    签名类型不正确

    ILLEGAL_CHARSET

    字符集不合法

    HAS_NO_PRIVILEGE

    无权访问

    INVALID_CHARACTER_SET

    字符集无效

    系统错误

    当出现系统错误提示时,请联系 支付宝技术支持

    错误代码

    描述

    SYSTEM_ERROR

    支付宝系统错误

    SESSION_TIMEOUT

    session超时

    ILLEGAL_TARGET_SERVICE

    错误的target_service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    商户不允许访问该类型的系统

    EXTERFACE_IS_CLOSED

    接口已关闭

    客服小机器人

    NEED HELP ?