交易即开票对接文档

# 瑞生意开票开放平台商户接口文档

## 修订记录

| 版本 | 日期 | 说明 |
| ---- | ---- | ---- |
| 1.1 | 2026年9月1日 | 初版 |
| 1.2 | 2026年9月5日 | 增加油机联动兼容 |

# 1. API接入认证

## 1.1 接口说明

开放平台请求分为系统级参数和业务级参数两部分：系统级参数是所有服务 API 都拥有的参数，业务级参数统一放在 `biz_content` 中。

| 接口       | method                          | 说明                                                 |
| ---------- | ------------------------------- | ---------------------------------------------------- |
| 支付即开票 | `rsypay.invoice.payment.issue`  | 创建支付订单；是否开票由 `is_invoice` 决定。         |
| 发票开具   | `rsypay.invoice.cash.issue`     | 未关联支付开票，或对「已付未开」订单开具发票。       |
| 发票查询   | `rsypay.invoice.query`          | 统一查询支付、开票、退款汇总、红冲及换开状态和详情。 |
| 换开发票   | `rsypay.invoice.change`         | 换开发票                                             |
| 退款即红冲 | `rsypay.invoice.refund.reverse` | 对支付订单发起退款及关联红冲。                       |
| 仅退款     | `rsypay.invoice.refund`         | 对支付订单发起退款，不触发红冲。                     |
| 仅红冲     | `rsypay.invoice.reverse`        | 对未关联支付的蓝票发起整票红冲。                     |
| 退款查询   | `rsypay.invoice.refund.query`   | 查询单笔退款及关联红冲结果。                         |
| 发票下载   | `rsypay.invoice.download`       | 根据发票业务编号实时获取发票 PDF Base64 内容。       |

## 1.2 接口地址

> 请联系客户经理获取接口地址
>

## 1.3 调用方式

| 项目              | 约定                              |
| ----------------- | --------------------------------- |
| 请求方式          | HTTP POST                         |
| 请求 Content-Type | `application/json; charset=UTF-8` |
| 响应 Content-Type | `application/json; charset=UTF-8` |

## 1.4 系统级参数

| 名称          | 类型   | 是否必须 | 描述                                                         |
| ------------- | ------ | -------- | ------------------------------------------------------------ |
| `appkey`      | String | 是       | 终端开放平台标识，例如 `000001`。平台根据该值获取商户 RSA 公钥。 |
| `version`     | String | 是       | 接口版本号，支持 `1.1` 和 `1.2`。传 `1.1` 时按 1.1 版本字段规则处理；传 `1.2` 时支持油机联动参数，见 `1.8.3.2`。 |
| `method`      | String | 是       | 接口业务标识                                                 |
| `rpi_no`      | String | 是       | 商户唯一编号                                                 |
| `biz_content` | Object | 是       | 业务请求参数 JSON 对象。                                     |
| `sign`        | String | 是       | Base64 格式的 RSA 请求签名。                                 |

## 1.5 签名规则

请求、成功响应和回调均使用 `SHA256withRSA` 算法进行签名（密钥长度 2048 位，私钥格式为 PKCS#8）。

商户生成密钥对并与平台交换公钥，通讯时请求方使用己方**私钥**签名，响应方使用对方公钥验签。

商户可使用 http://web.chacuo.net/netrsakeypair **【证书密码】不要输入任何值**，直接点生成即可。

待签名文本生成规则：

1. 请求从最外层 JSON 中排除 `sign`；响应从 `data` 中排除 `sign`；回调从最外层 JSON 中排除 `sign`。
2. 最外层值为 `null` 的字段不参与签名。
3. 对参与签名的字段名按 ASCII 码升序排列，如`key1=value1&key2=value2` ， 去前后空格得到排序后的字符。
4. 对待签名文本执行 `SHA256withRSA` 签名或验签。

例如，商户实际发送：

```json
{
  "appkey": "000001",
  "version": "1.1",
  "method": "rsypay.invoice.payment.issue",
  "rpi_no": "RPI001",
  "biz_content": {
    "out_trade_no": "T202608030001",
    "order_amount": 95.00,
    "pay_amount": 95.00
  },
  "sign": "Base64格式RSA签名"
}
```

对应待签名文本为：

```text
appkey=000001&biz_content={"out_trade_no":"T202608030001","order_amount":95.00,"pay_amount":95.00}&method=rsypay.invoice.payment.issue&rpi_no=RPI001&version=1.1
```

## 1.6 公共响应参数

| 名称      | 类型    | 描述                                   |
| --------- | ------- | -------------------------------------- |
| `code`    | Integer | `200` 表示请求成功受理或同步处理成功。 |
| `success` | Boolean | 同上，表示是否请求成功。               |
| `data`    | Object  | 业务响应参数。                         |
| `msg`     | String  | 请求结果说明。                         |

`code=200`  业务表示已受理，不代表发票、退款或红冲已完成。最终状态以发票查询或回调为准。

成功响应的 `data` 内统一包含 `sign`。平台使用平台私钥对 `data` 内除 `sign` 外的字段签名，商户使用平台公钥验签，规则见第 1.5 节。

```json
{
  "code": 200,
  "success": true,
  "data": {
    "order_code": "801012026080315300001",
    "out_trade_no": "T202608030001",
    "order_amount": 95.00,
    "pay_amount": 95.00,
    "pay_status": "PAYING",
    "sign": "Base64格式RSA签名"
  },
  "msg": "操作成功"
}
```

上例响应的待签名文本为 `order_amount=95.00&order_code=801012026080315300001&out_trade_no=T202608030001&pay_amount=95.00&pay_status=PAYING`

### 1.6.1 失败响应

失败时返回不生成 `data.sign`。

```json
{
  "code": 400,
  "success": false,
  "data": null,
  "msg": "签名校验失败"
}
```

