Forem: Peter Wurzinger

Trusting PayPal Webhooks the .NET Way

Peter Wurzinger — Sat, 24 Jan 2026 15:00:00 +0000

This is the second of the two-part series where I share my insights on the PayPal API and C#/.NET:

Part I covered proper HTTP request authentication for the PayPal API
Part II demonstrates building ASP.NET Core endpoints that accept PayPal webhooks, verifying their integrity and why that matters

Disclaimer

AI was used to refine phrasing, correct errors, and structure the content. The technical content and implementation were created entirely by me.

Prerequisites

This post won't cover how to set up an application integration in PayPal or how to register a webhook - check the official docs for that. I also assume you know what a webhook is and what you want to use it for. This post will show you how to verify the integrity of incoming requests and why you should still be cautious.

I'm using C# 14 and .NET 10, but you can adapt the code to earlier versions with minimal changes and some additional NuGet packages. Even for .NET Framework 3.5. (Just kidding - get rid of that already.)

Spam, Lisa, and trust in messages

Hi. Your bank account has been involved in fraudulent activity. Further transactions have been suspended, please follow this link to reactivate it.

If I sent you this email, would you believe me and take it at face value? Probably not.

But let's say your personal bank advisor calls you on your cell phone:

Hi Peter, it's Lisa from Fells Wargo. Last night, someone in Bangkok attempted to use your debit card to pay for an adult online service subscription. Could you come over to change the card?

I would at least consider that plausible. And alarming. And obviously I'm not going to tell Lisa that I'm on vacation in Southeast Asia. cough

Jokes aside, why does the second message prompt me to go to my local branch and take action, while I dismissed the first message as spam, even though their content is essentially identical?
This is highly subjective, but there are clues:

You know your personal bank advisor, you recognize her voice on the phone, and she's listed as an employee on your branch's website
She knows your phone number and your name
She doesn't ask for immediate action, but for verification in person

There's metadata that builds trust in the sender - certain indicators that make you think, "Some son of a biscuit is trying to spend my money."

Trusting Lisa - and PayPal

PayPal webhooks provide those clues via message signatures. They append a signature as a header to the HTTP request, which you can use to verify the request's integrity.

First, you need to build the string transmissionId|timeStamp|webhookId|crc32:

transmissionId from the HTTP request header PAYPAL-TRANSMISSION-ID
timeStamp from the HTTP request header PAYPAL-TRANSMISSION-TIME
webhookId is the Webhook ID you get after registering a webhook
crc32 is the CRC32 checksum of the HTTP request body

After assembling that, you'll end up with a string that looks like this:

db49fb10-1343-11ef-ac58-e32457403f67|2024-05-16T05:19:23Z|0NH55953DH663215D|2904282587

Its UTF-8 binary representation is the message that was signed. Where do you get the signature? The header PAYPAL-TRANSMISSION-SIG is what you're looking for. Since I scratched my head over this for quite some time, let me rephrase:

The value of the HTTP header PAYPAL-TRANSMISSION-SIG is the signature of the binary representation of the UTF-8 string db49fb10-1343-11ef-ac58-e32457403f67|2024-05-16T05:19:23Z|0NH55953DH663215D|2904282587.

Now we have the message and its signature. To actually verify it, we also need:

the algorithm
the public key of the sender

For the algorithm, there's another header in the request called PAYPAL-AUTH-ALGO. So far I've only seen the value SHA256withRSA, but we'll support different hash algorithms as well.

The public key takes a bit more effort to obtain. The request header PAYPAL-CERT-URL points to a PayPal endpoint where you can download the certificate. This certificate contains the public key that we'll feed into the RSA verification.

Summing it up conceptually

That was a lot of theory, so let me sum it up in pseudocode:

verify(webhookId, request):
    transmissionId = request.header["PAYPAL-TRANSMISSION-ID"]
    transmissionTime = request.header["PAYPAL-TRANSMISSION-TIME"]

    message = "{transmissionId}|
               {transmissionTime}|
               {webhookId}|
               {crc32(request.Body)}"

    algorithm = request.header["PAYPAL-AUTH-ALGO"]
    certificate = http_get(request.header["PAYPAL-CERT-URL"])
    signature = request.header["PAYPAL-TRANSMISSION-SIG"]

    return RSA.verify(message, signature, algorithm, certificate.publicKey)

