BlazorBasics.PayPal 1.0.2

BlazorBasics.PayPal

A Blazor component library that integrates the PayPal JavaScript SDK to render a PayPal checkout button with full cart support, currency handling, and transaction callbacks.

Table of Contents

• Installation
• Setup
• Usage
• Parameters
• Models
  • CartTotals
  • PaypalProduct
  • PaypalTransaction
  • Money
• Interfaces
  • ICurrencyConvertion
• Callbacks
• Examples

Installation

Install the NuGet package:

dotnet add package BlazorBasics.PayPal

Setup

Register the JS interop in your index.html (or App.razor host page). The component automatically loads JS module import — no additional script tag is required.

Usage

Add the PaypalButton component to any Blazor page or component:

<PaypalButton
    MerchantId="YOUR_PAYPAL_CLIENT_ID"
    CalculateTotalToPay="GetTotals"
    GetProducts="GetCartProducts"
    OnApproved="HandleApproved"
    OnCancel="HandleCancel"
    OnTransactionError="HandleError"
    OnLoad="HandleLoad" />

Parameters

Models

CartTotals

Represents the full breakdown of cart amounts passed to PayPal.

public class CartTotals
{
    public Money Total { get; set; }
    public Money Discounts { get; set; }
    public Money Shipping { get; set; }
    public Money Tax { get; set; }
    public Money Handling { get; set; }
    public Money Insurance { get; set; }
}

Constructor:

new CartTotals(
    total: new Money(100.00m, "USD"),
    discounts: new Money(5.00m, "USD"),
    shipping: new Money(10.00m, "USD"),
    tax: new Money(8.50m, "USD")
)

All optional fields default to Money(0, total.Currency) if not provided.

PaypalProduct

Represents a single line item in the PayPal order. Property names are serialized as lowercase JSON to match PayPal SDK expectations.

PaypalTransaction

Returned in the OnApproved callback. Contains the computed total and the raw PayPal response.

public class PaypalTransaction
{
    public string Id { get; set; }           // PayPal order ID (or generated fallback)
    public Money Total { get; set; }         // Computed total from purchase units
    public ApproveData TransactionData { get; set; } // Raw PayPal approve data
}

If PayPal does not return a transaction ID, a fallback ID is generated in the format PAYPAL-YYYYMMDD-XXXXXXXX.

Money

A value object representing a monetary amount with currency. Supports arithmetic and comparison operators.

Money price = new Money(49.99m, "USD");
Money tax   = new Money(4.50m, "USD");
Money total = price + tax; // Money(54.49, "USD")

Supported operators: +, -, *, /, %, ++, --, ==, !=, <, >, <=, >=

Implicit cast to decimal:

decimal value = price; // 49.99

Currency conversion (requires ICurrencyConvertion):

Money converted = await price.TotalMoneyToCurrency(conversionService, "EUR");

Arithmetic and comparison operations between Money instances require matching currencies. A mismatch throws InvalidOperationException.

Interfaces

ICurrencyConvertion

Implement this interface to provide currency conversion support for Money.TotalMoneyToCurrency.

public interface ICurrencyConvertion
{
    Task<Money> ConvertToCurrency(Money originCurrency, string destinationCurrency);
    Task<string> GetCurrency();
}

Register your implementation in DI:

builder.Services.AddScoped<ICurrencyConvertion, MyCurrencyService>();

Callbacks

OnApproved

Receives a PaypalTransaction with the computed total across all purchase units. Currencies are validated — if multiple currencies are detected within the same order, only the first currency is used and mismatched values are ignored (a warning is printed to the console).

private async Task HandleApproved(PaypalTransaction transaction)
{
    Console.WriteLine($"Payment approved: {transaction.Id}");
    Console.WriteLine($"Total: {transaction.Total}"); // e.g. "54.49 USD"
}

OnCancel

private async Task HandleCancel()
{
    Console.WriteLine("Payment cancelled by user.");
}

OnTransactionError

private async Task HandleError()
{
    Console.WriteLine("A PayPal error occurred.");
}

Examples

Minimal setup

@code {
    private async Task<CartTotals> GetTotals()
    {
        return new CartTotals(new Money(29.99m, "USD"));
    }

    private async Task<IEnumerable<PaypalProduct>> GetCartProducts()
    {
        return new List<PaypalProduct>
        {
            new PaypalProduct
            {
                Name = "Basic Plan",
                Price = 29.99m,
                Currency = "USD"
            }
        };
    }

    private async Task HandleApproved(PaypalTransaction transaction)
    {
        // Save transaction.Id and transaction.Total to your backend
    }
}

<PaypalButton
    MerchantId="YOUR_PAYPAL_CLIENT_ID"
    CalculateTotalToPay="GetTotals"
    GetProducts="GetCartProducts"
    OnApproved="HandleApproved" />

With full cart breakdown and custom description

<PaypalButton
    MerchantId="YOUR_PAYPAL_CLIENT_ID"
    CalculateTotalToPay="GetTotals"
    GetProducts="GetCartProducts"
    SetDescription="GetDescription"
    EnableDebugMode="true"
    OnApproved="HandleApproved"
    OnCancel="HandleCancel"
    OnTransactionError="HandleError"
    OnLoad="HandleLoad" />

@code {
    private async Task<string> GetDescription() => "My Store - Order #1042";

    private async Task<CartTotals> GetTotals()
    {
        return new CartTotals(
            total:     new Money(113.49m, "USD"),
            discounts: new Money(10.00m,  "USD"),
            shipping:  new Money(5.00m,   "USD"),
            tax:       new Money(8.50m,   "USD"),
            handling:  new Money(0.00m,   "USD"),
            insurance: new Money(0.00m,   "USD")
        );
    }

    private async Task<IEnumerable<PaypalProduct>> GetCartProducts()
    {
        return new List<PaypalProduct>
        {
            new PaypalProduct { Name = "Widget A", Price = 60.00m, Quantity = 1, Currency = "USD" },
            new PaypalProduct { Name = "Widget B", Price = 50.00m, Quantity = 1, Currency = "USD" }
        };
    }

    private async Task HandleApproved(PaypalTransaction t) => Console.WriteLine(t.Id);
    private async Task HandleCancel()                       => Console.WriteLine("Cancelled");
    private async Task HandleError()                        => Console.WriteLine("Error");
    private async Task HandleLoad()                         => Console.WriteLine("Button loaded");
}

License

MIT