公共参数缺失、`biz_content` 格式错误、终端或密钥无效、签名失败、字段校验失败以及业务服务拒绝，均按此结构返回。

## 1.7 字段说明

### 1.7.1 状态字段

| 字段             | 可见值      | 描述                       |
| ---------------- | ----------- | -------------------------- |
| `pay_status`     | `PAYING`    | 支付中，包含等待用户支付。 |
|                  | `SUCCESS`   | 交易成功。                 |
|                  | `FAIL`      | 交易失败。                 |
|                  | `CLOSED`    | 交易已关闭。               |
| `invoice_status` | `PENDING`   | 待开票。                   |
|                  | `ISSUING`   | 开票中。                   |
|                  | `SUCCESS`   | 开票成功。                 |
|                  | `FAIL`      | 开票失败。                 |
| `refund_status`  | `REFUNDING` | 退款中。                   |
|                  | `SUCCESS`   | 退款成功。                 |
|                  | `FAIL`      | 退款失败。                 |
| `red_status`     | `REVERSING` | 红冲中。                   |
|                  | `SUCCESS`   | 红冲成功。                 |
|                  | `FAIL`      | 红冲失败。                 |
| `change_status`  | `CHANGING`  | 换开中。                   |
|                  | `SUCCESS`   | 换开成功。                 |
|                  | `FAIL`      | 换开失败。                 |

支付即开票和发票开具均使用 `out_trade_no` 作为商户业务订单号。同一 `rpi_no` 商户下默认不得重复；**仅支付后开具发票时复用原支付单号**，见 1.7.2。

### 1.7.2 开票路径

1. **支付即开票**
   - `is_invoice=1`：支付成功后平台开票。工行必须传 `1`。购方、商品、特定要素不传时取系统默认。
   - `is_invoice=0`：只支付、不开票。
2. **发票开具**
   - 不传 `order_code`：未关联支付开具。`out_trade_no` 须使用新的商户单号，同一 `rpi_no` 下不得与已有订单重复。
   - 传 `order_code`：对「已付未开」订单开具发票，须同时满足：
     - `order_code` 为原支付即开票返回的平台单号
     - `out_trade_no` 为原支付请求的商户单号
     - `order_amount` 等于该笔交易金额

```mermaid
flowchart TD
  C["支付即开票<br/>rsypay.invoice.payment.issue"] --> E{"is_invoice"}
  E -->|"1 开，工行必传 1"| F["支付成功后平台开票"]
  F --> G["改抬头走换开"]
  E -->|"0 不开"| H["只收款"]
  H -->|"之后调发票开具"| D
  D["发票开具<br/>rsypay.invoice.cash.issue"] --> M{"是否传 order_code"}
  M -->|否| N["未关联支付：out_trade_no 用新单号"]
  M -->|是| J{"order_code、out_trade_no、order_amount 是否与原单一致"}
  J -->|是| K["开票"]
  J -->|否| L["拒绝"]
```

## 1.8 公共业务对象

### 1.8.1 `buyer_info` 购方信息

| 名称                  | 类型    | 是否必须     | 描述                                           |
| --------------------- | ------- | ------------ | ---------------------------------------------- |
| `buyer_name`          | String  | 传本对象时是 | 购方名称。                                     |
| `natural_flag`        | Integer | 传本对象时是 | `0` 企业或非自然人；`1` 自然人。               |
| `buyer_tax_no`        | String  | 条件必填     | 企业购方税号；企业开具专票时必填。             |
| `buyer_phone`         | String  | 否           | 购方电话。                                     |
| `buyer_address`       | String  | 否           | 购方地址。                                     |
| `buyer_bank_name`     | String  | 否           | 购方开户行名称。                               |
| `buyer_bank_account`  | String  | 否           | 购方银行账号。                                 |
| `natural_nationality` | String  | 条件必填     | 自然人国籍 `1`中国。与证件类型、证件号同时传。 |
| `natural_cert_type`   | String  | 条件必填     | 自然人证件类型 `1`身份证。                     |
| `natural_cert_no`     | String  | 条件必填     | 自然人证件号码。                               |
| `receive_email`       | String  | 否           | 发票接收邮箱。                                 |
| `receive_phone`       | String  | 否           | 发票接收手机号。                               |

### 1.8.2 `item_list` 商品及折扣行

发票开具必须传 `item_list`。支付即开票可选，不传取系统配置默认。

| 名称                  | 类型    | 是否必须 | 描述                                                         |
| --------------------- | ------- | -------- | ------------------------------------------------------------ |
| `item_no`             | Integer | 是       | 发票行号                                                     |
| `invoice_nature`      | Integer | 是       | `1` 被折扣行，`2` 正常行，`3` 折扣行。                       |
| `product_name`        | String  | 是       | 商品名称；折扣行与被折扣行一致                               |
| `tax_product_code`    | String  | 是       | 税收分类编码                                                 |
| `tax_product_name`    | String  | 是       | 税收分类名称                                                 |
| `product_spec`        | String  | 条件必填 | 规格型号                                                     |
| `product_unit`        | String  | 条件必填 | 计量单位，传系统字典键：`1`=L、`2`=KG、`3`=m³、`4`=升、`5`=公斤、`6`=件、`7`=个。 |
| `price`               | Decimal | 条件必填 | 含税单价                                                     |
| `quantity`            | Decimal | 条件必填 | 数量                                                         |
| `amount`              | Decimal | 是       | 含税行金额；正常/被折扣行为正数，折扣行为负数                |
| `tax_rate`            | Decimal | 是       | 税率小数比例，例如 `0.13` 表示 13%。                         |
| `discount_amount`     | Decimal | 是       | 商品对应优惠金额 无优惠时传 `0`                              |
| `real_amount`         | Decimal | 是       | 商品实收金额，计算公式：价税合计-优惠金额                    |
| `preferential_policy` | String  | 否       | 税收优惠政策编码，适用时传；                                 |
| `tax_rate_type`       | String  | 否       | 税率处理类型，免税、不征税或零税率等场景适用。               |