Phew. Trusting Lisa was less complicated.

Finally some real-world code

Let's go. Luckily you don't have to implement the crypto stuff like CRC and RSA in .NET yourself - although for CRC32 you'll need the additional NuGet package System.IO.Hashing. And no, I don't have an idea why that is.

To support integrations beyond ASP.NET Core, I implemented a class that takes all the required inputs and the HTTP body as a Stream.

using System.IO.Hashing;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;

public sealed class PayPalWebhookVerifier(PayPalWebhookSignatureCertificateCache payPalSignatureCertificateCache)
{
  public async Task<bool> Verify(string webhookId,
                                 string authAlgo,
                                 string certUrl,
                                 string transmissionId,
                                 string transmissionSig,
                                 string transmissionTime,
                                 Stream stream,
                                 CancellationToken cancellationToken)
  {
    ArgumentException.ThrowIfNullOrEmpty(webhookId);

    ArgumentException.ThrowIfNullOrEmpty(authAlgo);
    if (!authAlgo.EndsWith("withRSA", StringComparison.OrdinalIgnoreCase))
      throw new NotImplementedException("Only RSA is supported as signature algorithm.");

    ArgumentException.ThrowIfNullOrEmpty(certUrl);
    var certificateEndpoint = new Uri(certUrl);
    if (!certificateEndpoint.Host.EndsWith("paypal.com", StringComparison.OrdinalIgnoreCase))
      return false;

    ArgumentException.ThrowIfNullOrEmpty(transmissionId);
    ArgumentException.ThrowIfNullOrEmpty(transmissionSig);
    ArgumentException.ThrowIfNullOrEmpty(transmissionTime);
    ArgumentNullException.ThrowIfNull(stream);

    using var certificate = await payPalSignatureCertificateCache.GetCertificateByCertUrl(certificateEndpoint, cancellationToken);
    if (certificate is null)
      return false;

    var crc32 = await GetCrc32(stream, cancellationToken);
    var message = Encoding.UTF8.GetBytes($"{transmissionId}|{transmissionTime}|{webhookId}|{crc32}");

    var messageSignature = Convert.FromBase64String(transmissionSig);

    return VerifySignature(message, messageSignature, certificate, authAlgo);
  }

  private static async Task<uint> GetCrc32(Stream stream, CancellationToken cancellationToken)
  {
    var crc32 = new Crc32();

    await crc32.AppendAsync(stream, cancellationToken);
    return crc32.GetCurrentHashAsUInt32();
  }

  private static bool VerifySignature(ReadOnlySpan<byte> message,
                                      ReadOnlySpan<byte> signature,
                                      X509Certificate2 certificate,
                                      string authAlgo)
  {
    using var rsa = certificate.GetRSAPublicKey()
                      ?? throw new InvalidOperationException("Certificate does not contain a public key.");

    var hashAlgorithmName = GetHashAlgorithmName(authAlgo);

    return rsa.VerifyData(message, signature, hashAlgorithmName, RSASignaturePadding.Pkcs1);
  }

  private static HashAlgorithmName GetHashAlgorithmName(string authAlgorithm)
  {
    //PayPal sends "SHA256withRSA"
    var hashAlgorithmName = authAlgorithm.Replace("withRSA", string.Empty, StringComparison.OrdinalIgnoreCase);
    return new HashAlgorithmName(hashAlgorithmName);
  }
}

That's essentially the verification process described in pseudocode, but let me add a few remarks.

The code assumes authAlgo is formatted as <hashAlgorithm>with<signatureAlgorithm>, but only supports RSA as the signature algorithm for now. It should be straightforward to add support for DSA, ECDH, or post-quantum algorithms like ML-DSA in the future if necessary. For the hash algorithm, it extracts the first part of that string, passes it to the HashAlgorithmName constructor, and therefore supports SHA256withRSA, SHA512withRSA, or SHA3-512withRSA. Mind you, this would also allow garbage like SorryNotSorrywithRSA, but at that point I prefer more concise syntax over excessive defensiveness, since it'll throw an exception when used anyway.

You might have noticed that AppendAsync advances the stream. Since I'm only using it for HttpRequest.Body, I was okay with leaving the stream reset to the caller. To read an HTTP request body multiple times, you can buffer it in memory with HttpRequest.EnableBuffering(). Here's my wrapper to make it easier to use with HttpRequest:

using Microsoft.AspNetCore.Http;

