sioyun

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 19, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

sioyun-sdk

西奥开放网关 Go SDK，提供短信、支付、进件、应用查询等能力，支持 AK/SK 签名认证、WebSocket 实时推送及回调验签。

安装

go get github.com/zhoudm1743/sioyun-sdk@latest

依赖：仅 gorilla/websocket（WebSocket 客户端），核心 HTTP 客户端零外部依赖。

最低 Go 版本：1.22

快速开始

package main

import (
    "context"
    "fmt"
    sioyun "github.com/zhoudm1743/sioyun-sdk"
)

func main() {
    // 1. 创建客户端（自动验证连通性）
    client, err := sioyun.New(sioyun.Config{
        BaseURL:   "https://api.sioyun.com/api/gateway/v1",
        AccessKey: "ak_xxxxxxxxxxxxxxxxxxxxxxxx",
        SecretKey: "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        Timeout:   30,
    })
    if err != nil {
        panic(fmt.Sprintf("SDK 初始化失败: %v", err))
    }

    ctx := context.Background()

    // 2. 发送验证码
    result, err := client.SMS().Send(ctx, sioyun.SmsSendReq{
        Phone:        "13800138000",
        TemplateCode: "verify_code",
        Params:       map[string]string{"code": "123456"},
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("发送成功, send_id=%s, 消费 %d 条\n", result.SendID, result.Fee)

    // 3. 创建支付订单
    order, err := client.Pay().Create(ctx, sioyun.OrderCreateReq{
        OutTradeNo:  "ORDER20260612001",
        Amount:      100,
        PayMethod:   "wechat_jsapi",
        Description: "测试商品",
        NotifyURL:   "https://partner.example.com/callback",
        OpenID:      "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
    })
    if err != nil {
        panic(err)
    }
    jsapi, err := order.WechatJsapiPayInfo()
    if err != nil {
        panic(err)
    }
    fmt.Printf("下单成功, prepay_id=%s\n", jsapi.Package)
}
签名算法
签名字符串 = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(BODY)
HMAC key   = SHA256(SecretKey)
签名       = Hex(HMAC-SHA256(签名字符串, HMAC_key))

客户端自动处理签名，调用方无需关心。密钥仅在平台上创建时返回一次明文，请妥善保管。

API 概览

客户端配置
client, err := sioyun.New(sioyun.Config{
    BaseURL:        "https://api.sioyun.com/api/gateway/v1",
    AccessKey:      "ak_xxx",
    SecretKey:      "sk_xxx",
    Timeout:        30,       // 秒，默认 30
    CallbackSecret: "sk_xxx", // 回调验签密钥，默认等于 SecretKey
})
服务 获取方式 提供能力
短信 client.SMS() 发送短信、查询余额
支付 client.Pay() 下单、查询、关闭、退款、退款查询
进件 client.Partner() 提交进件、查询状态
应用 client.App() 查询订阅列表、账户信息
短信服务 (client.SMS())

发送短信

resp, err := client.SMS().Send(ctx, sioyun.SmsSendReq{
    Phone:        "13800138000",
    TemplateCode: "verify_code",
    Params:       map[string]string{"code": "123456"},
})
// resp.SendID  - 发送流水号
// resp.Fee     - 本次消费条数
// resp.BalanceRemaining - 剩余可用条数

查询余额

resp, err := client.SMS().Balance(ctx)
// resp.TotalRemaining - 总剩余条数
// resp.Packages       - 有效套餐明细
支付服务 (client.Pay())

下单

resp, err := client.Pay().Create(ctx, sioyun.OrderCreateReq{
    OutTradeNo:  "ORDER001",
    Amount:      100,          // 金额（分）
    PayMethod:   "wechat_jsapi",
    Description: "商品描述",
    NotifyURL:   "https://example.com/callback",
    OpenID:      "oUpF8uMu...", // JSAPI 必填
})
// resp.GatewayTradeNo - 网关流水号
// resp.PayInfo        - 调起支付所需参数（wechat_jsapi 可用 resp.WechatJsapiPayInfo() 解析）

支持的支付方式：wechat_jsapi | wechat_h5 | wechat_native | wechat_app | alipay_qr | alipay_h5 | alipay_app

查询订单

resp, err := client.Pay().Query(ctx, sioyun.OrderQueryReq{
    OutTradeNo: "ORDER001", // GET /pay/query/:out_trade_no
})
// resp.Status - PENDING / SUCCESS / CLOSED

关闭订单

resp, err := client.Pay().Close(ctx, sioyun.OrderCloseReq{
    OutTradeNo: "ORDER001",
})

退款

resp, err := client.Pay().Refund(ctx, sioyun.RefundCreateReq{
    OutTradeNo:   "ORDER001",
    OutRefundNo:  "REFUND001",
    RefundAmount: 50,
})
// resp.Status - PROCESSING

查询退款

resp, err := client.Pay().RefundQuery(ctx, sioyun.RefundQueryReq{
    OutRefundNo: "REFUND001",
})
// resp.Status - PROCESSING / SUCCESS / FAIL
进件服务 (client.Partner())

提交进件

resp, err := client.Partner().Submit(ctx, sioyun.ApplymentSubmitReq{
    Channel:      "wechat",
    MerchantName: "测试商户",
    SubjectType:  "ENTERPRISE",
    FormData: map[string]interface{}{
        "contact_info":      map[string]interface{}{"contact_name": "张三", ...},
        "subject_info":      map[string]interface{}{...},
        "business_info":     map[string]interface{}{...},
        "settlement_info":   map[string]interface{}{...},
        "bank_account_info": map[string]interface{}{...},
    },
})
// resp.ApplyID  - 申请单 ID
// resp.Status   - submitted / signing / rejected / finished

查询进件状态

resp, err := client.Partner().Query(ctx, "apply_xxx")
// resp.Status       - draft / submitted / signing / rejected / finished / canceled
// resp.SubMchID     - 微信子商户号（进件完成后返回）
// resp.AuditDetail  - 审核驳回详情
应用服务 (client.App())

查询已订阅应用

subs, err := client.App().Subscriptions(ctx)
// []sioyun.SubscriptionInfo

查询账户信息

resp, err := client.App().Profile(ctx)
// resp.WalletBalance - 钱包余额
// resp.SMSRemaining  - 短信剩余额度
// resp.WechatMerchants / resp.AlipayMerchants - 进件商户列表

错误处理

所有 API 方法在 HTTP 状态非 200 或响应 code != 0 时返回 *sioyun.APIError。

resp, err := client.SMS().Send(ctx, req)
if err != nil {
    if sioyun.IsInsufficientFunds(err) {
        // code=402，短信额度不足
    }
    if sioyun.IsRateLimited(err) {
        // code=429，频率超限
    }
    if apiErr, ok := err.(*sioyun.APIError); ok {
        fmt.Printf("code=%d, msg=%s\n", apiErr.Code, apiErr.Msg)
    }
}
错误码常量 值 含义
ErrCodeBadRequest 400 参数错误
ErrCodeUnauthorized 401 签名验证失败 / AK 无效
ErrCodeInsufficientFunds 402 短信额度不足
ErrCodeForbidden 403 账户被禁用
ErrCodeNotFound 404 资源不存在
ErrCodeRateLimited 429 频率限制
ErrCodeInternalError 500 服务器内部错误

WebSocket 实时推送

ws := sioyun.NewWSClient(sioyun.Config{
    BaseURL:   "https://api.sioyun.com/api/gateway/v1",
    AccessKey: os.Getenv("SIOYUN_AK"),
    SecretKey: os.Getenv("SIOYUN_SK"),
})

// 注册事件处理器（支持通配符）
ws.On("payment.success", func(event sioyun.GatewayEvent) {
    fmt.Printf("支付成功: %+v\n", event.Data)
})
ws.On("payment.*", func(event sioyun.GatewayEvent) {
    fmt.Printf("支付事件: %s\n", event.Event)
})

// 建立连接
ws.Connect(context.Background())

// 订阅频道
ws.Subscribe("payment.*")
ws.Subscribe("sms.delivered")

// 断开连接
defer ws.Close()

特性：自动断线重连（指数退避 1s→2s→4s→8s→...→60s）、30 秒心跳保活。

回调验签

网关支付/进件/短信等异步结果通过 HTTP 回调通知合作伙伴，SDK 提供验签工具：

方式一：便捷 Handler
http.HandleFunc("/callback/payment", sioyun.CallbackHandler(sioyun.Config{
    SecretKey: "sk_xxx",
}, func(payload *sioyun.CallbackPayload) error {
    fmt.Printf("收到回调: event=%s, data=%+v\n", payload.Event, payload.Data)
    // 更新本地订单状态...
    return nil
}))
方式二：手动验签
func handleCallback(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)

    payload, _ := sioyun.VerifyAndParseCallback(body, secretKey, "")
    if err := sioyun.VerifySignature(secretKey, payload, r.Header.Get("X-Gateway-Signature")); err != nil {
        http.Error(w, "验签失败", http.StatusForbidden)
        return
    }
    // 处理业务...
    w.Write([]byte("success"))
}

设计原则

  • 零外部依赖（除 gorilla/websocket 用于 WS 客户端）
  • 单实例复用，线程安全
  • 类型安全的请求/响应体
  • 自动签名，调用方无需关心签名逻辑
  • 初始化时连通性验证

相关文档

License

Apache-2.0

Documentation

Overview

Package id 提供时序 ID 生成器（移植自 backend/framework/id）。

规格：

  • 长度：16 字符（固定）
  • 字符集：Crockford Base32 小写（去掉 i l o u，避免视觉混淆）
  • 结构：[10 chars | 50-bit 毫秒时间戳] [6 chars | 30-bit 单调序列]
  • 字典序 ≡ 时间序：可直接在数据库 ORDER BY id ASC/DESC 按创建时间排序
  • 并发安全：全局 Mutex 保护，同一毫秒内序列单调递增
  • 时钟回拨安全：lastMs 只增不减，NTP 调整后 ID 仍单调递增

Index

Examples

Constants

View Source 
const (
	ErrCodeSuccess           = 0
	ErrCodeBadRequest        = 400
	ErrCodeUnauthorized      = 401
	ErrCodeInsufficientFunds = 402
	ErrCodeForbidden         = 403
	ErrCodeNotFound          = 404
	ErrCodeRateLimited       = 429
	ErrCodeInternalError     = 500
)

预定义错误码。

Variables

This section is empty.

Functions

func CallbackHandler 

func CallbackHandler(cfg Config, onEvent func(*CallbackPayload) error) http.HandlerFunc

CallbackHandler 是合作伙伴实现回调接口的参考实现。

使用方式： 

http.HandleFunc("/callback/payment", sioyun.CallbackHandler(sioyun.Config{
    SecretKey: "sk_xxx",
}, func(payload *sioyun.CallbackPayload) error {
    fmt.Printf("收到支付回调: %+v\n", payload)
    // 更新本地订单状态...
    return nil
}))

func IsInsufficientFunds 

func IsInsufficientFunds(err error) bool

IsInsufficientFunds 判断是否短信额度不足。

func IsRateLimited 

func IsRateLimited(err error) bool

IsRateLimited 判断是否频率超限。

func VerifySignature 

func VerifySignature(secretKey string, payload *CallbackPayload, signature string) error

VerifySignature 验签（配合 VerifyAndParseCallback 使用）。 签名规则：HMAC-SHA256，HMAC key = SHA256(secretKey)。 签名字符串 = event + "\n" + gateway_trade_no + "\n" + event_time + "\n" + SHA256(JSON(data))

Types

type APIError 

type APIError struct {
	HTTPStatus int    `json:"-"`
	Code       int    `json:"code"`
	Msg        string `json:"msg"`
}

APIError 网关返回的业务错误。

func (*APIError) Error 

func (e *APIError) Error() string

type APIResponse 

type APIResponse struct {
	Code int         `json:"code"`
	Msg  string      `json:"msg"`
	Data interface{} `json:"data"`
}

APIResponse 网关统一响应。

type AppService 

type AppService struct {
	// contains filtered or unexported fields
}

AppService 应用服务（查询已订阅应用与账户信息）。

func (*AppService) Profile 

func (a *AppService) Profile(ctx context.Context) (*ProfileResp, error)

Profile 查询当前账户信息。

func (*AppService) Subscriptions 

func (a *AppService) Subscriptions(ctx context.Context) ([]SubscriptionInfo, error)

Subscriptions 查询已订阅应用。

type ApplymentQueryResp 

type ApplymentQueryResp struct {
	ApplyID           string        `json:"apply_id"`
	ApplymentID       int64         `json:"applyment_id"`
	Channel           string        `json:"channel"`
	Status            string        `json:"status"` // draft/submitted/signing/rejected/finished/canceled
	ApplymentState    string        `json:"applyment_state"`
	ApplymentStateMsg string        `json:"applyment_state_msg"`
	SubMchID          string        `json:"sub_mchid"` // 微信子商户号
	SMID              string        `json:"smid"`      // 支付宝 smid
	SignURL           string        `json:"sign_url"`
	AuditDetail       []AuditDetail `json:"audit_detail"`
	SubmittedAt       int64         `json:"submitted_at"`
	FinishedAt        int64         `json:"finished_at"`
}

ApplymentQueryResp 进件查询响应。

type ApplymentSubmitReq 

type ApplymentSubmitReq struct {
	Channel      string                 `json:"channel"`       // wechat | alipay
	MerchantName string                 `json:"merchant_name"` // 商户简称
	SubjectType  string                 `json:"subject_type"`  // 主体类型（微信: ENTERPRISE/INDIVIDUAL/...）
	NotifyURL    string                 `json:"notify_url,omitempty"`
	FormData     map[string]interface{} `json:"form_data"` // 进件表单（结构按 channel 不同）
}

ApplymentSubmitReq 进件提交请求。

type ApplymentSubmitResp 

type ApplymentSubmitResp struct {
	ApplyID     string `json:"apply_id"`
	ApplymentID int64  `json:"applyment_id"`
	Channel     string `json:"channel"`
	Status      string `json:"status"` // submitted / signing / rejected / finished
	SignURL     string `json:"sign_url"`
	SubmittedAt int64  `json:"submitted_at"`
}

ApplymentSubmitResp 进件提交响应。

type AuditDetail 

type AuditDetail struct {
	Field        string `json:"field"`
	FieldName    string `json:"field_name"`
	RejectReason string `json:"reject_reason"`
}

AuditDetail 审核驳回详情。

type CallbackPayload 

type CallbackPayload struct {
	Event          string      `json:"event"`
	GatewayTradeNo string      `json:"gateway_trade_no"`
	OutTradeNo     string      `json:"out_trade_no"`
	EventTime      int64       `json:"event_time"`
	Data           interface{} `json:"data"`
}

CallbackPayload 网关回调通知的请求体。

func VerifyAndParseCallback 

func VerifyAndParseCallback(body []byte, secretKey string, expectedEvent string) (*CallbackPayload, error)

VerifyAndParseCallback 验证回调签名并解析回调数据。 用法：在合作伙伴的 HTTP handler 中调用，传入请求体和本地 SecretKey。

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client 网关客户端。 通过 New() 创建，内部维护连接池，线程安全。

func New 

func New(cfg Config) (*Client, error)

New 创建网关客户端，初始化时发送测试请求验证连通性。

func (*Client) App 

func (c *Client) App() *AppService

App 返回应用服务。

func (*Client) Config 

func (c *Client) Config() Config

Config 返回当前配置（只读副本）。

func (*Client) Partner 

func (c *Client) Partner() *PartnerService

Partner 返回进件服务。

func (*Client) Pay 

func (c *Client) Pay() *PaymentService

Pay 返回支付服务。

func (*Client) SMS 

func (c *Client) SMS() *SmsService

SMS 返回短信服务。

type Config 

type Config struct {
	// BaseURL 网关根地址，如 https://api.sioyun.com/api/gateway/v1
	BaseURL string
	// AccessKey 访问标识符（ak_ 前缀）
	AccessKey string
	// SecretKey 签名密钥（sk_ 前缀）
	SecretKey string
	// Timeout HTTP 超时（秒），默认 30
	Timeout int
	// CallbackSecret 回调验签所用的 SecretKey（用于 HandleCallback）
	// 默认等于 SecretKey，如果业务方有独立的回调密钥可单独设置
	CallbackSecret string
	// Transport 自定义 HTTP Transport（nil 则用禁用代理的默认 Transport）
	Transport http.RoundTripper
	// SkipConnectivityCheck 跳过 New() 时的连通性探测
	SkipConnectivityCheck bool
}

Config SDK 配置。

type EventHandler 

type EventHandler func(event GatewayEvent)

EventHandler 事件处理回调。

type GatewayEvent 

type GatewayEvent struct {
	Type    string      `json:"type"`
	Event   string      `json:"event,omitempty"`
	Data    interface{} `json:"data,omitempty"`
	Channel string      `json:"channel,omitempty"`
	Code    int         `json:"code,omitempty"`
	Msg     string      `json:"msg,omitempty"`
}

GatewayEvent 网关推送的事件。

type MerchantBrief 

type MerchantBrief struct {
	SubMchID     string `json:"sub_mchid"`
	SMID         string `json:"smid"`
	MerchantName string `json:"merchant_name"`
	Status       string `json:"status"`
}

MerchantBrief 商户简要信息。

type MicroPayInfo added in v1.1.0 

type MicroPayInfo struct {
	TradeState    string `json:"trade_state"`     // SUCCESS：同步扣款成功
	TransactionID string `json:"transaction_id"`  // 微信渠道交易流水号
	TradeNo       string `json:"trade_no"`        // 支付宝渠道交易流水号
	TargetOrderID string `json:"target_order_id"` // 银联渠道交易流水号
	SeqID         string `json:"seq_id"`          // 银联平台流水号
	PayAmount     int64  `json:"pay_amount"`      // 实付金额（分）
	PayTime       int64  `json:"pay_time"`        // 支付完成时间（Unix 秒）
}

MicroPayInfo 付款码支付（B扫C）同步扣款结果。 网关下单接口返回的 pay_info 即同步扣款结果，各渠道字段略有差异，均映射到此结构。

type OrderCloseReq 

type OrderCloseReq struct {
	OutTradeNo string `json:"out_trade_no"`
}

OrderCloseReq 关闭订单请求。

type OrderCloseResp 

type OrderCloseResp struct {
	OutTradeNo string `json:"out_trade_no"`
	Status     string `json:"status"`
}

OrderCloseResp 关闭订单响应。

type OrderCreateReq 

type OrderCreateReq struct {
	OutTradeNo    string                `json:"out_trade_no"`             // 必填：商户订单号（唯一）
	Amount        int64                 `json:"amount"`                   // 必填：金额（分）
	PayMethod     string                `json:"pay_method"`               // 必填：wechat_jsapi / wechat_h5 / wechat_native / wechat_app / wechat_micropay / alipay_qr / alipay_h5 / alipay_app / alipay_micropay / unionpay_qr / unionpay_mini / unionpay_jsapi / unionpay_micropay
	Description   string                `json:"description"`              // 必填：商品描述
	NotifyURL     string                `json:"notify_url"`               // 必填：支付结果回调地址
	OpenID        string                `json:"openid,omitempty"`         // 条件：微信 jsapi 支付必填
	SubMchID      string                `json:"sub_mchid,omitempty"`      // 指定子商户号
	Attach        string                `json:"attach,omitempty"`         // 附加数据（回调原样返回）
	ExpireMinutes int                   `json:"expire_minutes,omitempty"` // 过期分钟数
	ClientIP      string                `json:"client_ip,omitempty"`      // 条件：wechat_h5 建议传入
	ReturnURL     string                `json:"return_url,omitempty"`     // 可选：alipay_h5 支付完成跳转
	AuthCode      string                `json:"auth_code,omitempty"`      // 条件：B扫C（付款码支付）必填，用户付款码/被扫条码
	AutoSplit     bool                  `json:"auto_split,omitempty"`     // 可选：支付成功后自动分账（微信/支付宝按预配置接收方分账；银联在下单时直接分账）
	SubOrders     []ProfitShareSubOrder `json:"sub_orders,omitempty"`     // 可选：银联下单分账子商户列表（仅 unionpay_mini/unionpay_jsapi 分账使用）
}

OrderCreateReq 支付下单请求。

type OrderCreateResp 

type OrderCreateResp struct {
	OutTradeNo     string                 `json:"out_trade_no"`
	GatewayTradeNo string                 `json:"gateway_trade_no"`
	PayMethod      string                 `json:"pay_method"`
	Amount         int64                  `json:"amount"`
	PayInfo        map[string]interface{} `json:"pay_info"`
}

OrderCreateResp 支付下单响应。

func (*OrderCreateResp) AlipayAppPayInfo added in v1.0.3 

func (r *OrderCreateResp) AlipayAppPayInfo() (string, error)

AlipayAppPayInfo 解析 alipay_app 下单响应中的 pay_info。

func (*OrderCreateResp) AlipayH5PayInfo added in v1.0.3 

func (r *OrderCreateResp) AlipayH5PayInfo() (string, error)

AlipayH5PayInfo 解析 alipay_h5 下单响应中的 pay_info。

func (*OrderCreateResp) AlipayQrPayInfo added in v1.0.3 

func (r *OrderCreateResp) AlipayQrPayInfo() (string, error)

AlipayQrPayInfo 解析 alipay_qr 下单响应中的 pay_info。

func (*OrderCreateResp) MicroPayInfo added in v1.1.0 

func (r *OrderCreateResp) MicroPayInfo() (*MicroPayInfo, error)

MicroPayInfo 解析 wechat_micropay / alipay_micropay / unionpay_micropay 下单响应中的 pay_info。

func (*OrderCreateResp) UnionPayMiniPayInfo added in v1.0.4 

func (r *OrderCreateResp) UnionPayMiniPayInfo() (*UnionPayMiniPayInfo, error)

UnionPayMiniPayInfo 解析 unionpay_mini / unionpay_jsapi 下单响应中的 pay_info。

func (*OrderCreateResp) UnionPayQrPayInfo added in v1.0.4 

func (r *OrderCreateResp) UnionPayQrPayInfo() (string, error)

UnionPayQrPayInfo 解析 unionpay_qr 下单响应中的 pay_info (C扫B 二维码)。

func (*OrderCreateResp) WechatAppPayInfo added in v1.0.3 

func (r *OrderCreateResp) WechatAppPayInfo() (*WechatAppPayInfo, error)

WechatAppPayInfo 解析 wechat_app 下单响应中的 pay_info。

func (*OrderCreateResp) WechatH5PayInfo added in v1.0.3 

func (r *OrderCreateResp) WechatH5PayInfo() (string, error)

WechatH5PayInfo 解析 wechat_h5 下单响应中的 pay_info。

func (*OrderCreateResp) WechatJsapiPayInfo added in v1.0.3 

func (r *OrderCreateResp) WechatJsapiPayInfo() (*WechatJsapiPayInfo, error)

WechatJsapiPayInfo 解析 wechat_jsapi 下单响应中的 pay_info。

func (*OrderCreateResp) WechatNativePayInfo added in v1.0.3 

func (r *OrderCreateResp) WechatNativePayInfo() (string, error)

WechatNativePayInfo 解析 wechat_native 下单响应中的 pay_info。

type OrderQueryReq 

type OrderQueryReq struct {
	OutTradeNo     string `json:"out_trade_no,omitempty"`
	GatewayTradeNo string `json:"gateway_trade_no,omitempty"`
}

OrderQueryReq 订单查询请求。

type OrderQueryResp 

type OrderQueryResp struct {
	OutTradeNo     string `json:"out_trade_no"`
	GatewayTradeNo string `json:"gateway_trade_no"`
	Status         string `json:"status"` // PENDING / SUCCESS / CLOSED / REFUND / REFUND_PART
	PayMethod      string `json:"pay_method"`
	Amount         int64  `json:"amount"`
	PayAmount      int64  `json:"pay_amount"`
	TransactionID  string `json:"transaction_id"`
	PayTime        int64  `json:"pay_time"`
	Attach         string `json:"attach"`
}

OrderQueryResp 订单查询响应。

type PartnerService 

type PartnerService struct {
	// contains filtered or unexported fields
}

PartnerService 进件服务（微信/支付宝特约商户入驻）。

func (*PartnerService) Query 

func (p *PartnerService) Query(ctx context.Context, applyID string) (*ApplymentQueryResp, error)

Query 查询进件状态。

func (*PartnerService) Submit 

func (p *PartnerService) Submit(ctx context.Context, req ApplymentSubmitReq) (*ApplymentSubmitResp, error)

Submit 提交进件申请。

type PaymentService 

type PaymentService struct {
	// contains filtered or unexported fields
}

PaymentService 支付服务。

func (*PaymentService) Close 

func (p *PaymentService) Close(ctx context.Context, req OrderCloseReq) (*OrderCloseResp, error)

Close 关闭未支付的订单。

func (*PaymentService) Create 

func (p *PaymentService) Create(ctx context.Context, req OrderCreateReq) (*OrderCreateResp, error)

Create 创建支付订单。

func (*PaymentService) Query 

func (p *PaymentService) Query(ctx context.Context, req OrderQueryReq) (*OrderQueryResp, error)

Query 查询订单状态（GET /pay/query/:out_trade_no）。

func (*PaymentService) Refund 

func (p *PaymentService) Refund(ctx context.Context, req RefundCreateReq) (*RefundCreateResp, error)

Refund 申请退款。

func (*PaymentService) RefundQuery 

func (p *PaymentService) RefundQuery(ctx context.Context, req RefundQueryReq) (*RefundQueryResp, error)

RefundQuery 查询退款状态。

func (*PaymentService) Split added in v1.1.0 

func (p *PaymentService) Split(ctx context.Context, req SplitCreateReq) (*SplitCreateResp, error)

Split 发起分账。 分账明细按「预配置接收方 × 默认比例」自动计算，比例可在平台管理后台调整。

func (*PaymentService) SplitQuery added in v1.1.0 

func (p *PaymentService) SplitQuery(ctx context.Context, outProfitShareNo string) (*SplitQueryResp, error)

SplitQuery 查询分账结果（GET /pay/split/query/:out_profit_share_no）。

func (*PaymentService) SplitReturn added in v1.1.0 

func (p *PaymentService) SplitReturn(ctx context.Context, req SplitReturnReq) (*SplitReturnResp, error)

SplitReturn 分账回退（仅微信，仅已完成的分账可回退）。

func (*PaymentService) SplitUnsplitAmount added in v1.1.0 

func (p *PaymentService) SplitUnsplitAmount(ctx context.Context, outTradeNo string) (*SplitUnsplitAmountResp, error)

SplitUnsplitAmount 查询订单剩余待分金额（GET /pay/split/unsplit_amount/:out_trade_no，仅微信）。

type ProfileResp 

type ProfileResp struct {
	UserID          string          `json:"user_id"`
	Username        string          `json:"username"`
	Nickname        string          `json:"nickname"`
	Email           string          `json:"email"`
	WalletBalance   int64           `json:"wallet_balance"`
	SMSRemaining    int64           `json:"sms_remaining"`
	WechatMerchants []MerchantBrief `json:"wechat_merchants"`
	AlipayMerchants []MerchantBrief `json:"alipay_merchants"`
}

ProfileResp 账户信息响应。

type ProfitShareReceiver added in v1.1.0 

type ProfitShareReceiver struct {
	ReceiverType string `json:"receiver_type"` // 接收方类型
	Account      string `json:"account"`       // 接收方账号
	Amount       int64  `json:"amount"`        // 分账金额（分）
	Description  string `json:"description"`   // 分账描述
	Result       string `json:"result"`        // 该接收方分账结果 PENDING/SUCCESS/FAIL
	FailReason   string `json:"fail_reason"`   // 该接收方失败原因
}

ProfitShareReceiver 分账明细（按接收方）。

type ProfitShareSubOrder added in v1.1.0 

type ProfitShareSubOrder struct {
	Mid         string `json:"mid"`          // 子商户号
	MerOrderID  string `json:"mer_order_id"` // 子订单号
	TotalAmount int64  `json:"total_amount"` // 子订单金额（分）
}

ProfitShareSubOrder 银联下单分账子商户。

type RefundCreateReq 

type RefundCreateReq struct {
	OutTradeNo   string `json:"out_trade_no"`  // 原订单号
	OutRefundNo  string `json:"out_refund_no"` // 退款单号
	RefundAmount int64  `json:"refund_amount"` // 退款金额（分）
	RefundReason string `json:"refund_reason,omitempty"`
}

RefundCreateReq 退款申请请求。

type RefundCreateResp 

type RefundCreateResp struct {
	OutRefundNo  string `json:"out_refund_no"`
	RefundID     string `json:"refund_id"`
	RefundAmount int64  `json:"refund_amount"`
	Status       string `json:"status"` // PROCESSING
}

RefundCreateResp 退款申请响应。

type RefundQueryReq 

type RefundQueryReq struct {
	OutRefundNo string `json:"out_refund_no"`
}

RefundQueryReq 退款查询请求。

type RefundQueryResp 

type RefundQueryResp struct {
	OutRefundNo  string `json:"out_refund_no"`
	RefundID     string `json:"refund_id"`
	OutTradeNo   string `json:"out_trade_no"`
	RefundAmount int64  `json:"refund_amount"`
	Status       string `json:"status"` // PROCESSING / SUCCESS / FAIL
	RefundTime   int64  `json:"refund_time"`
}

RefundQueryResp 退款查询响应。

type SmsBalanceResp 

type SmsBalanceResp struct {
	TotalRemaining int64            `json:"total_remaining"`
	Packages       []SmsPackageInfo `json:"packages"`
}

SmsBalanceResp 余额查询响应。

type SmsPackageInfo 

type SmsPackageInfo struct {
	ID          string `json:"id"`
	PackageName string `json:"package_name"`
	Total       int64  `json:"total"`
	Remaining   int64  `json:"remaining"`
	ExpiredAt   int64  `json:"expired_at"`
}

SmsPackageInfo 套餐信息。

type SmsSendReq 

type SmsSendReq struct {
	Phone         string            `json:"phone"`                    // 必填：目标手机号
	TemplateCode  string            `json:"template_code"`            // 必填：平台模板编码
	Params        map[string]string `json:"params,omitempty"`         // 模板变量
	SignatureName string            `json:"signature_name,omitempty"` // 指定签名（不传用模板关联的）
}

SmsSendReq 短信发送请求。

type SmsSendResp 

type SmsSendResp struct {
	SendID           string `json:"send_id"`
	Fee              int    `json:"fee"`
	BalanceRemaining int64  `json:"balance_remaining"`
}

SmsSendResp 短信发送响应。

type SmsService 

type SmsService struct {
	// contains filtered or unexported fields
}

SmsService 短信服务。

func (*SmsService) Balance 

func (s *SmsService) Balance(ctx context.Context) (*SmsBalanceResp, error)

Balance 查询短信余额。

func (*SmsService) Send 

func (s *SmsService) Send(ctx context.Context, req SmsSendReq) (*SmsSendResp, error)

Send 发送模板短信，消费套餐额度。

type SplitCreateReq added in v1.1.0 

type SplitCreateReq struct {
	OutTradeNo       string `json:"out_trade_no"`        // 必填：原商户订单号
	OutProfitShareNo string `json:"out_profit_share_no"` // 必填：商户分账单号（唯一）
	Amount           int64  `json:"amount,omitempty"`    // 可选：本次分账总金额（分），不传则按订单实付金额全额分账
}

SplitCreateReq 发起分账请求。

type SplitCreateResp added in v1.1.0 

type SplitCreateResp struct {
	OutProfitShareNo string                `json:"out_profit_share_no"`
	Channel          string                `json:"channel"`
	Amount           int64                 `json:"amount"`
	Status           string                `json:"status"` // PROCESSING（微信异步）/ SUCCESS（支付宝/银联同步）
	Receivers        []ProfitShareReceiver `json:"receivers"`
}

SplitCreateResp 发起分账响应。

type SplitQueryResp added in v1.1.0 

type SplitQueryResp struct {
	OutProfitShareNo string                `json:"out_profit_share_no"`
	OutTradeNo       string                `json:"out_trade_no"`
	Channel          string                `json:"channel"`
	Amount           int64                 `json:"amount"`
	Status           string                `json:"status"` // PROCESSING / SUCCESS / FAIL / PARTIAL
	ChannelRecordNo  string                `json:"channel_record_no"`
	Receivers        []ProfitShareReceiver `json:"receivers"`
	ProfitShareTime  int64                 `json:"profit_share_time"` // 分账完成时间（Unix 秒）
}

SplitQueryResp 分账查询响应。

type SplitReturnReq added in v1.1.0 

type SplitReturnReq struct {
	OutTradeNo       string `json:"out_trade_no"`          // 必填：原商户订单号
	OutProfitShareNo string `json:"out_profit_share_no"`   // 必填：原分账单号
	OutReturnNo      string `json:"out_return_no"`         // 必填：回退单号（唯一）
	ReturnAmount     int64  `json:"return_amount"`         // 必填：回退金额（分）
	Description      string `json:"description,omitempty"` // 可选：回退原因
}

SplitReturnReq 分账回退请求（仅微信）。

type SplitReturnResp added in v1.1.0 

type SplitReturnResp struct {
	OutReturnNo  string `json:"out_return_no"`
	ReturnNo     string `json:"return_no"`
	ReturnAmount int64  `json:"return_amount"`
	Status       string `json:"status"`
}

SplitReturnResp 分账回退响应。

type SplitUnsplitAmountResp added in v1.1.0 

type SplitUnsplitAmountResp struct {
	OutTradeNo    string `json:"out_trade_no"`
	UnsplitAmount int64  `json:"unsplit_amount"`
}

SplitUnsplitAmountResp 剩余待分金额响应。

type SubscriptionInfo 

type SubscriptionInfo struct {
	ID          string `json:"id"`
	ProductID   string `json:"product_id"`
	ProductName string `json:"product_name"`
	Version     string `json:"version"`
	PriceType   int8   `json:"price_type"`
	Amount      int64  `json:"amount"`
	Status      int8   `json:"status"` // 1-有效 0-已过期 2-已取消
	StartAt     int64  `json:"start_at"`
	ExpireAt    int64  `json:"expire_at"`
}

SubscriptionInfo 订阅信息。

type UnionPayMiniPayInfo added in v1.0.4 

type UnionPayMiniPayInfo struct {
	MiniPayRequest map[string]interface{} `json:"mini_pay_request"`
	SeqID          string                 `json:"seq_id"`
	MerOrderID     string                 `json:"mer_order_id"`
}

UnionPayMiniPayInfo 小程序支付调起参数。

type WSClient 

type WSClient struct {
	// contains filtered or unexported fields
}

WSClient WebSocket 实时推送客户端。

Example 
package main

import (
	"fmt"
	"log"
	"os"
	"os/signal"
	"time"

	sioyun "github.com/zhoudm1743/sioyun-sdk"
)

func main() {
	client, err := sioyun.New(sioyun.Config{
		BaseURL:   "https://api.sioyun.com/api/gateway/v1",
		AccessKey: os.Getenv("SIOYUN_AK"),
		SecretKey: os.Getenv("SIOYUN_SK"),
	})
	if err != nil {
		log.Fatal(err)
	}
	_ = client // HTTP 客户端

	// 创建独立的 WS 客户端
	ws := sioyun.NewWSClient(sioyun.Config{
		BaseURL:   "https://api.sioyun.com/api/gateway/v1",
		AccessKey: os.Getenv("SIOYUN_AK"),
		SecretKey: os.Getenv("SIOYUN_SK"),
	})

	// 注册事件处理器
	ws.On("payment.success", func(event sioyun.GatewayEvent) {
		fmt.Printf("收到支付成功通知: %+v\n", event.Data)
	})

	ws.On("payment.refund", func(event sioyun.GatewayEvent) {
		fmt.Printf("收到退款通知: %+v\n", event.Data)
	})

	ws.On("payment.*", func(event sioyun.GatewayEvent) {
		fmt.Printf("收到支付相关事件: %s\n", event.Event)
	})

	// 建立连接
	if err := ws.Connect(nil); err != nil {
		log.Fatal(err)
	}

	// 订阅频道
	ws.Subscribe("payment.*")
	ws.Subscribe("sms.delivered")

	// 优雅退出
	sig := make(chan os.Signal, 1)
	signal.Notify(sig, os.Interrupt)
	<-sig

	ws.Close()
	time.Sleep(time.Second)
}

func NewWSClient 

func NewWSClient(cfg Config) *WSClient

NewWSClient 创建 WebSocket 客户端。

func (*WSClient) Close 

func (w *WSClient) Close() error

Close 断开 WebSocket 连接。

func (*WSClient) Connect 

func (w *WSClient) Connect(ctx context.Context) error

Connect 建立 WebSocket 连接并鉴权。

func (*WSClient) On 

func (w *WSClient) On(event string, handler EventHandler)

On 注册事件处理器。event 支持通配符（"payment.*" 匹配 "payment.success"）。

func (*WSClient) Subscribe 

func (w *WSClient) Subscribe(channel string) error

Subscribe 订阅事件频道，支持通配符。 频道示例："payment.*", "sms.delivered", "partner.*"

func (*WSClient) Unsubscribe 

func (w *WSClient) Unsubscribe(channel string) error

Unsubscribe 取消订阅。

type WechatAppPayInfo added in v1.0.3 

type WechatAppPayInfo struct {
	AppID        string `json:"appId"`
	PartnerID    string `json:"partnerId"`
	PrepayID     string `json:"prepayId"`
	PackageValue string `json:"packageValue"`
	NonceStr     string `json:"nonceStr"`
	TimeStamp    string `json:"timeStamp"`
	Sign         string `json:"sign"`
}

WechatAppPayInfo 微信 APP 调起支付参数。

type WechatJsapiPayInfo added in v1.0.3 

type WechatJsapiPayInfo struct {
	AppID     string `json:"appId"`
	TimeStamp string `json:"timeStamp"`
	NonceStr  string `json:"nonceStr"`
	Package   string `json:"package"`
	SignType  string `json:"signType"`
	PaySign   string `json:"paySign"`
}

WechatJsapiPayInfo 微信 JSAPI 调起支付参数（用于 wx.requestPayment / WeixinJSBridge）。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.