From 27a452f8d3c8eed843be092e0e5f7a2bcaee17e8 Mon Sep 17 00:00:00 2001
From: zizi <zizi2000mail@gmail.com>
Date: Wed, 20 May 2026 14:48:48 +0800
Subject: [PATCH] feat: add payment provider contract

Introduce shared payment request, response, order status, and provider interface types.
---
 payment/types.go | 49 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 payment/types.go

diff --git a/payment/types.go b/payment/types.go
new file mode 100644
index 00000000..96ef5816
--- /dev/null
+++ b/payment/types.go
@@ -0,0 +1,49 @@
+package payment
+
+import (
+	"context"
+	"time"
+)
+
+const (
+	OrderStatusPending = "pending"
+	OrderStatusSuccess = "success"
+	OrderStatusFailed  = "failed"
+	OrderStatusClosed  = "closed"
+)
+
+type PaymentRequest struct {
+	OrderID     string
+	Amount      int    // 美元分
+	Currency    string // USD / CNY
+	Description string
+	ReturnURL   string
+	NotifyURL   string
+	ClientIP    string
+	Metadata    map[string]string
+	TradeType   string // NATIVE / H5 / JSAPI (wxpay)
+	OpenID      string // JSAPI 必填 (wxpay)
+}
+
+type PaymentResponse struct {
+	ProviderOrderID string
+	PaymentURL      string // H5/WAP 跳转链接
+	QRCode          string // Native 扫码链接
+	RawResponse     string
+}
+
+type OrderStatus struct {
+	ProviderOrderID string
+	Status          string // pending / success / failed / closed
+	Amount          int
+	Currency        string
+	PaidAt          *time.Time
+}
+
+type Provider interface {
+	Name() string
+	CreatePayment(ctx context.Context, req *PaymentRequest) (*PaymentResponse, error)
+	QueryOrder(ctx context.Context, providerOrderID string) (*OrderStatus, error)
+	VerifyNotification(ctx context.Context, body []byte, headers map[string]string) (*OrderStatus, error)
+	Refund(ctx context.Context, providerOrderID string, amount int) error
+}