public static class PayPalWebhookVerifierExtensions
{
  public static async Task<bool> Verify(this PayPalWebhookVerifier verifier,
                                        string webhookId,
                                        HttpRequest request,
                                        CancellationToken cancellationToken)
  {
    string authAlgo;
    string certUrl;
    string transmissionId;
    string transmissionSig;
    string transmissionTime;

    try
    {
      authAlgo = GetSingleHeaderValue(request, "PAYPAL-AUTH-ALGO");
      certUrl = GetSingleHeaderValue(request, "PAYPAL-CERT-URL");

      transmissionId = GetSingleHeaderValue(request, "PAYPAL-TRANSMISSION-ID");
      transmissionSig = GetSingleHeaderValue(request, "PAYPAL-TRANSMISSION-SIG");
      transmissionTime = GetSingleHeaderValue(request, "PAYPAL-TRANSMISSION-TIME");
    }
    catch (ArgumentException)
    {
      return false;
    }

    request.EnableBuffering();
    try
    {
      return await verifier.Verify(webhookId, authAlgo, certUrl, transmissionId, transmissionSig, transmissionTime, request.Body, cancellationToken);
    }
    finally
    {
      request.Body.Seek(0, SeekOrigin.Begin);
    }
  }

  private static string GetSingleHeaderValue(HttpRequest request, string headerName)
  {
    var headerValues = request.Headers[headerName];
    if (headerValues.Count == 0)
      throw new ArgumentException($"HTTP header {headerName} was not present.");

    if (headerValues.Count > 1)
      throw new ArgumentException($"Multiple HTTP headers for {headerName} were present.");

    return headerValues.ToString();
  }
}

Nice.

Certificate validation and caching

You might have noticed I'm using a separate class called PayPalWebhookSignatureCertificateCache to retrieve the certificate, which I haven't shown yet. It deserves some explanation, but let me show you the code first:

using Microsoft.Extensions.Caching.Distributed;
using System.Security.Cryptography.X509Certificates;

public sealed class PayPalWebhookSignatureCertificateCache(IHttpClientFactory httpClientFactory,
                                                           IDistributedCache distributedCache)
{
  public async Task<X509Certificate2?> GetCertificateByCertUrl(Uri certUri, CancellationToken cancellationToken)
  {
    ArgumentNullException.ThrowIfNull(certUri);

    var canonicalCacheKey = certUri.ToString();
    var certData = await distributedCache.GetAsync(canonicalCacheKey, cancellationToken);

    var cacheHit = certData is not null;
    if (!cacheHit)
    {
      var httpClient = httpClientFactory.CreateClient(nameof(PayPalWebhookSignatureCertificateCache));
      certData ??= await httpClient.GetByteArrayAsync(certUri, cancellationToken);
    }

    var certificate = X509CertificateLoader.LoadCertificate(certData!);
    if (!certificate.Verify())
    {
      if (cacheHit)
        await distributedCache.RemoveAsync(canonicalCacheKey, cancellationToken);

      certificate.Dispose();
      return null;
    }

    if (!cacheHit)
      await StoreInCache(canonicalCacheKey, certificate, cancellationToken);

    return certificate;
  }

  private Task StoreInCache(string cacheKey, X509Certificate2 certificate, CancellationToken cancellationToken)
  {
    var entryOptions = new DistributedCacheEntryOptions
    {
      AbsoluteExpiration = certificate.NotAfter
    };
    return distributedCache.SetAsync(cacheKey, certificate.RawData, entryOptions, cancellationToken);
  }
}

This class takes the URI instance constructed from the certUrl parameter and tries to return a valid X509Certificate2 from either cache or the given endpoint. "Tries?" Let me explain.

Explaining PKI goes far beyond the scope of this article, but the short version is that it depends on trust. You trust a Certificate Authority to issue certificates to legitimate resource owners, and you trust those authorities to maintain their Certificate Revocation Lists. These lists essentially tell you: While this certificate seems valid, I'm telling you it's not. You should definitely respect that and consider the certificate invalid, since revocation happens when, for example, the private key has been compromised. Luckily, X509Certificate2 offers an all-in-one verification with the Verify() method. Alternatively, you could build an X509Chain yourself by specifying the policies you want to enforce. In any case: I verify both cached certificates and freshly downloaded ones. If a certificate fails verification, I won't use it and will remove it from the cache if necessary.

