# 2.通用API说明

商户服务器和 AllPay 网关对接的通用接口,每个渠道都具有的功能,包括:订购消费,订购预授权,订购预授权完成,预售期撤销,查询接口。 

## 2.1.验签说明

1.对于发送到 ALLPAY 系统的 POST 请求报文，其中所有传入参数(除 sign 参数外)按照字段名的 ASCII 码从小到大排序后(字典序)，使用 URL 键值对的格式(即 key1=value1&key2=value2...)拼接成字符串 String1。

2.在 String1 最后直接拼接(不需要用“&”连接)双方约定的签名密钥 K1(接入时 ALLPAY 时分配)，得到 stringSignTemp 字符串,并对 stringSignTemp 进行sha256 运算，得到 sign 的值。

3.示例签名串

```js
card_no=5200831111111113&currency=CNY&expiry_date=1119&mch_id=000000000000015&order_amount=100&sign_type=SHA256&trade_no=370000197809218764&trade_time=20180829165052&trade_type=PURC2f2c77e3718c47cfb47a89a6fbc9d361
```

## 2.2.通用API 接入地址

开发调试地址|生产交易地址  
-----------|-------
<https://testapi.allpayx.com/expup> |<https://api.allpayx.com/expup>

## 2.3.订购消费接口

接口说明：

该接口可以进行订购消费，每次trade_no不能重复

1. 请求参数

   | 参数名称     | 必填 | 使用说明                                       |
   | :----------- | :--- | ---------------------------------------------- |
   | mch_id       | M    | 商户ID，由AllPay分配                           |
   | trade_type   | M    | 交易类型 消费填写"PURC"                        |
   | trade_no     | M    | 商户自行定义，需保证同一商户号下订单号不能重复 |
   | order_amount | M    | 订单金额   如100元，表示为100或100.00          |
   | currency     | M    | 订单币种  人民币填写“CNY”,美元填写"USD"        |
   | card_no      | M    | 卡号                                           |
   | expiry_date  | M    | 有效期  MMYY                                   |
   | trade_time   | M    | 交易时间,格式:"yyyyMMddHHmmss"                 |
   | sign_type    | M    | SHA256                                         |
   | sign         | M    | 签名                                           |

   举例如下：

   ```json
   {
   	"mch_id": "000000000000015",
   	"trade_type": "PURC",
   	"trade_no": "370000197809218764",
   	"order_amount": "100",
   	"currency": "CNY",
   	"card_no": "5200831111111113",
   	"expiry_date": "1119",
   	"trade_time": "20180829165052",
   	"sign_type": "SHA256",
   	"sign": "426907204360081d7c728a6695067bc84233e82d0e3a61703313d874aa741d76"
   }
   ```

2. 响应报文

参数如下表:

| 参数名称   | 必填 | 使用说明             |
| ---------- | ---- | -------------------- |
| resp_code  | M    | 应答码 00-成功       |
| resp_msg   | M    | 应答信息             |
| mch_id     | M    | 商户ID，由AllPay分配 |
| trade_type | M    | 交易类型             |
| trade_time | M    | 交易时间             |
| trade_no   | M    | 交易订单号           |
| sign_type  | M    | SHA256               |
| sign       | M    | 签名                 |

举例如下：

```json
{
  "resp_code": "00",
  "resp_msg": "SUCCESS",
  "mch_id": "000000000000015",
  "trade_type": "PURC",
  "trade_time": "20180829165048",
  "trade_no": "520000197701311324",
  "sign_type": "SHA256",
  "sign": "7ca2442edac07b92ee9d086d2df1635b62c1d5d4ab33ffe8ceb2c195579a8698"
}
```

## 2.4.消费退款接口

接口说明：

该接口可以对订购消费进行退款，退款时origin_trade_no填写订购消费时的trade_no，可以进行分步退款，分步退款时每次的trade_no不能重复。

1. 请求参数

   | 参数名称       | 必填 | 使用说明                                       |
   | :------------- | :--- | ---------------------------------------------- |
   | mch_id         | M    | 商户ID，由AllPay分配                           |
   | trade_type     | M    | 交易类型 退款填写"REFD"              |
   | trade_no       | M    | 商户自行定义，需保证同一商户号下订单号不能重复 |
   | origin_trade_no       | M    | 原订购消费订单号, 原交易类型必须为PURC |
   | refund_amount | M    | 退款金额   如100元，表示为100或100.00          |
   | currency | M    | 订单币种  人民币填写“CNY”,美元填写"USD"        |
   | trade_time     | M    | 交易时间,格式:"yyyyMMddHHmmss"                 |
   | sign_type      | M    | SHA256                                         |
   | sign           | M    | 签名                                           |

   举例如下：

   ```json
   {
   	"mch_id": "000000000000015",
   	"trade_type": "REFD",
   	"trade_no": "990000198707011244",
   	"origin_trade_no": "230000197106062088",
   	"refund_amount": "1",
   	"currency": "CNY",
   	"trade_time": "20180829165313",
   	"sign_type": "SHA256",
   	"sign": "edc8e56be38190402ee537e3fc4e30766d47a0ca297c2de4be460a99a6139e14"
   }
   ```

