包信息

NuGet 包：Bitzsoft.Integrations.Payment.PayPal
接口：IPaymentProvider
鉴权：OAuth2 client_credentials（ClientId / ClientSecret）
Provider ID：paypal

配置

字段	类型	必填	默认值	说明
`ClientId`	string	是	—	应用 Client Id
`ClientSecret`	string	是	—	应用 Client Secret
`BaseUrl`	string	否	`https://api-m.paypal.com`	API 基地址（沙箱自动切换 `https://api-m.sandbox.paypal.com`）
`UseSandbox`	bool	否	`false`	是否使用 sandbox 沙箱环境
`WebhookId`	string?	否	—	Webhook ID（VERIFY-WEBHOOK-SIGNATURE 端点验签所需）
`HttpClientName`	string	否	`PayPalPaymentProvider`	业务 HttpClient 命名
`TokenHttpClientName`	string	否	`PayPalPaymentProviderToken`	令牌刷新专用 HttpClient 命名
`Timeout`	TimeSpan	否	`00:00:30`	HTTP 请求超时

{
  "PayPal": {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "UseSandbox": false,
    "WebhookId": "your-webhook-id"
  }
}

注册

// 方式一：IConfiguration（默认读取 "PayPal" 配置节）
services.AddPayPalPayment(configuration);

// 方式二：委托配置
services.AddPayPalPayment(options =>
{
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.UseSandbox = false;
});

使用示例

var orderResult = await provider.CreateOrderAsync(new PaymentOrderRequest
{
    OutTradeNo = "ORDER_20260801_004",
    Subject = "PayPal Order",
    TotalAmount = 29.99m,
    Scene = PaymentScene.Web
});

// 查询状态
var status = await provider.QueryStatusAsync("ORDER_20260801_004");

// 退款
var refundResult = await provider.RefundAsync(new RefundRequest
{
    OutTradeNo = "ORDER_20260801_004",
    RefundAmount = 29.99m,
    RefundNo = "REFUND_003"
});

鉴权机制

令牌获取：POST /v1/oauth2/token，HTTP Basic Auth（ClientId:ClientSecret），grant_type=client_credentials。
令牌缓存：PayPalTokenManager 为 Singleton，持有内存令牌缓存，过期前自动刷新（SemaphoreSlim 并发安全）。
业务请求：按请求注入 Authorization: Bearer {token} 头。
双 HttpClient 隔离：令牌刷新 HttpClient 不经业务管道，避免循环依赖。

已知限制

UseSandbox 为 true 时，若 BaseUrl 仍为默认值则自动切换到沙箱地址。Webhook 验签需要配置 WebhookId。