Readers of Part I are already familiar with how I like to match cache entry expiration with the lifetimes of stored objects. In this case, the NotAfter property determines the expiration, since the only way the cache entry needs to be invalidated earlier is because of revocation. And again: bandwidth matters. In this case even more so, since those certificates are roughly ~2KB that you'd download on each verification attempt. It doesn't sound like much, but doing that on each and every incoming webhook request adds up - besides, this endpoint may experience outages too.

Unlike in Part I, I'm using IDistributedCache because X509Certificate2 has a property called RawData. This is the certificate content as byte[], so you don't have to deal with serialization at all and can simply use it as the cache entry value. If you want, you can configure a truly distributed cache like Redis, or just stick with an in-memory implementation that's ready for scaling.

On clues and trust issues

Earlier I intentionally introduced the term clues to indicate a certain level of trust. I broke down why a call from Lisa made me think my bank account might actually be in trouble. Now let's find those clues for a webhook request with a matching signature:

The caller knows the endpoint in my application that accepts webhooks. - Or they're good at guessing.
The caller knows the webhookId, which is the only component of the message string not transmitted with the request itself. - Or they stood beside me when I opened the PayPal developer portal and noted it.
Since the message was signed, they possess the private key to a valid certificate hosted within the paypal.com domain. - Or...

At this point, if it walks like a duck and quacks like a duck... A potential attacker would have to invest quite a lot of effort to send malicious requests that you'd consider legitimate. What do we have left - DNS poisoning to redirect the certificate download maybe? Hard and unlikely, but not impossible. Depends on the reward, I'd argue.

Let's get back to Lisa briefly. She told me to come over to change my card in person. Why not do the same when a webhook request arrives? Well, not fly over to San Jose and ask them in person, but rather call the API to get the current state of whatever the request content claims.

public void HandlePayPalPaymentNotification(PaymentSuccessfulNotificationDtoOrWhatever webhook) {
  var payment = payPalApi.GetPayment(webhook.PaymentId);
  //Inspect payment.State or whatever you would do with it
}

Still not 100% secure - DNS poisoning mentioned above would obviously also affect outgoing HTTP requests - but you get additional security for the price of an API roundtrip. That's reasonable.

Also, webhook senders typically require you to complete the request within a certain timeframe to avoid blocking their resources indefinitely. PayPal enforces a maximum timeout of 30 seconds; anything exceeding that will see the request cancelled. If you're in the middle of booking the payment in your accounting system, that might lead to trouble. Instead, start a background job that handles the processing and return HTTP 200 immediately.

Integrating into ASP.NET Core

The depth of integration depends on your requirements. Nothing stops you from injecting PayPalWebhookVerifier into a controller action or minimal API endpoint and invoking the verification manually:

app.MapPost("/payPal/notify", async (HttpRequest request, PayPalWebhookVerifier verifier, IOptions<YourPayPalWebhookOptions> options, CancellationToken cancellationToken) => {
  var couldVerify = await verifier.Verify(options.Value.WebhookId, request, cancellationToken);
  if (!couldVerify)
    return TypedResults.Unauthorized();

  //...
});

But as the status code 401 for negative results implies, what we're essentially doing by running the verification procedure is authenticating the request. Since ASP.NET Core provides a whole subsystem with various integration points for authentication, why not utilize it and provide a reusable component?

To implement a custom authentication scheme, you need to bind an implementation of IAuthenticationHandler to a scheme name. To avoid starting from scratch, you can instead implement AuthenticationHandler<T>.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using System.Security.Claims;
using System.Text.Encodings.Web;

