Overview

Search…
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）
如具体接口还有其他定义则以其为准
Header
请求头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地址常量
测试环境
paymentApiUrl：https://testpay.asiabill.com​
openApiUrl：https://api-uat.asiabill.com​
生产环境
paymentApiUrl：https://safepay.asiabill.com​
openApiUrl：https://openapi.asiabill.com​
商户管理后台
测试环境：https://merchant-uat.asiabill.com​
生产环境：https://portal.asiabill.com​
5 API账户信息
测试环境的账户信息：测试账户信息​
生产环境的账户信息：联系AsiaBill客服获取
Next - API Reference
交易
Last modified 1mo ago
Copy link
Contents