PaymentService

支付管理服务，负责支付创建、状态查询、网关回调处理和退款操作。支持对接多种 PaymentGateway 插件（如易支付、银行转账）。

RPC 列表

RPC	描述	权限
CreatePayment	创建支付记录（生成支付链接）	已认证
ListPayments	支付列表（分页+筛选）	admin 全量 / customer 自身
GetPayment	获取支付详情	admin 全量 / customer 自身
QueryPaymentStatus	向网关查询支付状态	admin
HandleCallback	接收支付网关异步回调	公开（网关调用）
RefundPayment	发起退款	admin

CreatePayment

描述

为订单或发票创建支付记录。调用 PaymentGateway 插件生成支付 URL 或二维码。

Request — `CreatePaymentRequest`

字段	类型	编号	必填	描述
order_id	string	1	是	订单 ID（UUID）
invoice_id	string	2	是	发票 ID（UUID）
gateway_interface_id	string	3	是	支付网关接口 ID（UUID）
return_url	string	4	是	支付完成后跳转 URL

Response — `CreatePaymentResponse`

字段	类型	编号	描述
payment	PaymentRecord	1	支付记录
payment_url	string	2	支付页面 URL
qr_code	string	3	二维码内容（Base64 或 URL）
instructions	string	4	支付说明

错误码

错误	说明
InvalidArgument	订单/发票不存在或已支付
Internal	网关插件执行失败
Unauthenticated	未登录

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"order_id":"0192a123-...","invoice_id":"","gateway_interface_id":"0192d012-...","return_url":"https://example.com/payment/result"}' \
  localhost:50051 rustbill.payment.PaymentService/CreatePayment

const resp = await api.createPayment({
  order_id: "0192a123-...",
  invoice_id: "",
  gateway_interface_id: "0192d012-...",
  return_url: "https://example.com/payment/result"
});
// 跳转到 resp.payment_url

ListPayments

描述

分页查询支付记录列表。Admin 可查看所有支付，Customer 自动限定为自身支付。

Request — `ListPaymentsRequest`

字段	类型	编号	必填	描述
pagination	PageRequest	1	是	分页参数
order_id	string?	2	否	按订单过滤
invoice_id	string?	3	否	按发票过滤
gateway_interface_id	string?	4	否	按网关接口过滤
status	string?	5	否	按状态过滤

Response — `ListPaymentsResponse`

字段	类型	编号	描述
payments	repeated PaymentRecord	1	支付列表
meta	PageMeta	2	分页元数据

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"pagination":{"page":1,"page_size":20},"status":"success"}' \
  localhost:50051 rustbill.payment.PaymentService/ListPayments

GetPayment

描述

获取单条支付记录详情。

Request — `GetPaymentRequest`

字段	类型	编号	必填	描述
id	string	1	是	支付记录 ID（UUID）

Response — `GetPaymentResponse`

字段	类型	编号	描述
payment	PaymentRecord	1	支付记录

错误码

错误	说明
NotFound	支付记录不存在
PermissionDenied	customer 用户无权查看他人支付

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"id":"0192a123-4567-7890-abcd-ef0123456789"}' \
  localhost:50051 rustbill.payment.PaymentService/GetPayment

QueryPaymentStatus

描述

主动向支付网关查询支付状态并同步本地记录。

Request — `QueryPaymentStatusRequest`

字段	类型	编号	必填	描述
payment_id	string	1	是	支付记录 ID（UUID）

Response — `QueryPaymentStatusResponse`

字段	类型	编号	描述
payment	PaymentRecord	1	更新后的支付记录

错误码

错误	说明
NotFound	支付记录不存在
Internal	网关查询失败
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"payment_id":"0192a123-..."}' \
  localhost:50051 rustbill.payment.PaymentService/QueryPaymentStatus

HandleCallback

描述

接收支付网关的异步回调通知。使用乐观锁（expected_status）确保回调幂等，防止重复处理。

注意：此 RPC 由支付网关调用，不由前端直接调用。

Request — `PaymentCallbackRequest`

字段	类型	编号	必填	描述
gateway_interface_id	string	1	是	网关接口 ID（UUID）
payload	string	2	是	网关回调原始 payload（由网关插件自行解析）

Response — `PaymentCallbackResponse`

字段	类型	编号	描述
payment	PaymentRecord	1	更新后的支付记录

错误码

错误	说明
InvalidArgument	签名验证失败、订单号不匹配
NotFound	支付记录不存在
AlreadyExists	重复回调（乐观锁拦截）

回调流程

支付网关 → POST /rustbill.payment.PaymentService/HandleCallback
  → gateway 插件验证签名
  → 更新 payment.status = "success"
  → 更新 order.status = "paid"
  → INSERT event_queue(order_paid)  ← event_worker 异步处理开通

RefundPayment

描述

对已支付订单发起退款。amount 为空时全额退款。

Request — `RefundPaymentRequest`

字段	类型	编号	必填	描述
payment_id	string	1	是	支付记录 ID（UUID）
amount	string	2	是	退款金额（空字符串=全额退款）

Response — `RefundPaymentResponse`

字段	类型	编号	描述
payment	PaymentRecord	1	更新后的支付记录

错误码

错误	说明
NotFound	支付记录不存在
InvalidArgument	退款金额超过支付金额、支付状态不允许退款
Internal	网关退款执行失败
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"payment_id":"0192a123-...","amount":""}' \
  localhost:50051 rustbill.payment.PaymentService/RefundPayment

公共类型

PaymentRecord

字段	类型	编号	描述
id	string	1	支付记录 UUID
order_id	string	2	关联订单 ID
invoice_id	string	3	关联发票 ID
amount	string	4	支付金额（字符串）
currency	string	5	货币代码
gateway_interface_id	string	6	支付网关接口 ID
gateway_payment_id	string	7	网关内支付 ID（回调后填充）
gateway_tx_id	string	8	网关交易流水号
status	string	9	支付状态
paid_at	string	10	支付时间（RFC3339）
created_at	string	11	创建时间（RFC3339）
updated_at	string	12	更新时间（RFC3339）

支付状态流转

pending → success / failed / refunded

状态	说明
pending	待支付
success	支付成功
failed	支付失败
refunded	已退款

Keyboard shortcuts

RustBill 文档