public sealed class PayPalWebhookAuthenticationHandler(IOptionsMonitor<AuthenticationSchemeOptions> options,
                                                       ILoggerFactory logger,
                                                       UrlEncoder encoder,
                                                       PayPalWebhookVerifier payPalWebhookVerifier)
  : AuthenticationHandler<AuthenticationSchemeOptions>(options, logger, encoder)
{
  protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
  {
    var endpoint = Context.GetEndpoint();
    if (endpoint is null)
      return AuthenticateResult.NoResult();

    var webhookMetadata = endpoint.Metadata.GetRequiredMetadata<PayPalWebhookMetadata>();
    var webhookId = webhookMetadata.WebhookIdAccessor(Context.RequestServices);

    var couldVerify = await payPalWebhookVerifier.Verify(webhookId, Context.Request, Context.RequestAborted);
    if (!couldVerify)
      return AuthenticateResult.Fail("Could not verify PayPal Webhook Request.");

    var ticket = BuildAuthenticationTicket(Scheme.Name);
    return AuthenticateResult.Success(ticket);
  }

  private static AuthenticationTicket BuildAuthenticationTicket(string authenticationSchemeName)
  {
    IEnumerable<Claim> claims = [new Claim(ClaimsIdentity.DefaultNameClaimType, "PayPal Webhook")];
    var identity = new ClaimsIdentity(claims, authenticationSchemeName);
    var principal = new ClaimsPrincipal(identity);
    return new AuthenticationTicket(principal, authenticationSchemeName);
  }
}

internal sealed record PayPalWebhookMetadata(Func<IServiceProvider, string> WebhookIdAccessor);

PayPalWebhookMetadata provides a way to access the Webhook ID. Normally this would be encapsulated in a dedicated class derived from AuthenticationSchemeOptions. I decided against that because there's usually a one-to-one mapping between a webhook registration and an application endpoint, meaning the Webhook ID is a property that's only valid for one specific endpoint. Therefore, it felt natural to implement it as endpoint metadata instead. Since the accessor's parameter is the request-scoped service provider, you can obtain the Webhook ID however you like.

What's left now is to provide an extension to register the required services and authentication scheme, and an extension to configure an endpoint to authenticate with this specific authentication scheme.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using System.Diagnostics.CodeAnalysis;

public static class PayPalWebhookVerificationExtensions
{
  public const string AuthenticationSchemeName = "PayPalWebhook";

  public static IServiceCollection AddPayPalWebhookVerification(this IServiceCollection services)
  {
    ArgumentNullException.ThrowIfNull(services);

    services.AddHttpClient();
    services.AddDistributedMemoryCache();
    services.TryAddSingleton<PayPalWebhookVerifier>();
    services.TryAddSingleton<PayPalWebhookSignatureCertificateCache>();

    return services.AddAuthenticationCore(options =>
    {
      if (!options.Schemes.Any(s => s.Name == AuthenticationSchemeName))
        options.AddScheme<PayPalWebhookAuthenticationHandler>(AuthenticationSchemeName, "PayPal Webhook");
    });
  }

  public static RouteHandlerBuilder MapPayPalWebhook<TBuilder>(this TBuilder builder,
                                                               [StringSyntax("Route")] string pattern,
                                                               Delegate handler,
                                                               Func<IServiceProvider, string> webhookIdAccessor)
    where TBuilder : IEndpointRouteBuilder
  {
    ArgumentNullException.ThrowIfNull(builder);
    ArgumentNullException.ThrowIfNull(webhookIdAccessor);

    var endpoint = builder.MapPost(pattern, handler);

    endpoint.WithMetadata(new PayPalWebhookMetadata(webhookIdAccessor));
    endpoint.RequireAuthorization(b =>
    {
      b.AuthenticationSchemes = [AuthenticationSchemeName];
      b.RequireAuthenticatedUser();
    });

    return endpoint;
  }
}

By calling MapPayPalWebhook, an HTTP POST endpoint is added with webhookIdAccessor as endpoint metadata, and a custom authorization policy ensures the request will be authenticated using the scheme registered above.

Implementing verification as an authentication scheme also has the nice side effect that you can bypass it in development environments:

var webhookEndpoint = app.MapPayPalWebhook("/payPal/notify", ...);
if (app.Environment.IsDevelopment())
  webhookEndpoint.AllowAnonymous();

To test the endpoint, you don't have to actually build signed requests or use the webhooks simulator - simply use Swagger or Scalar to paste in the JSON payload.

Let's revisit the example from earlier in this section:

services.AddPayPalWebhookVerification();

//...

app.MapPayPalWebhook("/payPal/notify", () => {
  //...
}, s => s.GetRequiredService<IOptions<YourPayPalWebhookOptions>>().Value.WebhookId);

Now that's what I'd call separation of concerns.

Closing words

You made it to the end - congratulations. When I started writing, I didn't expect to have this much to say, but apparently there was a lot to explain about properly verifying PayPal webhooks using C# and .NET 10. If you have feedback or suggestions for improvements, I'd truly appreciate a comment. As in Part I, I don't claim to have the best solution possible, but what I presented worked well for me.

