# 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`(具体接口另外声明除外) ，注意特殊字符[乱码问题](/api-explorer/fu-lu/chang-jian-wen-ti.md#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="/pages/fcT05rGIoeEMO3FWV0F9#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="/pages/fcT05rGIoeEMO3FWV0F9#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" 或者 [错误码](/api-explorer/fu-lu/chang-jian-cuo-wu-ma.md)

解析数据先判断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四种类型，分别指请求时，参数应该传递的位置，具体见[参数定义](/api-explorer/fu-lu/shu-ju-qian-ming-guo-cheng.md#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>](/api-explorer/fu-lu/ce-shi-zhang-hao-xin-xi.md)
>
> 生产环境的账户信息：<mark style="color:orange;">联系AsiaBill客服获取</mark>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://asiabill.gitbook.io/api-explorer/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.