GameCore.PaymentSystem

PaymentBalanceInfo 仅客户端

命名空间 GameCore.PaymentSystem

public readonly struct PaymentBalanceInfo : IEquatable<PaymentBalanceInfo>

旧版客户端星火币余额详情。

• CurrentBalance — 当前可用星火币余额。
• TotalCoin — 旧版支付服务返回的账号级汇总值；不是当前项目消费。

构造函数

PaymentBalanceInfo 仅客户端

public PaymentBalanceInfo(long CurrentBalance, long TotalCoin)

旧版客户端星火币余额详情。

• CurrentBalance — 当前可用星火币余额。
• TotalCoin — 旧版支付服务返回的账号级汇总值；不是当前项目消费。

属性

CurrentBalance 仅客户端

public long CurrentBalance { get; init; }

当前可用星火币余额。

TotalCoin 仅客户端

public long TotalCoin { get; init; }

旧版支付服务返回的账号级汇总值；不是当前项目消费。

方法

ToString 仅客户端

public override string ToString()

operator != 仅客户端

public static bool operator !=(PaymentBalanceInfo left, PaymentBalanceInfo right)

operator == 仅客户端

public static bool operator ==(PaymentBalanceInfo left, PaymentBalanceInfo right)

GetHashCode 仅客户端

public override int GetHashCode()

Equals 仅客户端

public override bool Equals(object obj)

Equals 仅客户端

public bool Equals(PaymentBalanceInfo other)

Deconstruct 仅客户端

public void Deconstruct(out long CurrentBalance, out long TotalCoin)

PaymentClient 仅客户端

命名空间 GameCore.PaymentSystem

public static class PaymentClient

客户端支付 API。通过 IPaymentProvider 调用原生平台支付 SDK。 支付完成后的通知由服务端 PaymentServer 处理。

方法

GetCurrentBalance 仅客户端

public static long? GetCurrentBalance()

查询当前客户端登录用户的星火币余额。 仅支持当前用户，不提供任意 userId 查询。

返回： 当前星火币余额；查询失败时返回 null。

GetBalanceInfo 仅客户端

public static PaymentBalanceInfo? GetBalanceInfo()

查询旧版余额详情接口。

返回： 旧版余额详情；客户端不支持或查询失败时返回 null。

备注

返回值中的 TotalCoin 不是当前项目消费统计， 不应再用于业务判断。保留此方法仅用于避免旧项目调用被删除后直接中断。

RequestPayment 仅客户端

public static bool RequestPayment(string productId, string productName, string productDesc, int price, string? extra = null)

发起平台支付请求

• productId — 商品标识
• productName — 商品显示名称
• productDesc — 商品描述
• price — 价格（星火币数量）
• extra — 附加数据（透传给支付回调），可为空

返回： 请求是否成功发出（不代表支付成功）

RequestPayment 仅客户端

public static bool RequestPayment(string productId, string productName, string productDesc, int price, string serverId, string? extra = null)

发起平台支付请求（手动指定 serverId）。 通常不需要手动指定，推荐使用不带 serverId 的重载。

• productId — 商品标识
• productName — 商品显示名称
• productDesc — 商品描述
• price — 价格（星火币数量）
• serverId — 服务器/游戏标识
• extra — 附加数据（透传给支付回调），可为空

返回： 请求是否成功发出（不代表支付成功）

PaymentCompensationContext 仅服务端

命名空间 GameCore.PaymentSystem

public sealed class PaymentCompensationContext

支付补偿上下文。补偿处理方应只向事务追加与原支付等值的项目内货币返还操作。

属性

Notification 仅服务端

public PaymentNotification Notification { get; }

支付通知数据。

Transaction 仅服务端

public TransactionBuilder Transaction { get; }

独立补偿事务。此事务不包含原始 PaymentHandler 的任何操作。

PaymentDeliveryContext 仅服务端

命名空间 GameCore.PaymentSystem

public sealed class PaymentDeliveryContext

支付交付上下文，组合支付通知数据与事务操作器。 框架创建此上下文并传递给 PaymentHandler，Handler 通过 Transaction 追加物品发放等操作，框架随后追加星火币扣除操作并统一提交， 保证物品发放和星火币扣除在同一原子事务中完成。

属性

Notification 仅服务端

public PaymentNotification Notification { get; }

支付通知数据（只读）

Transaction 仅服务端

public TransactionBuilder Transaction { get; }

事务操作器，Handler 应使用此实例追加物品发放等操作。 不要在 Handler 中调用 ExecuteAsync()，框架将在 Handler 返回后统一提交。