### 1.8.3 特定要素

| 名称            | 类型   | 是否必须 | 描述                                               |
| --------------- | ------ | -------- | -------------------------------------------------- |
| `element_code`  | String | 是       | 特定要素编码；普通商品传 `Y00000000`。             |
| `element_value` | Object | 条件必填 | 特定要素明细对象；字段结构由 `element_code` 决定。 |

`Y00000000` 为非特定要素，不需要传 `element_value`。当前开放平台支持以下特定要素对象。

#### 1.8.3.1 旅客运输 `element_value`

`element_code=Y00000003` 时传递

| 名称          | 类型   | 是否必须 | 描述                                                         |
| ------------- | ------ | -------- | ------------------------------------------------------------ |
| `name`        | String | 是       | 出行人姓名。                                                 |
| `idType`      | String | 否       | 证件类型编码；100：单位  101：组织机构代码证  102：营业执照  103：税务登记证  199：其他单位证件  200：个人  201：居民身份证 |
| `idNo`        | String | 否       | 证件号码。                                                   |
| `travelDate`  | String | 否       | 出行日期，格式 `yyyy-MM-dd`；未传时送当前交易日期            |
| `depart`      | String | 是       | 出发地。                                                     |
| `arrive`      | String | 是       | 到达地。                                                     |
| `vehicleType` | String | 是       | 交通工具类型：`1`飞机、`2`火车、`3`长途汽车、`4`公共交通、`5`出租车、`6`汽车、`7`船舶、`9`其他。 |
| `seatLevel`   | String | 是       | 座位等级编码 1公务舱、2头等舱、3经济舱、4一等座、5二等座、6软席（软座、软卧）、7硬席（硬座、硬卧）、8出租车、9一等舱、10二等舱、11三等舱 |

```json
{
  "name": "张三",
  "idType": "201",
  "idNo": "110101199001011234",
  "travelDate": "2026-08-04",
  "depart": "北京",
  "arrive": "上海",
  "vehicleType": "2",
  "seatLevel": "2"
}
```

#### 1.8.3.2 成品油 `element_value`

`element_code=Y00000006` 时传递。版本为 `1.1` 时保持现有字段结构；版本为 `1.2` 时增加油机联动字段。油品名称、税收分类编码、税率、单价、数量和金额仍在 `item_list` 中传递。

| 名称                   | 类型   | 是否必须 | 描述                                                                  |
| ---------------------- | ------ | -------- | --------------------------------------------------------------------- |
| `oil_gun_name`         | String | 否       | 版本 `1.1` 的油枪名称，例如 `1号枪`；版本 `1.2` 继续兼容传递。       |
| `oil_gun_no`           | String | 否       | 版本 `1.2` 新增，油枪编号。                                           |
| `oil_machine_order_no` | String | 否       | 版本 `1.2` 新增，油机联动订单号。                                     |

版本 `1.1` 示例：

```json
{
  "oil_gun_name": "1号枪"
}
```

版本 `1.2` 油机联动示例：

```json
{
  "oil_gun_no": "1",
  "oil_machine_order_no": "OM202609050001"
}
```

`item_list`、`buyer_info`、`element_value` 在业务接口中均作为 JSON 对象或数组传入，不用再次序列化为 JSON 字符串。

### 1.8.4 `detail_wx` 微信单品优惠活动

| 参数         | 类型   | 必填 | 参数说明                                                |
| :----------- | :----- | :--- | :------------------------------------------------------ |
| cost_price   | double | 否   | 订单原价，整数不超过14位，小数不 超过2位，单位元 10．50 |
| receipt_id   | String | 否   | 商品小票ID，长度不能超过32位 Ys001001                   |
| goods_tag    | String | 否   | 订单优惠标记，代金券或立减优惠功能的参数                |
| goods_detail | List   | 是   | 商品列表                                                |

- goods_detail 微信商品列表

| 参数           | 类型   | 必填 | 参数说明                                                     |
| :------------- | :----- | :--- | :----------------------------------------------------------- |
| goods_id       | String | 是   | 商户商品编码,由半角的大小写字母，数字，下划线，中划线中的一种或者几种组成，长度不能超过32位 Shouji_abcef_001-001 |
| wxpay_goods_id | String | 否   | 微信支付定义的统一商品编号，长度不能超过32 ,1001             |
| goods_name     | String | 否   | 商品的实际名称，长度不能超过256                              |
| quantity       | int    | 是   | 数量，只能是正整数 ,1000                                     |
| price          | Double | 是   | 商品单价，单位元，整数部分不能超过12位，小数不能超过2位 , 100.20 |

# 2. 开票业务接口

## 2.1 支付即开票

- method：`rsypay.invoice.payment.issue`

### 2.1.1 请求参数

