如何通过Stripe.Net获取指定时段GBP付款退款列表

核心逻辑说明 #

你之前通过遍历Events列表筛选Charge的方案效率很低，且混淆了两个不同的币种字段：

• Charge对象自带的currency字段：记录付款人支付时使用的原始币种
• Charge/Refund关联的balance_transaction.currency字段：记录资金实际结算进入你Stripe账户的币种，也就是你需要的入账对应币种
  不要通过Events接口拉取交易记录，Events是用于webhook事件通知溯源的，全量拉取会包含大量无关数据，效率极低，直接用Stripe.Net内置的Charge、Refund列表接口即可实现需求。

具体实现代码 #

1. 拉取指定时间范围结算为GBP的成功付款记录 #

用ChargeService做游标分页拉取，通过Expand参数预加载关联的BalanceTransaction对象，避免多次请求触发速率限制：

// 初始化Stripe客户端
StripeConfiguration.ApiKey = "你的Stripe账户Secret Key";
var chargeService = new ChargeService();

// 配置查询参数：指定时间范围、单次拉取条数、预加载关联字段
var chargeOptions = new ChargeListOptions
{
    Limit = 100, // Stripe接口单次最大支持100条
    Created = new DateRangeOptions
    {
        // 替换为你需要的开始、结束时间，注意转成Unix时间戳
        GreaterThanOrEqual = new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero).ToUnixTimeSeconds(),
        LessThanOrEqual = new DateTimeOffset(2024, 1, 31, 23, 59, 59, TimeSpan.Zero).ToUnixTimeSeconds()
    },
    Expand = new List<string> { "data.balance_transaction" }
};

List<Charge> gbpSuccessPayments = new List<Charge>();
StripeList<Charge> currentPage;
do
{
    currentPage = await chargeService.ListAsync(chargeOptions);
    // 筛选实际结算币种为GBP、支付成功的记录
    var validRecords = currentPage.Where(c => 
        c.Status == "succeeded" 
        && c.BalanceTransaction?.Currency == "gbp"
    );
    gbpSuccessPayments.AddRange(validRecords);
    // 设置下一页游标
    chargeOptions.StartingAfter = currentPage.Data.LastOrDefault()?.Id;
} while (currentPage.HasMore);

2. 拉取指定时间范围结算为GBP的成功退款记录 #

和付款逻辑一致，使用RefundService拉取即可：

var refundService = new RefundService();
var refundOptions = new RefundListOptions
{
    Limit = 100,
    Created = new DateRangeOptions
    {
        GreaterThanOrEqual = new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero).ToUnixTimeSeconds(),
        LessThanOrEqual = new DateTimeOffset(2024, 1, 31, 23, 59, 59, TimeSpan.Zero).ToUnixTimeSeconds()
    },
    Expand = new List<string> { "data.balance_transaction" }
};

List<Refund> gbpSuccessRefunds = new List<Refund>();
StripeList<Refund> currentRefundPage;
do
{
    currentRefundPage = await refundService.ListAsync(refundOptions);
    var validRefunds = currentRefundPage.Where(r => 
        r.Status == "succeeded" 
        && r.BalanceTransaction?.Currency == "gbp"
    );
    gbpSuccessRefunds.AddRange(validRefunds);
    refundOptions.StartingAfter = currentRefundPage.Data.LastOrDefault()?.Id;
} while (currentRefundPage.HasMore);

特殊场景说明 #

• 如果你要找的是客户直接使用GBP付款的记录（而非其他币种兑换后结算为GBP的记录），不需要本地筛选BalanceTransaction，直接在ChargeListOptions里添加Currency = "gbp"参数即可，Stripe服务端会直接过滤返回原始币种为GBP的付款记录，效率更高。
• 退款如果要筛选原始退款币种为GBP的记录，同理在RefundListOptions里加Currency = "gbp"参数即可。

注意：必须实现游标分页逻辑，Stripe接口不支持跳过页码的offset分页，不做分页会导致数据拉取不全。Expand参数必须配置，否则每条记录都要单独发起一次请求查询BalanceTransaction，很容易触发Stripe的API速率限制。

内容的提问来源于stack exchange，提问作者Trevor Daniel