PurchaseStat 仅服务端

public PurchaseStat? PurchaseStat { get; }

支付成功后需要写入后台的商品购买统计。为空时框架会按支付通知生成兜底统计。

方法

SetPurchaseStat 仅服务端

public void SetPurchaseStat(PurchaseStat purchaseStat)

设置本次支付对应的商品购买统计。框架仅在商品发放和星火币扣除均成功后写入。

PaymentNotification 双端

命名空间 GameCore.PaymentSystem

public sealed class PaymentNotification

从支付服务器接收的支付通知数据。

构造函数

PaymentNotification 双端

public PaymentNotification()

属性

MsgId 双端

public long MsgId { get; init; }

消息 ID，用于请求/响应匹配

ServerId 双端

public string ServerId { get; init; }

服务器/游戏标识

UserId 双端

public string UserId { get; init; }

用户 ID

OrderId 双端

public string OrderId { get; init; }

订单 ID

CallbackChannel 双端

public string CallbackChannel { get; init; }

回调频道（用于向 XdPayServer 发送确认）

Gemstone 双端

public long Gemstone { get; init; }

星火币数量

ProductionId 双端

public string ProductionId { get; init; }

商品标识

方法

TryParse 双端

public static PaymentNotification? TryParse(ReadOnlySpan<byte> data)

从 MsgPack 字节数组解析支付通知。 仅支持 XdPayServer 发送的固定格式（fixmap + fixstr keys + int/str values）。

PaymentServer 仅服务端

命名空间 GameCore.PaymentSystem

public static class PaymentServer

服务端支付处理器。

属性

PaymentHandler 仅服务端

public static Func<User, PaymentDeliveryContext, Task<bool>>? PaymentHandler { get; set; }

支付通知处理委托。游戏层注册此委托以处理 gem2game 通知。 收到通知后，处理方应通过 Transaction 追加物品发放操作， 返回 true 表示物品已准备好发放，返回 false 表示拒绝此订单。 不要在 Handler 中调用 Transaction.ExecuteAsync()，框架将在 Handler 返回后统一提交。

PaymentCompensationHandler 仅服务端

public static Func<User, PaymentCompensationContext, Task<bool>>? PaymentCompensationHandler { get; set; }

支付已扣除但降级发货失败时的补偿委托。 补偿委托应仅向独立事务追加等值项目内货币返还操作，不应调用原始 PaymentHandler。

方法

QueryCurrentProjectConsumptionAsync 仅服务端

public static Task<long?> QueryCurrentProjectConsumptionAsync(User user)

查询当前游戏局用户在本项目中已结算的星火币累计消耗。

备注

这是服务端 API。Host 会校验用户属于当前游戏局，并固定使用当前项目 ID。

SubscribePayment 仅服务端

public static void SubscribePayment(User user)

为指定用户订阅支付通知。应在用户加入游戏时调用。

• user — 用户对象

UnsubscribePayment 仅服务端

public static void UnsubscribePayment(User user)

取消订阅指定用户的支付通知。应在用户离开游戏时调用。

• user — 用户对象

事件

OnPaymentDelivered 仅服务端

public static event Action<User, PaymentNotification>? OnPaymentDelivered

支付通知处理成功后触发。用于额外处理（如推送 UI 更新）。 此事件在确认回执发送之后触发。

OnPaymentCompensated 仅服务端

public static event Action<User, PaymentNotification>? OnPaymentCompensated

支付已结算但商品发放失败、项目内货币补偿成功后触发。

PurchaseStat 仅服务端

命名空间 GameCore.PaymentSystem

public sealed class PurchaseStat

后台商品购买统计字段。框架会将该结构写入平台商品购买记录。

构造函数

PurchaseStat 仅服务端

public PurchaseStat()

属性

ItemLink 仅服务端

public string ItemLink { get; init; }

商品 ID / link。

CostLink 仅服务端

public string CostLink { get; init; }

消耗资源 ID / link。星火币支付可传 "星火币"。

Count 仅服务端

public int Count { get; init; }

购买数量。

Price 仅服务端

public int Price { get; init; }

商品单价。

IsRealMoney 仅服务端

public bool IsRealMoney { get; init; }

是否为星火币消耗。

PurchaseStatReporter 仅服务端

命名空间 GameCore.PaymentSystem

public static class PurchaseStatReporter

受限购买统计入口。仅写入平台支持的商品购买统计字段集合。

方法

EmitBuyStat 仅服务端

public static bool EmitBuyStat(long userId, PurchaseStat stat)