| 名称              | 类型    | 是否必须     | 描述                                                         |
| ----------------- | ------- | ------------ | ------------------------------------------------------------ |
| `out_trade_no`    | String  | 是           | 商户支付订单号；同一 `rpi_no` 商户下唯一。                   |
| `pay_amount`      | Decimal | 是           | 支付金额                                                     |
| `pay_way`         | String  | 是           | `1` 微信、`2` 支付宝、`3` 银联/云闪付。 pay_scene为`QRCODE`时，可不传入。 |
| `pay_scene`       | String  | 是           | `JSAPI` 公众号/小程序支付；`BARCODE` 付款码支付。 `QRCODE` 中台页跳转支付。 |
| `user_code`       | String  | JSAPI 时是   | 用户授权标识。                                               |
| `auth_code`       | String  | BARCODE 时是 | 用户付款码；                                                 |
| `is_minipg`       | String  | 否           | `1` 小程序、`2` 公众号。 默认不送时使用平台公众号            |
| `appid`           | String  | 否           | 公众号或小程序 appid。 默认不送时使用平台公众号              |
| `subject`         | String  | 否           | 订单备注。                                                   |
| `timeout_express` | String  | 否           | 设置未付款交易的超时时间，一旦超时，该笔交易就会自动被关闭，取值范围：1m～15d。m-分钟，h-小时，d-天。该参数数值不接受小数点，如1.5h，可转换为90m。注意：设置了未付款交易超时时间的情况下，若我司在限定时间内没有收到成功支付通知，则会关闭交易，关闭后该笔交易若付款方支付成功的情况下，会自动原路退款至付款方。 示例值：96h 代表96小时后订单自动关闭 不传默认15m |
| `other_content`   | String  | 否           | 业务透传信息。                                               |
| `invoice_type`    | String  | 否           | `01` 数电专票，`02` 数电普票。                               |
| `buyer_info`      | Object  | 否           | 见 `buyer_info` 购方信息。不传取系统配置默认                 |
| `item_list`       | Array   | 否           | 见 `item_list` 商品明细信息。不传取系统配置默认              |
| `element_code`    | String  | 否           | 见`1.8.3`特定要素。                                          |
| `element_value`   | Object  | 条件必填     | 见`1.8.3`特定要素。                                          |
| `is_invoice`      | String  | 是           | 是否开票。`1` 支付成功后开票；`0` 只支付不开票。工行必须传 `1`。 |
| `detail_wx`       | String  | 否           | 银盛微信单品优惠明细见`1.8.4`，传原始 JSON 字符串；其他通道暂省略。 |
| `remark`          | String  | 否           | 发票备注。                                                   |
| `notify_url`      | String  | 否           | 支付及开票结果通知地址。                                     |

### 2.1.2 响应参数

| 名称                 | 类型    | 描述                                         |
| -------------------- | ------- | -------------------------------------------- |
| `order_code`         | String  | 平台支付订单号。                             |
| `out_trade_no`       | String  | 商户支付订单号。                             |
| `inv_order_id`       | String  | 发票业务编号。                               |
| `subject`            | String  | 条件返回；订单备注。                         |
| `other_content`      | String  | 条件返回；业务透传信息。                     |
| `aisle_order_code`   | String  | 通道商户订单号；付款码场景可作为条码订单号。 |
| `official_order_no`  | String  | 通道官方订单号。                             |
| `order_amount`       | Decimal | 订单金额。                                   |
| `pay_amount`         | Decimal | 支付金额。                                   |
| `js_api`             | String  | JSAPI 场景返回的支付拉起参数。               |
| `invoice_qr_content` | String  | 开票二维码内容                               |
| `pay_status`         | String  | 支付状态，取值见 1.7.1。                     |
| `sign`               | String  | `data` 业务字段签名。                        |
| `payUrl`             | String  | 中台页支付跳转url。pay_scene为QRCODE时返回   |

### 2.1.3 `biz_content` 示例

```json
{
  "out_trade_no": "T202608030001",
  "order_amount": 95.00,
  "pay_amount": 95.00,
  "pay_way": "1",
  "pay_scene": "JSAPI",
  "user_code": "oKxxxxx",
  "is_minipg": "1",
  "appid": "wx1234567890",
  "invoice_type": "02",
  "buyer_info": {
    "buyer_name": "北京示例科技有限公司",
    "natural_flag": 0,
    "buyer_tax_no": "91110108XXXXXXXXXX",
    "receive_email": "invoice@example.com"
  },
  "item_list": [
    {
      "item_no": 1,
      "invoice_nature": 2,
      "product_name": "商品A",
      "tax_product_code": "1070101010000000000",
      "tax_product_name": "商品A",
      "product_spec": "标准",
      "product_unit": "6",
      "price": 95.00,
      "quantity": 1,
      "amount": 95.00,
      "tax_rate": 0.13
    }
  ],
  "element_code": "Y00000000",
  "is_invoice": "1",
  "notify_url": "https://merchant.example.com/api/invoice/notify"
}
```

付款码支付将 `pay_scene` 改为 `BARCODE`，并传递 `auth_code`；不传 `user_code`、`is_minipg`、`appid`。

```json
{
  "pay_scene": "BARCODE",
  "auth_code": "134567890123456789"
}
```

## 2.2 发票开具

- method：`rsypay.invoice.cash.issue`

**业务说明：**

本接口根据是否传入 `order_code` 区分开票场景：未传 `order_code`（平台支付订单号）时，为未关联支付的现金开票；传入 `order_code` 时，为对已付未开订单开具发票。`out_trade_no` 仍为必传字段，关联支付时的参数要求见 1.7.2。

现金开票时，`buyer_info` 为非必传：

- 未传 `buyer_info`：平台返回 `invoice_qr_content` 开票二维码内容，用户扫码进入小程序后可补充购方信息并完成开票，或办理换开。
- 传入 `buyer_info`：平台按所传购方信息进行现金开票；接口仍返回 `invoice_qr_content`，用户可扫码进入小程序办理换开。

### 2.2.1 请求参数

