Article .NET

Article

C# Union Types for Payment Requests

A practical introduction to C# 15 union types using PayPal and Stripe payment requests.

2 min read .NET

C# 15 introduces union types: a way to say that a value is exactly one of a fixed set of types.

This is useful when an application has a small number of valid shapes, but those shapes do not need a shared base class. A checkout flow is a good example: a payment request can be for PayPal or Stripe, and the code processing it must handle both.

Union types are currently a preview feature. They are available with .NET 11 Preview 2 and require <LangVersion>preview</LangVersion>.

Model the allowed payment requests

Instead of accepting object, define the two request types and the closed set that can contain them:

public record class PayPalPayment(string OrderId, string PayerId);

public record class StripePayment(
    string PaymentIntentId,
    string PaymentMethodId);

public union PaymentRequest(PayPalPayment, StripePayment);

PaymentRequest can now hold a PayPalPayment or a StripePayment—and nothing else. The compiler adds implicit conversions, so creating one stays straightforward:

PaymentRequest request = new StripePayment(
    PaymentIntentId: "pi_3QExample",
    PaymentMethodId: "pm_card_visa");

Handle every provider explicitly

Pattern matching unwraps the union value for us. Because PaymentRequest has only two cases, the switch is complete without a catch-all branch:

static string GetProviderReference(PaymentRequest request) => request switch
{
    PayPalPayment payPal => $"PayPal order: {payPal.OrderId}",
    StripePayment stripe => $"Stripe intent: {stripe.PaymentIntentId}",
};

That is the main benefit: the payment gateway choices become part of the type contract. If the application later adds BankTransferPayment to PaymentRequest, the compiler identifies every switch that still needs to handle it.

What happens under the hood

The union declaration is compiler shorthand for a struct. It creates a constructor for each case type and exposes the selected value through an object? Value property. Those constructors support the implicit conversions used earlier.

For this example, the underlying value is either a PayPalPayment or a StripePayment. Pattern matching looks at Value automatically, which is why the switch arms can match the payment types directly instead of first reading request.Value.

The generated storage is one object? reference. That is simple and works well for the reference-type payment records above. A union that contains a value type, such as int, stores that value by boxing it; avoid relying on the shorthand in allocation-sensitive paths without measuring. Custom union types can use the Union attribute and a non-boxing TryGetValue pattern when they need a different storage strategy.

Like every struct, a union has a default value. default(PaymentRequest).Value is null, so code that could receive a default-initialized union should include a null arm:

static string GetProviderName(PaymentRequest request) => request switch
{
    PayPalPayment => "PayPal",
    StripePayment => "Stripe",
    null => "No payment request",
};

Why not use an interface or object?

An interface or base class can be a good fit when payment providers share behavior. But it is not a closed list—other types can still implement or inherit from it. object is even looser: it accepts any value and forces callers to defend against unexpected types at runtime.

A union is a better fit when the important rule is: these are the only supported request shapes. It keeps that rule near the model and gives the compiler enough information to check every decision point.

Read my previous article on discriminated unions in TypeScript.

Reference

Related articles

Keep reading

Search

Search the publication

Search articles and topic pages without leaving the page.