2. 响应报文

参数如下表:

| 参数名称   | 必填 | 使用说明             |
| ---------- | ---- | -------------------- |
| resp_code  | M    | 应答码 00-成功       |
| resp_msg   | M    | 应答信息             |
| mch_id     | M    | 商户ID，由AllPay分配 |
| trade_type | M    | 交易类型             |
| trade_time | M    | 交易时间             |
| trade_no   | M    | 交易订单号           |
| sign_type  | M    | SHA256               |
| sign       | M    | 签名                 |

举例如下：

```json
{
  "resp_code": "00",
  "resp_msg": "SUCCESS",
  "mch_id": "000000000000015",
  "trade_type": "REFD",
  "trade_time": "20180829165313",
  "trade_no": "990000198707011244",
  "sign_type": "SHA256",
  "sign": "3a370170181a5aa6b5f53cb3ae81890813c455df6ec9b1a894a49302fcc3d055"
}
```

## 2.5.订购预授权 

接口说明：

该接口可以进行订购预授权，每次trade_no不能重复


1. 请求参数

   | 参数名称     | 必填 | 使用说明                                       |
   | :----------- | :--- | ---------------------------------------------- |
   | mch_id       | M    | 商户ID，由AllPay分配                           |
   | trade_type   | M    | 交易类型 预授权填写" PAUT "                    |
   | trade_no     | M    | 商户自行定义，需保证同一商户号下订单号不能重复 |
   | order_amount | M    | 订单金额   如100元，表示为100或100.00          |
   | currency     | M    | 订单币种  人民币填写“CNY”,美元填写"USD"        |
   | card_no      | M    | 卡号                                           |
   | expiry_date  | M    | 有效期  MMYY                                   |
   | trade_time   | M    | 交易时间,格式:"yyyyMMddHHmmss"                 |
   | sign_type    | M    | SHA256                                         |
   | sign         | M    | 签名                                           |

   举例如下：

   ```json
   {
   	"mch_id": "000000000000015",
   	"trade_type": "PAUT",
   	"trade_no": "620000199911267889",
   	"order_amount": "100",
   	"currency": "CNY",
   	"card_no": "5200831111111113",
   	"expiry_date": "1119",
   	"trade_time": "20180829165720",
   	"sign_type": "SHA256",
   	"sign": "ac7cf7d284cf72743e16c51b7a95d9a61b7dbb6f50e92f5699ecf4d9f8e65aee"
   }
   ```

2. 响应报文

参数如下表:

| 参数名称   | 必填 | 使用说明             |
| ---------- | ---- | -------------------- |
| resp_code  | M    | 应答码 00-成功       |
| resp_msg   | M    | 应答信息             |
| mch_id     | M    | 商户ID，由AllPay分配 |
| trade_type | M    | 交易类型             |
| trade_time | M    | 交易时间             |
| trade_no   | M    | 交易订单号           |
| sign_type  | M    | SHA256               |
| sign       | M    | 签名                 |

举例如下：

```json
{
  "resp_code": "00",
  "resp_msg": "SUCCESS",
  "mch_id": "000000000000015",
  "trade_type": "PAUT",
  "trade_time": "20180829165720",
  "trade_no": "620000199911267889",
  "sign_type": "SHA256",
  "sign": "7421f9720d56b1d417edc26f89d2777b74d7745440bfc4957c853474f20ea4f7"
}
```





## 2.6.订购预授权完成 

接口说明：

该接口可以对订购预授权完成，origin_trade_no填写订购预授权时的trade_no


1. 请求参数

   | 参数名称        | 必填 | 使用说明                                       |
   | :-------------- | :--- | ---------------------------------------------- |
   | mch_id          | M    | 商户ID，由AllPay分配                           |
   | trade_type      | M    | 交易类型 预授权完成填写"  PAUC  "              |
   | trade_no        | M    | 商户自行定义，需保证同一商户号下订单号不能重复 |
   | origin_trade_no | M    | 原预授权订单号, 原交易类型必须为PAUT           |
   | order_amount    | M    | 订单金额   如100元，表示为100或100.00          |
   | currency        | M    | 订单币种  人民币填写“CNY”,美元填写"USD"        |
   | trade_time      | M    | 交易时间,格式:"yyyyMMddHHmmss"                 |
   | sign_type       | M    | SHA256                                         |
   | sign            | M    | 签名                                           |



   举例如下：

   ```json
   {
   	"mch_id": "000000000000015",
   	"trade_type": "PAUC",
   	"origin_trade_no": "620000199911267889",
   	"trade_no": "310000198512106263",
   	"order_amount": "100",
   	"currency": "CNY",
   	"trade_time": "20180829170036",
   	"sign_type": "SHA256",
   	"sign": "0a532fdc7488bdbc6cdc87d24635fdd7294d6d3fc8cf0eb387d4b74b5fc3dcb7"
   }
   ```

2. 响应报文

参数如下表:

