# Overview

AsiaBill 提供了一套Restful API接口来满足您的对接需要。

本文档所有接口（除具体接口额外声明），均使用签名验签的方式，服务端对服务端进行通信交互，不建议在前端或不安全的环境进行接口签名以及接口调用

## 1 常量

本文档含有一些常量参数，在不同环境对应不同的值，具体取值见下方[环境参数](#4-huan-jing-can-shu)

**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`(具体接口另外声明除外) ，注意特殊字符[乱码问题](https://asiabill.gitbook.io/api-explorer/fu-lu/chang-jian-wen-ti#1-can-shu-zhi-luan-ma-huo-que-shi)
* 请求与响应，均含有header、body
* 所有请求与响应结果中，body部分格式均为json格式（含有code message data）
* 如具体接口还有其他定义则以其为准

### Header

#### 请求头Request Header

每一次发起请求时，需要在header设置如下字段信息。**注意：**字段名称不区分大小写

<table><thead><tr><th width="203.86592343396615">字段名称</th><th width="173.68050407394247">字段类型（长度）</th><th>字段描述</th></tr></thead><tbody><tr><td>gateway-no</td><td>String(8)</td><td>商户网关号，由Asiabill为商户分配的唯一标识，8位数字编号</td></tr><tr><td>request-id</td><td>String(64)</td><td>请求id，商户系统每次请求的唯一标识，30分钟内不可重复。可由字母数字组成，区分大小写，如："12345678902234</td></tr><tr><td>request-time</td><td>String(16)</td><td>请求的时间戳(ms)，时间偏移不能超过10分钟，如：1646648307486</td></tr><tr><td>sign-info</td><td>String(255)</td><td>签名结果，对<a href="../fu-lu/shu-ju-qian-ming-guo-cheng#4-dui-qing-qiu-shu-ju-qian-ming">请求参数进行签名</a>后值写入该处，不区分大小写</td></tr></tbody></table>

#### 响应头Response Header

每一个请求，如果返回结果的话，则含有如下统一的header信息：

<table><thead><tr><th>字段名称</th><th width="196.33333333333331">字段类型（长度）</th><th>字段描述</th></tr></thead><tbody><tr><td>gateway-no</td><td>String(8)</td><td>值同请求时的gateway-no</td></tr><tr><td>response-id</td><td>String(64)</td><td>值同request-id</td></tr><tr><td>response-time</td><td>String(16)</td><td>时间戳(ms)，服务端处理的时间，一般为13位长度字符串，如：1646648307486</td></tr><tr><td>version</td><td>String(16)</td><td>一般接口返回无该字段，只有在webhook返回时才有该字段，如V2022-03</td></tr><tr><td>sign-info</td><td>String(255)</td><td>签名结果，对<a href="../fu-lu/shu-ju-qian-ming-guo-cheng#5-dui-jie-guo-shu-ju-qian-ming-yan-zheng">响应结果进行签名</a>后值写入该处，不区分大小写</td></tr></tbody></table>

### Body

#### 请求体Request Body

get方式，此时参数实际是附加在url上，属于本文的query参数，此时无body参数

post方式，如果接口需要传入参数，则统一json格式，否则无需传入

#### 响应体Response Body

每个请求如果服务端接收处理，则返回json格式的结果，含有code message data三项，

code一般返回："00000" 或者 [错误码](https://asiabill.gitbook.io/api-explorer/fu-lu/chang-jian-cuo-wu-ma)

解析数据先判断code为"00000"，再解析data里面的数据

示例如下：

{% tabs %}
{% tab title="异常返回示例" %}

```json
//当发生业务或数据异常，此时返回code message data，其中data可能为null：
//比如，请求时间不在当前范围内（时钟偏移量不超过10分钟）
{
    "code": "L0003",
    "message": "requestTime outside range",
    "data": null
}s
```

{% endtab %}

{% tab title="单笔数据返回示例" %}

```json
// "00000"一般表示请求操作成功，具体见此类接口的response
{
     "code": "00000",
     "message": "success",
     "data": {
          "firstName": "first",
          "lastName": "last",
          "otherProperty":"val"
     }
}
```

{% endtab %}

{% tab title="列表数据返回示例" %}

```json
// 具体见此类接口的response
{
     "code": "00000",
     "message": "success",
     "data": {
          "list": [
               {
                    "firstName": "first",
                    "lastName": "last",
                    "otherProperty":"val"
               }
          ]
     }
}
```

{% endtab %}

{% tab title="分页数据返回示例" %}

```json
// 具体见此类接口的response
{
     "code": "00000",
     "message": "success",
     "data": {
          "page":{
               "total": 12,
               "pageSize":10,
               "currentPageNo":1
          }
          "list": [
               {
                    "firstName": "first",
                    "lastName": "last",
                    "otherProperty":"val"
               }
          ]
     }
}
```

{% endtab %}
{% endtabs %}

## 3 请求参数与对象描述

### 请求参数定义

对于请求入参，按照类型，现分为header、path、query、body四种类型，分别指请求时，参数应该传递的位置，具体见[参数定义](https://asiabill.gitbook.io/api-explorer/fu-lu/shu-ju-qian-ming-guo-cheng#shu-ju-ding-yi)

### 请求参数描述

* **格式：必填\* 、类型长度(最大长度n) 、附加条件的文字描述**
* **赋值示范：【字段描述】中举例展示**
* **实际校验：必填+长度+附加条件**

一般请求与返回的对象表示如下：

<table><thead><tr><th width="203.86592343396615">字段名称</th><th width="173.68050407394247">字段类型（长度）</th><th>字段描述</th></tr></thead><tbody><tr><td>tradeNo*</td><td>String(64)</td><td><p>订单号；</p><p>最长64个字符；</p><p>如：123456</p></td></tr><tr><td>currency*</td><td>String(3)</td><td><p>币种，固定长度为3；</p><p>如：USD；  </p></td></tr><tr><td>cardNo</td><td>String(19)</td><td>卡号，非必填，最大长度19</td></tr><tr><td>type^</td><td>String(4)</td><td>类型，最大长度为4，条件性必填，当cardNo不为空时，需要输入type</td></tr><tr><td>remark</td><td>String(500)</td><td>交易备注 </td></tr></tbody></table>

{% hint style="info" %}
长度一般以转为UTF-8后计算长度，会出现中文或特殊字符的长度与显示字符个数不一致

注意：某些非必传参数在特定场景下会被要求提供，请仔细阅读字段描述中的要求
{% endhint %}

**以上表示信息为：**

> tradeNo：字符串，带\*表示必填（不能传入空），长度的最大为16
>
> currency：字符串，带\*表示必填（不能传入空），固定长度3的值（字段描述中进一步注明）
>
> type: 字符串，带\~表示条件必填，当满足描述的条件时，需要传入值
>
> remark：字符串，非必填，可传入空，最大长度为500个字符

## 4 环境参数

### API地址常量

#### 测试环境

> paymentApiUrl：[https://testpay.asiabill.com](https://testpay.asiabill.com/)
>
> openApiUrl：[https://api-uat.asiabill.com](https://api-sandbox.asiabill.com)

#### 生产环境

> paymentApiUrl：[https://safepay.asiabill.com](https://safepay.asiabill.com/)
>
> openApiUrl：[https://openapi.asiabill.com](https://safepay.asiabill.com/)

### 商户管理后台

> 测试环境：[https://merchant-uat.asiabill.com](https://merchant-uat.asiabill.com/)
>
> 生产环境：[https://portal.asiabill.com](https://portal.asiabill.com/)

## 5 API账户信息

> 测试环境的账户信息：[<mark style="color:blue;">测试账户信息</mark>](https://asiabill.gitbook.io/api-explorer/fu-lu/ce-shi-zhang-hao-xin-xi)
>
> 生产环境的账户信息：<mark style="color:orange;">联系AsiaBill客服获取</mark>