| 名称            | 类型    | 是否必须 | 描述                                                         |
| --------------- | ------- | -------- | ------------------------------------------------------------ |
| `out_trade_no`  | String  | 是       | 商户业务订单号。未关联支付须使用新的商户单号，同一 `rpi_no` 下不得与已有订单重复；关联支付时必须传原支付请求的商户单号，见 1.7.2。 |
| `order_code`    | String  | 否       | 平台支付订单号。关联支付时必传，且须为原支付即开票返回的平台单号。 |
| `order_amount`  | Decimal | 是       | 订单金额。关联支付时必须等于原交易金额。                     |
| `invoice_type`  | String  | 否       | `01` 数电专票，`02` 数电普票。                               |
| `trade_time`    | String  | 否       | 交易发生时间，格式：`yyyy-MM-dd HH:mm:ss` 不传默认取接口发起时间 |
| `buyer_info`    | Object  | 否       | 见 `buyer_info`。                                            |
| `item_list`     | Array   | 是       | 见 `item_list`。                                             |
| `element_code`  | String  | 是       | 见特定要素。                                                 |
| `element_value` | Object  | 条件必填 | 见特定要素。                                                 |
| `remark`        | String  | 否       | 发票备注。                                                   |
| `notify_url`    | String  | 否       | 开票结果通知地址。                                           |

### 2.2.2 响应参数

| 名称                 | 类型    | 描述                  |
| -------------------- | ------- | --------------------- |
| `out_trade_no`       | String  | 商户业务订单号。      |
| `inv_order_id`       | String  | 发票业务编号。        |
| `order_amount`       | Decimal | 订单金额。            |
| `invoice_qr_content` | String  | 开票二维码内容        |
| `sign`               | String  | `data` 业务字段签名。 |

### 2.2.3 `biz_content` 示例

```json
{
  "out_trade_no": "C202608030001",
  "order_amount": 95.00,
  "invoice_type": "02",
  "buyer_info": {
    "buyer_name": "北京示例科技有限公司",
    "natural_flag": 0,
    "buyer_tax_no": "91110108XXXXXXXXXX"
  },
  "item_list": [
    {
      "item_no": 1,
      "invoice_nature": 2,
      "product_name": "商品A",
      "tax_product_code": "1070101010000000000",
      "tax_product_name": "商品A",
      "product_spec": "标准",
      "product_unit": "6",
      "price": 95.00,
      "quantity": 1,
      "amount": 95.00,
      "tax_rate": 0.13
    }
  ],
  "element_code": "Y00000000",
  "notify_url": "https://merchant.example.com/api/invoice/notify"
}
```

支付后开具发票须传原支付单号和平台单号，`order_amount` 与原交易金额一致：

```json
{
  "out_trade_no": "T202608030001",
  "order_code": "801012026080315300001",
  "order_amount": 95.00,
  "invoice_type": "02",
  "buyer_info": {
    "buyer_name": "北京示例科技有限公司",
    "natural_flag": 0,
    "buyer_tax_no": "91110108XXXXXXXXXX"
  },
  "item_list": [
    {
      "item_no": 1,
      "invoice_nature": 2,
      "product_name": "商品A",
      "tax_product_code": "1070101010000000000",
      "tax_product_name": "商品A",
      "product_spec": "标准",
      "product_unit": "6",
      "price": 95.00,
      "quantity": 1,
      "amount": 95.00,
      "tax_rate": 0.13
    }
  ],
  "element_code": "Y00000000",
  "notify_url": "https://merchant.example.com/api/invoice/notify"
}
```

## 2.3 发票查询

- method：`rsypay.invoice.query`

本接口统一返回支付状态、蓝票状态、退款汇总、红冲状态和换开状态。未关联支付不返回支付相关字段；

### 2.3.1 请求参数

查询标识三选一，每次请求只能传一个。可使用发票业务编号、平台支付订单号或商户业务订单号

| 名称           | 类型   | 是否必须 | 描述                                           |
| -------------- | ------ | -------- | ---------------------------------------------- |
| `inv_order_id` | String | 三选一   | 发票业务编号。                                 |
| `order_code`   | String | 三选一   | 平台订单号。                                   |
| `out_trade_no` | String | 三选一   | 商户业务订单号，支付即开票或发票开具均可使用。 |

### 2.3.2 响应参数

| 名称                    | 类型    | 描述                                                         |
| ----------------------- | ------- | ------------------------------------------------------------ |
| `inv_order_id`          | String  | 发票业务编号。                                               |
| `order_code`            | String  | 条件返回；平台支付订单号。未关联支付不返回；支付即开票、关联支付时返回。 |
| `out_trade_no`          | String  | 商户业务订单号，支付即开票和发票开具均返回。                 |
| `subject`               | String  | 条件返回；支付即开票的订单备注。                             |
| `other_content`         | String  | 条件返回；支付即开票的业务透传信息。                         |
| `aisle_order_code`      | String  | 通道商户订单号；付款码场景可作为条码订单号。                 |
| `official_order_no`     | String  | 通道官方订单号。                                             |
| `invoice_type`          | String  | 发票类型。`01` 数电专票，`02` 数电普票。                     |
| `invoice_status`        | String  | 蓝票状态，取值见 1.7.1。                                     |
| `invoice_code`          | String  | 蓝字发票号码。                                               |
| `invoice_apply_time`    | String  | 申请开票时间。                                               |
| `invoice_complete_time` | String  | 开票完成时间。                                               |
| `pay_status`            | String  | 交易状态；支付即开票时返回，取值见 1.7.1。                   |
| `order_amount`          | Decimal | 订单金额，支付即开票和发票开具均返回。                       |
| `pay_amount`            | Decimal | 支付金额；                                                   |
| `pay_way`               | String  | 支付方式；未关联支付时不返回。                               |
| `pay_time`              | String  | 支付完成时间；未关联支付时不返回。                           |
| `is_refund`             | String  | 是否有退款（0无退款 1部分退款 2全部退款）                    |
| `total_refund_amount`   | Decimal | 当前累计退款金额，含退款中的金额，退款失败后回退；未关联支付时不返回。 |
| `red_status`            | String  | 红冲状态；存在红票时返回，取值见 1.7.1。                     |
| `change_status`         | String  | 已发起换开时返回，取值见 1.7.1。                             |
| `buyer_info`            | Object  | 购方信息。                                                   |
| `item_list`             | Array   | 商品行。                                                     |
| `element_code`          | String  | 特定要素编码。                                               |
| `element_value`         | Object  | 特定要素对象。                                               |
| `remark`                | String  | 发票备注。                                                   |
| `error_reason`          | String  | 失败原因。                                                   |
| `sign`                  | String  | `data` 业务字段签名。                                        |

