微服务支付架构接口规范文档

微服务支付架构接口规范文档一、接口规范总则（一）适用范围。本规范适用于公司所有微服务支付架构接口的设计、开发、测试及运维，涵盖支付请求、支付通知、退款、对账等核心业务场景。（二）基本原则。接口设计应遵循标准化、安全性、高性能、可扩展原则，确保各服务间交互的稳定性和一致性。（三）版本管理。接口版本采用主版本号.次版本号.修订号格式，主版本号变更代表不兼容性修改，次版本号用于新增功能，修订号用于修复缺陷。（四）命名规范。接口名称采用动词+名词结构，如"QueryPaymentStatus"表示查询支付状态，服务名称需与注册中心规范一致。（五）数据格式。所有接口参数及返回值统一采用JSON格式，日期时间采用ISO8601标准，货币单位统一为分（最小货币单位）。（六）错误处理。所有接口必须返回标准错误码体系，包含错误码、错误描述、建议操作，参考表1错误码定义。二、接口权限控制（一）认证机制。所有接口必须通过JWT（JSONWebToken）进行认证，Token有效期不得超过24小时，需在请求头中携带"Authorization:Bearer{token}"。（二）权限校验。支付中心需实现RBAC（基于角色的访问控制）机制，根据请求者角色及业务类型进行权限校验，拒绝无权限访问。（三）IP白名单。核心支付接口需配置IP白名单机制，仅允许授权网段访问，禁止跨区域直接调用。（四）防刷机制。所有支付接口需实现IP+用户ID+请求频率限制，单用户单分钟请求不得超过20次，连续失败5次自动锁定10分钟。（五）令牌刷新。Token过期后需通过"/api/auth/refresh"接口获取新Token，该接口无需认证但需验证refresh_token有效性。（六）安全审计。所有接口调用需记录调用方IP、时间戳、操作类型、结果状态，日志保留周期不少于90天。三、支付请求接口（一）接口路径。/api/payment/create（二）功能说明。创建支付订单并返回预支付信息，调用第三方支付渠道完成实际支付。（三）请求参数。见表2支付请求参数规范。表2支付请求参数规范|参数名|类型|必填|说明||-----------------|----------|------|--------------------------------------------------------------||order_no|string|是|32位唯一订单号，需保证全局不重复||amount|integer|是|支付金额（分）||currency|string|否|货币类型，默认"CNY"||subject|string|是|订单主题||body|string|否|订单详情||timeout|integer|否|终止时间（秒），默认15分钟||channel|string|否|期望支付渠道，可选"alipay"、"wechat"、"unionpay"等||notify_url|string|是|支付成功回调地址||return_url|string|否|支付跳转地址（同步通知）||user_id|string|是|用户唯一标识||client_ip|string|否|客户端IP地址||ext_params|json|否|扩展参数|（四）返回结构。见表3支付请求返回规范。表3支付请求返回规范|字段名|类型|说明||--------------|----------|--------------------------------------------------------------||code|integer|状态码，0表示成功||message|string|提示信息||data|object|详细数据||data.app_id|string|第三方支付渠道应用ID||data.order_id|string|第三方支付渠道订单号||data.url|string|支付跳转地址||data.qr_code|string|二维码图片Base64编码（可选）|（五）调用示例。POST/api/payment/createHTTP/1.1Authorization:Bearer{token}Content-Type:application/json{"order_no":"20230101001","amount":1000,"subject":"商品购买","notify_url":"/notify","user_id":"user123"}（六）异常处理。当订单已存在、金额为空或第三方渠道不可用时，返回状态码为-1，详细错误信息需包含"order_no"字段。四、支付通知接口（一）接口路径。/api/payment/notify（二）功能说明。接收第三方支付渠道发送的异步通知，验证后更新订单状态。（三）请求参数。见表4支付通知参数规范。表4支付通知参数规范|参数名|类型|必填|说明||---------------|----------|------|--------------------------------------------------------------||sign|string|是|签名，用于验证通知真实性||params|json|是|支付渠道通知参数||timestamp|integer|是|时间戳（毫秒）||app_id|string|是|支付渠道应用ID|（四）验证流程。1.检查签名有效性，使用支付渠道提供的密钥计算签名并与请求签名比对2.验证timestamp是否在5分钟内，防止重放攻击3.检查params中的order_id是否存在于本地订单表4.确认订单状态为未支付，避免重复处理（五）返回结构。见表5支付通知返回规范。表5支付通知返回规范|字段名|类型|说明||----------|----------|--------------------------------------------------------------||code|integer|状态码，0表示成功||message|string|提示信息|（六）调用示例。POST/api/payment/notifyHTTP/1.1Content-Type:application/json{"sign":"abcdef123456","params":{"trade_no":"202301010001","status":"SUCCESS","amount":1000},"timestamp":1670000000000,"app_id":"wx2011123100001"}（七）异常处理。验证失败或订单已处理时，返回状态码为-1；成功处理时需返回状态码0，确保第三方渠道收到正确响应。五、退款接口（一）接口路径。/api/payment/refund（二）功能说明。处理支付订单的退款请求，调用第三方支付渠道完成退款操作。（三）请求参数。见表6退款请求参数规范。表6退款请求参数规范|参数名|类型|必填|说明||---------------|----------|------|--------------------------------------------------------------||order_no|string|是|原支付订单号||refund_no|string|否|退款订单号，为空时自动生成||amount|integer|是|退款金额（分）||refund_reason|string|否|退款原因||user_id|string|是|用户唯一标识||client_ip|string|否|客户端IP地址|（四）返回结构。见表7退款请求返回规范。表7退款请求返回规范|字段名|类型|说明||--------------|----------|--------------------------------------------------------------||code|integer|状态码，0表示成功||message|string|提示信息||data|object|详细数据||data.refund_id|string|第三方退款流水号||data.url|string|退款结果通知地址（可选）|（五）调用示例。POST/api/payment/refundHTTP/1.1Authorization:Bearer{token}Content-Type:application/json{"order_no":"20230101001","amount":500,"user_id":"user123"}（六）异常处理。当订单不存在、退款金额超过原金额时，返回状态码为-1；退款失败时需记录详细日志并尝试重试。六、对账接口（一）接口路径。/api/payment/reconciliation（二）功能说明。定期与第三方支付渠道进行账单对账，确保资金流向一致。（三）触发机制。系统每日凌晨3点自动触发对账任务，也可通过"/api/payment/start_reconciliation"手动启动。（四）对账数据。需包含支付流水号、交易时间、交易金额、交易状态等关键信息，支持分页查询。