If my code or explanations saved you time in a business context, consider leaving a donation.

Handling PayPal API Authentication the .NET Way

Peter Wurzinger — Sat, 10 Jan 2026 15:00:00 +0000

This is the first post in a two-part series where I share my insights on the PayPal API and C#/.NET:

Part I covers proper HTTP request authentication for the PayPal API
Part II demonstrates building ASP.NET Core endpoints that accept PayPal webhooks, verifying their integrity and why that matters

Disclaimer

AI was used to refine phrasing, correct errors, and structure the content. The technical content and implementation were created entirely by me.

Prerequisites

This post won't cover setting up a PayPal developer account — check the official docs for that. If you're still reading, you probably already know the drill.

This also isn't about architecting payment or subscription systems. It's purely focused on handling API authentication so you can concentrate on the more interesting bits.

I'm using C# 14 and .NET 10, but you can adapt this code to earlier versions with minimal changes and some additional NuGet packages. Unless you're stuck on .NET Framework 3.5 — then you need an exorcist.

Store your secrets the .NET way

After creating an application in the PayPal developer portal, you'll receive a CLIENT_ID and CLIENT_SECRET. As the name suggests, one is more secret than the other. I recommend using the options pattern to bind and retrieve them at runtime.

Beyond the credentials, I also store:

The PayPal API base address
An expiration threshold timespan