### 2.3.3 `biz_content` 示例

```json
{
  "inv_order_id": "INV801012026080315300001"
}
```

## 2.4 换开发票

- method：`rsypay.invoice.change`

### 2.4.1 请求参数

| 名称           | 类型   | 是否必须 | 描述                                           |
| -------------- | ------ | -------- | ---------------------------------------------- |
| `inv_order_id` | String | 三选一   | 发票业务编号。                                 |
| `order_code`   | String | 三选一   | 平台订单号。                                   |
| `out_trade_no` | String | 三选一   | 商户业务订单号，支付即开票或发票开具均可使用。 |
| `invoice_type` | String | 是       | `01` 数电专票，`02` 数电普票。                 |
| `buyer_info`   | Object | 是       | 新购方信息。                                   |
| `notify_url`   | String | 否       | 换开结果通知地址。                             |

### 2.4.2 响应参数

| 名称            | 类型   | 描述                     |
| --------------- | ------ | ------------------------ |
| `inv_order_id`  | String | 原蓝票发票业务编号。     |
| `change_status` | String | 换开状态，取值见 1.7.1。 |
| `error_reason`  | String | 错误原因                 |
| `sign`          | String | `data` 业务字段签名。    |

### 2.4.3 `biz_content` 示例

```json
{
  "inv_order_id": "INV801012026080315300001",
  "invoice_type": "02",
  "buyer_info": {
    "buyer_name": "北京示例科技有限公司",
    "natural_flag": 0,
    "buyer_tax_no": "91110108XXXXXXXXXX"
  },
  "notify_url": "https://merchant.example.com/api/invoice/notify"
}
```

## 2.5 退款即红冲

- method：`rsypay.invoice.refund.reverse`

### 2.5.1 请求参数

| 名称               | 类型    | 是否必须 | 描述                                                         |
| ------------------ | ------- | -------- | ------------------------------------------------------------ |
| `order_code`       | String  | 三选一   | 平台支付订单号。                                             |
| `out_trade_no`     | String  | 三选一   | 商户支付订单号。                                             |
| `aisle_order_code` | String  | 三选一   | 通道商户订单号；付款码场景可作为条码订单号。                 |
| `out_refund_no`    | String  | 是       | 商户退款业务号；同一 `rpi_no`商户 下唯一，退款即红冲和仅退款不得复用。 |
| `refund_amount`    | Decimal | 是       | 退款金额(必须全额退款)。                                     |
| `refund_offset`    | String  | 是       | 红冲原因   01：开票有误，02：销货退回，03：服务中止          |
| `refund_reason`    | String  | 是       | 退款备注。                                                   |
| `notify_url`       | String  | 否       | 退款及红冲结果通知地址。                                     |

### 2.5.2 响应参数

| 名称                 | 类型    | 描述                                               |
| -------------------- | ------- | -------------------------------------------------- |
| `order_code`         | String  | 平台支付订单号。                                   |
| `inv_order_id`       | String  | 原蓝票发票业务编号。                               |
| `out_refund_no`      | String  | 商户退款业务号。                                   |
| `refund_amount`      | Decimal | 本次退款金额。                                     |
| `order_request_code` | String  | 平台退款请求号。                                   |
| `refund_status`      | String  | 退款状态，取值见 1.7.1。                           |
| `red_status`         | String  | 条件返回；关联红冲流程已开始时返回，取值见 1.7.1。 |
| `sign`               | String  | `data` 业务字段签名。                              |

### 2.5.3 `biz_content` 示例

```json
{
  "order_code": "801012026080315300001",
  "out_refund_no": "R202608030001",
  "refund_amount": 95.00,
  "refund_reason": "退款申请",
  "notify_url": "https://merchant.example.com/api/invoice/notify"
}
```

## 2.6 仅退款

- method：`rsypay.invoice.refund`

### 2.6.1 请求参数

| 名称               | 类型    | 是否必须 | 描述                                                         |
| ------------------ | ------- | -------- | ------------------------------------------------------------ |
| `order_code`       | String  | 三选一   | 平台支付订单号。                                             |
| `out_trade_no`     | String  | 三选一   | 商户支付订单号。                                             |
| `aisle_order_code` | String  | 三选一   | 通道商户订单号；付款码场景可作为条码订单号。                 |
| `out_refund_no`    | String  | 是       | 商户退款业务号；同一 `rpi_no`商户 下唯一，退款即红冲和仅退款不得复用。 |
| `refund_amount`    | Decimal | 是       | 退款金额。                                                   |
| `refund_reason`    | String  | 是       | 退款备注。                                                   |
| `notify_url`       | String  | 否       | 退款结果通知地址。                                           |

### 2.6.2 响应参数

| 名称                 | 类型    | 描述                     |
| -------------------- | ------- | ------------------------ |
| `order_code`         | String  | 平台支付订单号。         |
| `out_refund_no`      | String  | 商户退款业务号。         |
| `refund_amount`      | Decimal | 本次退款金额。           |
| `order_request_code` | String  | 平台退款请求号。         |
| `refund_status`      | String  | 退款状态，取值见 1.7.1。 |
| `sign`               | String  | `data` 业务字段签名。    |

### 2.6.3 `biz_content` 示例

```json
{
  "order_code": "801012026080315300001",
  "out_refund_no": "R202608030002",
  "refund_amount": 95.00,
  "refund_reason": "退款申请",
  "notify_url": "https://merchant.example.com/api/invoice/notify"
}
```

