{
  "openapi": "3.0.3",
  "info": {
    "title": "IDACHF-3 邮储收款账户保存掩码防护增量",
    "version": "2026-07-21-masked-save",
    "description": "PC 管理端邮储收款账户列表、详情和保存接口。写入 Apifox 项目 5737553 的 PC 端目录 48690332。"
  },
  "tags": [
    {
      "name": "邮储收款账户",
      "description": "账单管理下的邮储支付配置维护接口，与账单记录模块同级。"
    }
  ],
  "paths": {
    "/p/psbcaccount/save": {
      "post": {
        "tags": [
          "邮储收款账户"
        ],
        "x-apifox-folder": "邮储收款账户",
        "summary": "新增或编辑邮储收款账户",
        "description": "仅平台管理员可调用。id 为空时新增，传 id 时编辑。账户状态只允许 3=可用、4=停用；可用必须绑定一所顶级学校，停用不得绑定学校。新增时三个密钥必填；编辑时密钥不传或传空会保留原密文，不能把详情接口返回的带 ******** 脱敏值作为新密钥提交。若学校已有账户，首次返回确认提示，再传 confirm_replace_binding=1 后停用旧账户并完成替换。",
        "operationId": "psbcAccountSave",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PsbcAccountMaskedAwareSaveRequest"
              },
              "examples": {
                "create": {
                  "summary": "新增可用账户",
                  "value": {
                    "name": "荣海小学餐费账户",
                    "status": 3,
                    "settlement_desc": "学生餐费统一结算",
                    "school_uuid": "school-a-uuid",
                    "merchant_no": "100610100002386",
                    "payment_id": "shop-payment-001",
                    "merchant_public_key": "MERCHANT-SM2-PUBLIC-KEY",
                    "merchant_private_key": "MERCHANT-SM2-PRIVATE-KEY",
                    "psbc_public_key": "PSBC-SM2-PUBLIC-KEY",
                    "remark": "开户、联调或使用说明"
                  }
                },
                "editWithoutChangingKeys": {
                  "summary": "编辑基础资料并保留原密钥",
                  "value": {
                    "id": 1,
                    "name": "荣海小学餐费账户",
                    "status": 3,
                    "settlement_desc": "学生餐费统一结算",
                    "school_uuid": "school-a-uuid",
                    "merchant_no": "100610100002386",
                    "payment_id": "shop-payment-001",
                    "remark": "修改说明"
                  }
                },
                "disable": {
                  "summary": "停用账户",
                  "value": {
                    "id": 1,
                    "name": "荣海小学餐费账户",
                    "status": 4,
                    "school_uuid": "",
                    "merchant_no": "100610100002386",
                    "payment_id": "shop-payment-001"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "业务结果，以 code=0 表示成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PsbcAccountMaskedAwareSaveResponse"
                },
                "examples": {
                  "success": {
                    "summary": "保存成功",
                    "value": {
                      "code": 0,
                      "message": "保存成功",
                      "data": {
                        "id": 1,
                        "uuid": "cc819d52-14c3-4bd1-a81b-c08ae3ce1cad",
                        "name": "荣海小学餐费账户",
                        "status": 3,
                        "status_label": "可用",
                        "school_uuid": "school-a-uuid",
                        "school_name": "荣海小学",
                        "merchant_no": "100610100002386",
                        "merchant_no_masked": "********2386",
                        "payment_id": "shop-payment-001",
                        "merchant_public_key_configured": true,
                        "merchant_private_key_configured": true,
                        "psbc_public_key_configured": true,
                        "version_no": 1,
                        "editable": true
                      }
                    }
                  },
                  "schoolConflict": {
                    "summary": "学校已有当前账户，需要二次确认",
                    "value": {
                      "code": 1,
                      "message": "所选学校已有当前收款账户，请确认后再更换",
                      "data": []
                    }
                  },
                  "permissionDenied": {
                    "summary": "非平台管理员",
                    "value": {
                      "code": 1,
                      "message": "仅平台管理员可维护邮储收款账户",
                      "data": []
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PsbcAccountListItem": {
        "type": "object",
        "properties": {
          "id": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ],
            "description": "配置主键；历史只读兼容记录为 legacy_psbc_config"
          },
          "uuid": {
            "type": "string",
            "description": "配置 UUID"
          },
          "name": {
            "type": "string",
            "description": "账户名称"
          },
          "status": {
            "type": "integer",
            "enum": [
              3,
              4
            ],
            "description": "账户状态：3可用，4停用"
          },
          "status_label": {
            "type": "string",
            "enum": [
              "可用",
              "停用"
            ]
          },
          "settlement_desc": {
            "type": "string"
          },
          "school_uuid": {
            "type": "string",
            "description": "绑定学校 UUID；未绑定时为空字符串"
          },
          "school_name": {
            "type": "string",
            "description": "绑定学校名称"
          },
          "school_uuids": {
            "type": "array",
            "deprecated": true,
            "description": "旧前端兼容字段，当前最多一个学校",
            "items": {
              "type": "string"
            }
          },
          "school_names": {
            "type": "array",
            "deprecated": true,
            "description": "旧前端兼容字段，当前最多一个学校",
            "items": {
              "type": "string"
            }
          },
          "merchant_no_masked": {
            "type": "string",
            "description": "脱敏商户号，仅显示最后4位",
            "example": "********2386"
          },
          "version_no": {
            "type": "integer",
            "description": "支付参数版本号"
          },
          "remark": {
            "type": "string"
          },
          "is_legacy": {
            "type": "boolean",
            "description": "是否为缺表场景下的历史只读兼容记录"
          },
          "editable": {
            "type": "boolean",
            "description": "当前记录是否允许编辑"
          },
          "create_time": {
            "type": "string",
            "description": "创建时间"
          },
          "update_time": {
            "type": "string",
            "description": "最近更新时间"
          }
        }
      },
      "PsbcAccountMaskedDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PsbcAccountListItem"
          },
          {
            "type": "object",
            "properties": {
              "merchant_no": {
                "type": "string",
                "description": "完整 B2C 商户号"
              },
              "payment_id": {
                "type": "string",
                "description": "统一收单门店号或支付标识"
              },
              "merchant_public_key": {
                "type": "string",
                "readOnly": true,
                "description": "商户 SM2 公钥脱敏值，仅平台管理员详情返回；格式为开头 8 位 + ******** + 结尾 8 位"
              },
              "merchant_private_key": {
                "type": "string",
                "format": "password",
                "readOnly": true,
                "description": "商户 SM2 私钥脱敏值，仅平台管理员详情返回；格式为开头 8 位 + ******** + 结尾 8 位"
              },
              "psbc_public_key": {
                "type": "string",
                "readOnly": true,
                "description": "邮储支付 SM2 公钥脱敏值，仅平台管理员详情返回；格式为开头 8 位 + ******** + 结尾 8 位"
              },
              "merchant_public_key_configured": {
                "type": "boolean"
              },
              "merchant_private_key_configured": {
                "type": "boolean"
              },
              "psbc_public_key_configured": {
                "type": "boolean"
              },
              "config_complete": {
                "type": "boolean",
                "description": "支付参数是否完整"
              }
            }
          }
        ]
      },
      "PsbcAccountMaskedAwareSaveRequest": {
        "type": "object",
        "required": [
          "name",
          "status",
          "merchant_no",
          "payment_id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1,
            "description": "编辑时传配置主键；新增时不传"
          },
          "name": {
            "type": "string",
            "maxLength": 100,
            "description": "账户名称，同一商城内不能重复",
            "example": "荣海小学餐费账户"
          },
          "status": {
            "type": "integer",
            "enum": [
              3,
              4
            ],
            "default": 3,
            "description": "账户状态：3可用，4停用"
          },
          "settlement_desc": {
            "type": "string",
            "maxLength": 500,
            "description": "结算说明"
          },
          "school_uuid": {
            "type": "string",
            "description": "顶级学校 UUID。状态为3时必填，状态为4时必须为空",
            "example": "school-a-uuid"
          },
          "merchant_no": {
            "type": "string",
            "maxLength": 128,
            "description": "B2C 商户号",
            "example": "100610100002386"
          },
          "payment_id": {
            "type": "string",
            "maxLength": 128,
            "description": "统一收单门店号或支付标识",
            "example": "shop-payment-001"
          },
          "merchant_public_key": {
            "type": "string",
            "writeOnly": true,
            "description": "商户 SM2 公钥完整值。新增必填；编辑时不传或传空表示保持原值，不接受带 ******** 的详情脱敏值"
          },
          "merchant_private_key": {
            "type": "string",
            "writeOnly": true,
            "format": "password",
            "description": "商户 SM2 私钥完整值。新增必填；编辑时不传或传空表示保持原值，不接受带 ******** 的详情脱敏值"
          },
          "psbc_public_key": {
            "type": "string",
            "writeOnly": true,
            "description": "邮储支付 SM2 公钥完整值。新增必填；编辑时不传或传空表示保持原值，不接受带 ******** 的详情脱敏值"
          },
          "remark": {
            "type": "string",
            "maxLength": 500,
            "description": "备注"
          },
          "confirm_replace_binding": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "default": 0,
            "description": "学校已有账户时，二次确认传1；保存成功后旧账户会被停用并解除学校绑定"
          }
        }
      },
      "PsbcAccountMaskedAwareSaveResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "0成功，1失败"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PsbcAccountMaskedDetail"
              },
              {
                "type": "array",
                "maxItems": 0,
                "description": "失败时返回空数组"
              }
            ]
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      }
    }
  }
}