Overview
更新时间:2022-03-11 12:43
AsiaBill 提供了一套Restful API接口来满足您的对接需要。
本文档所有接口(除具体接口额外声明),均使用签名验签的方式,服务端对服务端进行通信交互,不建议在前端或不安全的环境进行接口签名以及接口调用

1 常量

本文档含有一些常量参数,在不同环境对应不同的值,具体取值见下方环境参数
apiVersion
API版本号,体现在接口请求的URL中间,一般跟在API基本路径后方,示例:https://{paymentApiUrl}/{apiVersion}/sessionToken,https://{openApiUrl}/{apiVersion}/transaction/123456,其中{apiVersion}表示版本号
paymentApiUrl
支付类API服务的基本路径,本文档中出现的{paymentApiUrl}即代表此常量
openApiUrl
openApi服务的基本路径,本文档中出现的{openApiUrl}即代表此常量

2 接口报文结构

  • 默认输入和输出格式: Content-Type: application/json; charset=UTF-8(具体接口另外声明除外) ,注意特殊字符乱码问题
  • 请求与响应,均含有header、body
  • 所有请求与响应结果中,body部分格式均为json格式(含有code message data)
  • 如具体接口还有其他定义则以其为准

请求头Request Header

每一次发起请求时,需要在header设置如下字段信息。注意:字段名称不区分大小写
字段名称
字段类型(长度)
字段描述
gateway-no
String(8)
商户网关号,由Asiabill为商户分配的唯一标识,8位数字编号
request-id
String(64)
请求id,商户系统每次请求的唯一标识,30分钟内不可重复。可由字母数字组成,区分大小写,如:"12345678902234
request-time
String(16)
请求的时间戳(ms),时间偏移不能超过10分钟,如:1646648307486
sign-info
String(255)
签名结果,对请求参数进行签名后值写入该处,不区分大小写

响应头Response Header

每一个请求,如果返回结果的话,则含有如下统一的header信息:
字段名称
字段类型(长度)
字段描述
gateway-no
String(8)
值同请求时的gateway-no
response-id
String(64)
值同request-id
response-time
String(16)
时间戳(ms),服务端处理的时间,一般为13位长度字符串,如:1646648307486
version
String(16)
一般接口返回无该字段,只有在webhook返回时才有该字段,如V2022-03
sign-info
String(255)
签名结果,对响应结果进行签名后值写入该处,不区分大小写

Body

请求体Request Body

get方式,此时参数实际是附加在url上,属于本文的query参数,此时无body参数
post方式,如果接口需要传入参数,则统一json格式,否则无需传入

响应体Response Body

每个请求如果服务端接收处理,则返回json格式的结果,含有code message data三项,
code一般返回:"00000" 或者 错误码
解析数据先判断code为"00000",再解析data里面的数据
示例如下:
异常返回示例
单笔数据返回示例
列表数据返回示例
分页数据返回示例
1
//当发生业务或数据异常,此时返回code message data,其中data可能为null:
2
//比如,请求时间不在当前范围内(时钟偏移量不超过10分钟)
3
{
4
"code": "L0003",
5
"message": "requestTime outside range",
6
"data": null
7
}s
Copied!
1
// "00000"一般表示请求操作成功,具体见此类接口的response
2
{
3
"code": "00000",
4
"message": "success",
5
"data": {
6
"firstName": "first",
7
"lastName": "last",
8
"otherProperty":"val"
9
}
10
}
Copied!
1
// 具体见此类接口的response
2
{
3
"code": "00000",
4
"message": "success",
5
"data": {
6
"list": [
7
{
8
"firstName": "first",
9
"lastName": "last",
10
"otherProperty":"val"
11
}
12
]
13
}
14
}
Copied!
1
// 具体见此类接口的response
2
{
3
"code": "00000",
4
"message": "success",
5
"data": {
6
"page":{
7
"total": 12,
8
"pageSize":10,
9
"currentPageNo":1
10
}
11
"list": [
12
{
13
"firstName": "first",
14
"lastName": "last",
15
"otherProperty":"val"
16
}
17
]
18
}
19
}
Copied!

3 请求参数与对象描述

请求参数定义

对于请求入参,按照类型,现分为header、path、query、body四种类型,分别指请求时,参数应该传递的位置,具体见参数定义

请求参数描述

  • 格式:必填* 、类型长度(最大长度n) 、附加条件的文字描述
  • 赋值示范:【字段描述】中举例展示
  • 实际校验:必填+长度+附加条件
一般请求与返回的对象表示如下:
字段名称
字段类型(长度)
字段描述
tradeNo*
String(64)
订单号;
最长64个字符;
如:123456
currency*
String(3)
币种,固定长度为3;
如:USD;
cardNo
String(19)
卡号,非必填,最大长度19
type^
String(4)
类型,最大长度为4,条件性必填,当cardNo不为空时,需要输入type
remark
String(500)
交易备注
长度一般以转为UTF-8后计算长度,会出现中文或特殊字符的长度与显示字符个数不一致
注意:某些非必传参数在特定场景下会被要求提供,请仔细阅读字段描述中的要求
以上表示信息为:
tradeNo:字符串,带*表示必填(不能传入空),长度的最大为16
currency:字符串,带*表示必填(不能传入空),固定长度3的值(字段描述中进一步注明)
type: 字符串,带~表示条件必填,当满足描述的条件时,需要传入值
remark:字符串,非必填,可传入空,最大长度为500个字符

4 环境参数

API地址常量

测试环境

生产环境

商户管理后台

5 API账户信息

测试环境的账户信息:测试账户信息
生产环境的账户信息:联系AsiaBill客服获取
Last modified 1mo ago