## 2.7 仅红冲

- method：`rsypay.invoice.reverse`
- 仅适用于未关联支付的蓝票，按整票红冲。

### 2.7.1 请求参数

| 名称            | 类型   | 是否必须 | 描述                                                |
| --------------- | ------ | -------- | --------------------------------------------------- |
| `inv_order_id`  | String | 二选一   | 原未关联支付蓝票的发票业务编号。                    |
| `out_trade_no`  | String | 二选一   | 商户支付订单号。                                    |
| `refund_offset` | String | 是       | 红冲原因   01：开票有误，02：销货退回，03：服务中止 |
| `red_reason`    | String | 是       | 红冲备注。                                          |
| `notify_url`    | String | 否       | 红冲结果通知地址。                                  |

### 2.7.2 响应参数

| 名称           | 类型   | 描述                             |
| -------------- | ------ | -------------------------------- |
| `inv_order_id` | String | 原未关联支付蓝票的发票业务编号。 |
| `red_status`   | String | 红冲状态，取值见 1.7.1。         |
| `sign`         | String | `data` 业务字段签名。            |

### 2.7.3 `biz_content` 示例

```json
{
  "inv_order_id": "INV801012026080315300001",
  "red_reason": "未关联支付红冲",
  "notify_url": "https://merchant.example.com/api/invoice/notify"
}
```

## 2.8 退款查询

- method：`rsypay.invoice.refund.query`
- 本接口同步查询单笔退款结果，不传 `notify_url`。

### 2.8.1 请求参数

查询标识二选一，每次请求只能传一个。

| 名称                 | 类型   | 是否必须 | 描述             |
| -------------------- | ------ | -------- | ---------------- |
| `out_refund_no`      | String | 二选一   | 商户退款业务号。 |
| `order_request_code` | String | 二选一   | 平台退款请求号。 |

### 2.8.2 响应参数

| 名称                 | 类型    | 描述                                                   |
| -------------------- | ------- | ------------------------------------------------------ |
| `out_refund_no`      | String  | 商户退款业务号。                                       |
| `order_request_code` | String  | 平台退款请求号。                                       |
| `out_trade_no`       | String  | 商户支付订单号。                                       |
| `order_code`         | String  | 平台支付订单号。                                       |
| `inv_order_id`       | String  | 条件返回；退款即红冲时返回关联的发票业务编号。         |
| `refund_amount`      | Decimal | 本次退款金额。                                         |
| `refund_status`      | String  | 退款状态，取值见 1.7.1。                               |
| `red_status`         | String  | 条件返回；退款即红冲时返回关联红冲状态，取值见 1.7.1。 |
| `result_note`        | String  | 条件返回；结果说明，退款或红冲失败时必须返回失败原因。 |
| `sign`               | String  | `data` 业务字段签名。                                  |

`refund_amount` 表示当前这一笔退款金额。订单累计退款金额继续通过发票查询接口的 `total_refund_amount` 获取。

### 2.8.3 `biz_content` 示例

```json
{
  "out_refund_no": "R202608030001"
}
```

## 2.9 发票下载

- method：`rsypay.invoice.download`
- 请求按第 1.5 节规则进行 RSA 验签；成功响应 `data` 按第 1.5 节规则返回 `sign`。
- 平台统一返回 PDF 文件的 Base64 内容；上游通道是否带签名不影响本平台对下游的统一响应协议。

### 2.9.1 请求参数

| 名称           | 类型   | 是否必须 | 描述           |
| -------------- | ------ | -------- | -------------- |
| `inv_order_id` | String | 是       | 发票业务编号。 |

### 2.9.2 响应参数

| 名称           | 类型   | 描述                     |
| -------------- | ------ | ------------------------ |
| `inv_order_id` | String | 发票业务编号。           |
| `file_content` | String | PDF 文件的 Base64 内容。 |
| `sign`         | String | `data` 业务字段签名。    |

### 2.9.3 `biz_content` 示例

```json
{
  "inv_order_id": "INV801012026080315300001"
}
```

成功响应中的 `file_content` 示例会因内容较长而省略：

```json
{
  "code": 200,
  "success": true,
  "data": {
      "inv_order_id": "INV801012026080315300001",
      "file_content": "JVBERi0xLjQK...",
      "sign": "Base64格式RSA签名"
  },
  "msg": "操作成功"
}
```

# 3. 结果回调（平台推送）

## 3.1 回调处理约定

平台向业务请求中的 `notify_url` 发送 POST JSON。

```json
{
  "appkey": "000001",
  "method": "rsypay.invoice.payment.notify",
  "rpi_no": "RPI001",
  "notice_time": "2026-08-05 15:30:20",
  "order_code": "801012026080515300001",
  "out_trade_no": "T202608050001",
  "pay_amount": 95.00,
  "pay_status": "SUCCESS",
  "sign": "Base64格式RSA签名"
}
```

| 项目         | 约定                                                         |
| ------------ | ------------------------------------------------------------ |
| 请求方式     | HTTP POST                                                    |
| Content-Type | `application/json; charset=UTF-8`                            |
| 成功应答     | 回调请求体是 JSON，但商户成功应答仍返回纯文本 `success`（小写），不再包装成 JSON。 |
| 重试         | 首次立即推送；首次失败后最多重试 3 次，分别延迟 1 分钟、5 分钟、10 分钟，总计最多投递 4 次（含首次）。连接异常、超时或应答正文不是 `success` 均按失败处理。 |
| 验签         | 对回调最外层除 `sign` 外的字段验签，规则见第 1.5 节。        |

回调分为三个 method：

| method                          | 说明                           |
| ------------------------------- | ------------------------------ |
| `rsypay.invoice.payment.notify` | 支付结果推送。                 |
| `rsypay.invoice.status.notify`  | 发票开具、换开或红冲状态推送。 |
| `rsypay.invoice.refund.notify`  | 退款结果推送。                 |