The base address lets you switch between Sandbox and Live environments (or even route through a proxy if you're feeling adventurous). The expiration threshold provides a safety buffer to account for clock skew or race conditions between API calls and token expiration.

public sealed record PayPalOptions
{
  public required Uri BaseAddress { get; init; }
  public required string ClientId { get; init; }
  public required string ClientSecret { get; init; }
  public TimeSpan TokenRefreshThreshold { get; init; } = TimeSpan.FromMinutes(5);
}

I like to validate my options — either via Data Annotations or by implementing IValidateOptions:

public sealed class PayPalOptionsValidation : IValidateOptions<PayPalOptions>
{
  public ValidateOptionsResult Validate(string? name, PayPalOptions options)
  {
    var resultBuilder = new ValidateOptionsResultBuilder();

    if (options.BaseAddress is null)
      resultBuilder.AddError($"{nameof(PayPalOptions.BaseAddress)} must not be null.", nameof(PayPalOptions.BaseAddress));

    if (string.IsNullOrEmpty(options.ClientId))
      resultBuilder.AddError($"{nameof(PayPalOptions.ClientId)} must not be null or empty.", nameof(PayPalOptions.ClientId));

    if (string.IsNullOrEmpty(options.ClientSecret))
      resultBuilder.AddError($"{nameof(PayPalOptions.ClientSecret)} must not be null or empty.", nameof(PayPalOptions.ClientSecret));

    if (options.TokenRefreshThreshold < TimeSpan.Zero)
      resultBuilder.AddError($"{nameof(PayPalOptions.TokenRefreshThreshold)} must not be less than 0.", nameof(PayPalOptions.TokenRefreshThreshold)); ;

    return resultBuilder.Build();
  }
}

In development, you could bind the values from User Secrets:

{
    "PayPal": {
        "Endpoint": "https://api-m.paypal.com/",
        "ClientId": "...",
        "ClientSecret": "..."
    }
}

and bind it via:

services.Configure<PayPalOptions>(configuration.GetSection("PayPal"));

BUT PLEASE: Don't dump secrets into appsettings.Development.json. Use User Secrets — there's no excuse not to.

Tokens everywhere

The docs specify that you need to attach an OAuth 2.0 access token as an Authorization header to access most API endpoints. This access token is neither your CLIENT_ID nor your CLIENT_SECRET. Instead, there's a dedicated endpoint at v1/oauth2/token that exchanges your credentials for a short-lived token.

Obtain your token

Conceptually, before sending a request to the PayPal API, you need to:

Retrieve an instance of PayPalOptions
Exchange your credentials for an access token by calling the OAuth token endpoint
Attach the returned access token as a header to your request

For dynamically retrieving credentials and attaching them to HTTP requests, I find implementing a DelegatingHandler most convenient. It provides fine-grained control over the send pipeline and integrates seamlessly with IHttpClientFactory. If you're not already familiar with IHttpClientFactory concepts, get up to speed — it'll make your life easier.

Here's an implementation that does exactly that:

using Microsoft.Extensions.Options;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json.Serialization;

public sealed class PayPalAuthenticationHandler(HttpClient authClient,
                                                IOptionsMonitor<PayPalOptions> optionsMonitor) : DelegatingHandler
{
  protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
  {
    var options = optionsMonitor.CurrentValue;

    var authenticationToken = await RenewToken(options, cancellationToken);
    request.Headers.Authorization = new("Bearer", authenticationToken!.AccessToken);

    return await base.SendAsync(request, cancellationToken);
  }

  private async Task<PayPalTokenResponse> RenewToken(PayPalOptions options, CancellationToken cancellationToken)
  {
    var tokenEndpoint = new Uri("v1/oauth2/token", UriKind.Relative);

    using var request = new HttpRequestMessage(HttpMethod.Post, tokenEndpoint);

    using var content = new FormUrlEncodedContent([new("grant_type", "client_credentials")]);
    request.Content = content;
    request.Headers.Authorization = new("Basic", GetBasicAuthCredentials());

    var response = await authClient.SendAsync(request, cancellationToken);
    response.EnsureSuccessStatusCode();

    return (await response.Content.ReadFromJsonAsync<PayPalTokenResponse>(cancellationToken: cancellationToken))!;

    string GetBasicAuthCredentials()
    {
      var authLiteral = $"{options.ClientId}:{options.ClientSecret}";
      var encodedLiteral = Encoding.UTF8.GetBytes(authLiteral);

      return Convert.ToBase64String(encodedLiteral);
    }
  }

  private sealed record PayPalTokenResponse
  {
    [JsonPropertyName("scope")]
    public required string Scope { get; init; }

    [JsonPropertyName("access_token")]
    public required string AccessToken { get; init; }

    [JsonPropertyName("token_type")]
    public required string TokenType { get; init; }

    [JsonPropertyName("app_id")]
    public required string AppId { get; init; }

    [JsonPropertyName("expires_in")]
    public required int ExpiresIn { get; init; }

    [JsonPropertyName("nonce")]
    public required string Nonce { get; init; }
  }
}

Since PayPalAuthenticationHandler depends on HttpClient, you need to configure it during registration. Providing an extension method on IServiceCollection is a well-established pattern.

For my use cases, accepting the dependent service as a generic type parameter works well — similar to AddHttpClient<TClient>(). The HttpClient dependency in your client type will automatically be configured to retrieve an access token before each request. The name AddPayPalHttpClient telegraphs its purpose, but add docs if needed.

Depending on your architecture, you might need additional overloads, but this should give you the general idea:

public static class PayPalHttpClientExtensions
{
  public static IServiceCollection AddPayPalHttpClient<TClient>(this IServiceCollection services)
      where TClient : class
  {
    services.AddOptionsWithValidateOnStart<PayPalOptions, PayPalOptionsValidation>();
    services.AddHttpClient<PayPalAuthenticationHandler>(ConfigureBaseAddress);

    services.AddHttpClient<TClient>(ConfigureBaseAddress)
            .AddHttpMessageHandler<PayPalAuthenticationHandler>();

    return services;
  }

  private static void ConfigureBaseAddress(IServiceProvider serviceProvider, HttpClient httpClient)
  {
    var payPalOptions = serviceProvider.GetRequiredService<IOptions<PayPalOptions>>();
    httpClient.BaseAddress = payPalOptions.Value.BaseAddress;
  }
}

Note that both the client service and PayPalAuthenticationHandler are configured with ConfigureBaseAddress.

A PayPal API client and its registration could look like this:

class PayPalPaymentClient(HttpClient httpClient) {
  //Do some fancy financial calls to e.g. /v2/payments/...
}

//Registration
services.AddPayPalHttpClient<PayPalPaymentClient>();

Cache your token

The implementation above works fine but requests a new token for every API call, even when the previous one is still valid. This might be acceptable if calls are infrequent.

But let's be real: bandwidth matters. In cloud environments, it costs actual money (or egress units or cloud-funny-money). Caching the token until expiration is straightforward — let me show you.

.NET offers several caching options:

In-Memory Cache
Distributed Cache
Hybrid Cache
Libraries like FusionCache
Direct integration with Redis or memcached

Which suits you best depends on your use case and deployment topology, but it likely only matters if you already know the driving factors. I recommend keeping it simple initially — use an in-memory cache to handle token expiration within the application lifetime and go fancy when you see the need.

Conceptually, check if there's an unexpired cache hit for the token response:

If yes, use the cached token
If not, retrieve and cache it

The cache entry expiration equals the token expiration minus the expiration threshold (to account for clock skew, network delays, and thunderstorms).

I added dependencies on TimeProvider and IMemoryCache, and implemented token renewal as a GetOrCreate factory:

public sealed class PayPalAuthenticationHandler(HttpClient authClient,
                                                TimeProvider timeProvider,
                                                IMemoryCache cache,
                                                IOptionsMonitor<PayPalOptions> optionsMonitor) : DelegatingHandler
{
  protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
  {
    var options = optionsMonitor.CurrentValue;

    var cacheKey = $"PayPal:{options.ClientId}:Token";
    var authenticationToken = await cache.GetOrCreateAsync(cacheKey, async entry =>
    {
      var renewalTime = timeProvider.GetUtcNow();
      var token = await RenewToken(options, cancellationToken);

      entry.AbsoluteExpiration = renewalTime + TimeSpan.FromSeconds(token.ExpiresIn) - options.TokenRefreshThreshold;

      return token;
    });

    request.Headers.Authorization = new("Bearer", authenticationToken!.AccessToken);

    return await base.SendAsync(request, cancellationToken);
  }

  //Rest stays the same

The token contains an ExpiresIn property (expiration time in seconds). You could feed it directly into entry.AbsoluteExpirationRelativeToNow and it would probably work fine. But that felt sloppy to me — the value for "now" would differ from the "now" used by PayPal to determine ExpiresIn. So I took a defensive approach and captured the current time before the request as the base for adding ExpiresIn.

The beauty of using a cache: you don't have to manage token expiration manually. The cache discards expired tokens and calls the factory method to renew them automatically.

And that's it. Tokens are cached for the lifetime of the application service container, which for web apps means until the app instance shuts down.

Oh and you need to register services needed for IMemoryCache:

//PayPalHttpClientExtensions
services.AddMemoryCache();

Cache your token even harder

You could. If you're feeling ambitious, use IDistributedCache instead of IMemoryCache. There's no GetOrCreate helper and you'll need to serialize your token, but if that's worthwhile for you, replace the cache logic with something like:

PayPalTokenResponse? authenticationToken;
var serializedToken = await distributedCache.GetAsync(cacheKey, cancellationToken);
if (serializedToken is null)
{
  var renewalTime = timeProvider.GetUtcNow();

  authenticationToken = await RenewToken(options, cancellationToken);

  serializedToken = JsonSerializer.SerializeToUtf8Bytes(authenticationToken);
  await distributedCache.SetAsync(cacheKey, serializedToken, new()
  {
    AbsoluteExpiration = renewalTime + TimeSpan.FromSeconds(authenticationToken.ExpiresIn) - options.TokenRefreshThreshold
  }, cancellationToken);
}
else
{
  authenticationToken = JsonSerializer.Deserialize<PayPalTokenResponse>(serializedToken);
}

Since PayPalTokenResponse already has JSON serialization annotations, using it as the serialization format is a nice synergy.

Caching Level over 9000

I tried. HybridCache seemed like the logical next step to offer an opt-in mechanism for configuring an additional distributed cache like Redis or memcached.
Unfortunately, HybridCache doesn't appear to support setting cache entry expiration dynamically. At this point, for my use case, it simply wasn't worth digging deeper to force it to work.

Things I didn't care about

Exposing the Token

There was no need to, so I didn't. I'm fine with storing and renewing it in the HTTP message handler without external access. If you need the token elsewhere, consider implementing a dedicated PayPalTokenService that encapsulates token handling.

Transient failures and dedicated exceptions

Yeah, guilty as charged. For the token exchange API call, you could hook up a resilience pipeline to handle timeouts and HTTP 500 errors. Instead of EnsureSuccessStatusCode(), you could inspect the status and throw something like a PayPalAuthenticationException for HTTP 4xx.

Closing words

In this article, we explored how to encapsulate authentication for PayPal API requests and demonstrated ways to reduce your application's traffic by caching tokens.

I don't claim this is the best solution available — I wanted to share what worked well for me. If you have feedback or suggestions, drop them in the comments.

If this code or explanation saved you time in a business context, consider leaving a donation.