| 参数名称   | 必填 | 使用说明             |
| ---------- | ---- | -------------------- |
| resp_code  | M    | 应答码 00-成功       |
| resp_msg   | M    | 应答信息             |
| mch_id     | M    | 商户ID，由AllPay分配 |
| trade_type | M    | 交易类型             |
| trade_time | M    | 交易时间             |
| trade_no   | M    | 交易订单号           |
| sign_type  | M    | SHA256               |
| sign       | M    | 签名                 |

举例如下：

```json
{
  "resp_code": "00",
  "resp_msg": "SUCCESS",
  "mch_id": "000000000000015",
  "trade_type": "PAUC",
  "trade_time": "20180829170036",
  "trade_no": "310000198512106263",
  "sign_type": "SHA256",
  "sign": "5769c35d68d8263ace180e224eea6ebb8907cc1a1042a9f955cd9c32fd0602cf"
}
```
## 2.7.撤销接口 

接口说明：

该接口可以对 订购消费，订购预授权，订购预授权完成进行撤销，origin_trade_no填写对应交易的trade_no。


1. 请求参数

   | 参数名称        | 必填 | 使用说明                                       |
   | :-------------- | :--- | ---------------------------------------------- |
   | mch_id          | M    | 商户ID，由AllPay分配                           |
   | trade_type      | M    | 交易类型 撤销填写"VOID "                       |
   | trade_no        | M    | 商户自行定义，需保证同一商户号下订单号不能重复 |
   | origin_trade_no | M    | 需要撤销的订单号                               |
   | trade_time      | M    | 交易时间,格式:"yyyyMMddHHmmss"                 |
   | sign_type       | M    | SHA256                                         |
   | sign            | M    | 签名                                           |

   举例如下：

   ```json
   {
   	"mch_id": "000000000000015",
   	"trade_type": "VOID",
   	"trade_no": "370000197912155378",
   	"origin_trade_no": "460000201604155983",
   	"trade_time": "20180829170913",
   	"sign_type": "SHA256",
   	"sign": "6c0815cd8f364dacc965e6bc2ce144fe56b7743912f0520db33c9c3393e75d26"
   }
   ```

2. 响应报文

参数如下表:

| 参数名称   | 必填 | 使用说明             |
| ---------- | ---- | -------------------- |
| resp_code  | M    | 应答码 00-成功       |
| resp_msg   | M    | 应答信息             |
| mch_id     | M    | 商户ID，由AllPay分配 |
| trade_type | M    | 交易类型             |
| trade_time | M    | 交易时间             |
| trade_no   | M    | 交易订单号           |
| sign_type  | M    | SHA256               |
| sign       | M    | 签名                 |

举例如下：

```json
{
  "resp_code": "00",
  "resp_msg": "SUCCESS",
  "mch_id": "000000000000015",
  "trade_type": "VOID",
  "trade_time": "20180829170913",
  "trade_no": "370000197912155378",
  "sign_type": "SHA256",
  "sign": "d48e6a23b87f7f3b47598aed52fe60aaccb053979de588170f943f9a3426ced4"
}
```

## 2.8.交易查询 

接口说明：

该接口可以对订购消费，订购预授权，订购预授权完成，退款，撤销，进行查询，trade_no填写要查询的订单的


1. 请求参数

   | 参数名称   | 必填 | 使用说明                       |
   | :--------- | :--- | ------------------------------ |
   | mch_id     | M    | 商户ID，由AllPay分配           |
   | trade_type | M    | 交易类型 查询填写"INQY"        |
   | trade_no   | M    | 需要查询状态的订单号           |
   | trade_time | M    | 交易时间,格式:"yyyyMMddHHmmss" |
   | sign_type  | M    | SHA256                         |
   | sign       | M    | 签名                           |

   举例如下：

   ```json
   {
   	"mch_id": "000000000000015",
   	"trade_type": "INQY",
   	"trade_no": "990000198707011244",
   	"trade_time": "20180829171422",
   	"sign_type": "SHA256",
   	"sign": "2bdfe50dc7c207891e132485eedf978c3f355f3a8e3ad25d6b4260c388a584c5"
   }
   ```

2. 响应报文

参数如下表:

| 参数名称      | 必填 | 使用说明                               |
| ------------- | ---- | -------------------------------------- |
| resp_code     | M    | 应答码 00-成功                         |
| resp_msg      | M    | 应答信息                               |
| mch_id        | M    | 商户ID，由AllPay分配                   |
| trade_type    | M    | 交易类型                               |
| trade_time    | M    | 交易时间                               |
| trade_no      | M    | 交易订单号                             |
| order_amount  | C    | trade_type 为PURC,PAUT,PAUC时返回      |
| refund_amount | C    | trade_type 为REFD时返回                |
| currency      | C    | trade_type 为PURC,PAUT,PAUC,REFD时返回 |
| sign_type     | M    | SHA256                                 |
| sign          | M    | 签名                                   |

举例如下：

```json
{
  "mch_id": "000000000000015",
  "trade_type": "REFD",
  "trade_time": "20180829165313",
  "trade_no": "990000198707011244",
  "refund_amount": "1",
  "currency": "CNY",
  "sign_type": "SHA256",
  "sign": "4ab0c48ac6aac058f7f5d6473679dcebc91d6c57cf3f690ab8984248b5b960f9"
}
```