三个推送均固定包含 `appkey`、`method`、`rpi_no`、`sign`，以下参数表仅列出各推送的业务字段。

## 3.2 支付结果推送

- method：`rsypay.invoice.payment.notify`

### 3.2.1 推送参数

| 名称                | 类型    | 是否必有 | 描述                                                         |
| ------------------- | ------- | -------- | ------------------------------------------------------------ |
| `notice_time`       | String  | 是       | 通知时间，格式 `yyyy-MM-dd HH:mm:ss`。                       |
| `order_code`        | String  | 是       | 平台支付订单号。                                             |
| `out_trade_no`      | String  | 是       | 商户支付订单号。                                             |
| `pay_amount`        | Decimal | 是       | 支付订单金额，与发起请求的 `pay_amount` 一致；支付成功时即实际支付金额。 |
| `pay_status`        | String  | 是       | 支付状态，取值见 1.7.1。                                     |
| `aisle_order_code`  | String  | 条件返回 | 通道商户订单号；付款码场景可作为条码订单号。                 |
| `official_order_no` | String  | 条件返回 | 通道官方订单号。                                             |
| `other_content`     | String  | 条件返回 | 支付即开票请求传入时原样返回。                               |
| `result_note`       | String  | 否       | 结果说明；                                                   |

### 3.2.2 回调示例

```json
{
  "appkey": "000001",
  "method": "rsypay.invoice.payment.notify",
  "rpi_no": "RPI001",
  "notice_time": "2026-08-05 15:30:20",
  "order_code": "801012026080515300001",
  "out_trade_no": "T202608050001",
  "pay_amount": 95.00,
  "pay_status": "SUCCESS",
  "aisle_order_code": "A202608050001",
  "official_order_no": "O202608050001",
  "other_content": "merchant-data",
  "sign": "Base64格式RSA签名"
}
```

## 3.3 发票状态变更推送

- method：`rsypay.invoice.status.notify`

该回调覆盖蓝票开具、换开和红冲。

### 3.3.1 推送参数

| 名称            | 类型    | 是否必有 | 描述                                                         |
| --------------- | ------- | -------- | ------------------------------------------------------------ |
| `notice_time`   | String  | 是       | 通知时间，格式 `yyyy-MM-dd HH:mm:ss`。                       |
| `notice_type`   | String  | 是       | 通知类型 1蓝票 2换开 3红冲                                   |
| `out_trade_no`  | String  | 是       | 商户业务订单号。                                             |
| `order_code`    | String  | 条件返回 | 平台支付订单号；未关联支付不返回。                           |
| `inv_order_id`  | String  | 是       | 发票业务编号。                                               |
| `order_amount`  | Decimal | 是       | 订单金额。                                                   |
| `pay_amount`    | Decimal | 是       | 支付金额。                                                   |
| `invoice_type`  | String  | 条件返回 | 发票类型：`01` 数电专票、`02` 数电普票；开票或换开结果返回。 |
| `inv_status`    | String  | 是       | 状态码，根据通知类型取值见 1.7.1  1蓝票：**invoice_status** 2换开：**change_status**  3红冲：**red_status** |
| `invoice_code`  | String  | 条件返回 | 蓝字发票号码；                                               |
| `other_content` | String  | 条件返回 | 商户透传参数                                                 |
| `result_note`   | String  | 条件返回 | 结果说明；返回失败原因。                                     |

### 3.3.2 开票结果示例

```json
{
  "appkey": "000001",
  "method": "rsypay.invoice.status.notify",
  "rpi_no": "RPI001",
  "notice_time": "2026-08-05 15:31:20",
  "notice_type": "1",
  "order_code": "801012026080515300001",
  "out_trade_no": "T202608050001",
  "inv_order_id": "INV801012026080515300001",
  "order_amount": 95.00,
  "pay_amount": 95.00,
  "invoice_type": "02",
  "inv_status": "SUCCESS",
  "invoice_code": "25442000000000000123",
  "sign": "Base64格式RSA签名"
}
```

## 3.4 退款结果推送

- method：`rsypay.invoice.refund.notify`

### 3.4.1 推送参数

| 名称                 | 类型    | 是否必有 | 描述                                                |
| -------------------- | ------- | -------- | --------------------------------------------------- |
| `notice_time`        | String  | 是       | 通知时间，格式 `yyyy-MM-dd HH:mm:ss`。              |
| `order_code`         | String  | 是       | 平台支付订单号。                                    |
| `out_trade_no`       | String  | 是       | 商户支付订单号。                                    |
| `out_refund_no`      | String  | 是       | 商户退款业务号。                                    |
| `order_request_code` | String  | 是       | 平台退款请求号。                                    |
| `refund_amount`      | Decimal | 是       | 本次退款金额。                                      |
| `refund_status`      | String  | 是       | 退款状态，取值见 1.7.1。                            |
| `result_note`        | String  | 条件返回 | 结果说明；`refund_status=FAIL` 时必须返回失败原因。 |

退款即红冲会分别推送退款结果和红冲结果：退款结果使用 `rsypay.invoice.refund.notify`，红冲结果使用 `rsypay.invoice.status.notify`

### 3.4.2 回调示例

```json
{
  "appkey": "000001",
  "method": "rsypay.invoice.refund.notify",
  "rpi_no": "RPI001",
  "notice_time": "2026-08-05 15:35:20",
  "order_code": "801012026080515300001",
  "out_trade_no": "T202608050001",
  "out_refund_no": "R202608050001",
  "order_request_code": "801012026080515310001",
  "refund_amount": 95.00,
  "refund_status": "SUCCESS",
  "sign": "Base64格式RSA签名"
}
```