Paystack.SDK 1.1.1

Paystack.SDK

A .NET class library for the Paystack API with a result-based error model, automatic amount-to-subunit conversion, built-in fee absorption, and ready-made ASP.NET Core DI registration. Covers the Transaction, Charge (direct mobile money/OTP/PIN), Settlement, and Subaccount resources. Targets .NET 8 and .NET 10.

Installation

dotnet add package Paystack.SDK

Configuration

Add your Paystack secret key to appsettings.json:

"Paystack": {
  "SecretKey": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Get your secret key from the Paystack dashboard. Use sk_test_... during development.

Registration

// Program.cs
builder.Services.AddPaystackSdk(config =>
{
    config.SecretKey = builder.Configuration["Paystack:SecretKey"]!;
});

With a custom base URL (rarely needed — defaults to https://api.paystack.co):

builder.Services.AddPaystackSdk(config =>
{
    config.SecretKey = "sk_live_...";
    config.BaseUrl = "https://api.paystack.co";
});

This registers the following as scoped services:

• IPaystackTransactionService
• IPaystackChargeService
• IPaystackSettlementService
• IPaystackSubaccountService

Usage

Every method returns a PaystackResult<T> — no exceptions are thrown for API errors. Check IsSuccess before using Data.

Initialize a transaction (redirect checkout)

public class CheckoutService(IPaystackTransactionService transactions)
{
    public async Task<string?> StartCheckoutAsync(string email, decimal amount)
    {
        var result = await transactions.InitializeAsync(new InitializeTransactionRequest(
            Email: email,
            Amount: amount,
            CallbackUrl: "https://myapp.com/payment/callback"
        ));

        if (!result.IsSuccess)
        {
            // result.Message contains the Paystack error message
            return null;
        }

        // Redirect the user here to complete payment
        return result.Data!.AuthorizationUrl;
    }
}

Verify a transaction after callback

using Paystack.SDK.Transactions.Extensions;

var result = await transactions.VerifyAsync(reference);

if (result.IsVerifiedSuccess())
{
    // Payment confirmed — fulfill the order
}

IsVerifiedSuccess() combines the API-level and transaction-level checks: the call must have succeeded and Paystack must report the transaction as success. A parallel IsChargeSuccess() exists in Paystack.SDK.Charge.Extensions for mobile money / direct charges.

Charge mobile money directly (Ghana)

public class MobileMoneyService(IPaystackChargeService charge)
{
    public async Task PayWithMomoAsync(string email, decimal amount, string phone)
    {
        var result = await charge.ChargeMobileMoneyAsync(new MobileMoneyChargeRequest(
            Email: email,
            Amount: amount,
            Phone: phone,
            Network: charge.GetNetworkProvider(phone)!   // auto-detect mtn | vod | atl
        ));

        if (!result.IsSuccess) return;

        var status = result.Data!.Data?.Status;

        // status = "send_otp"      → prompt user, call SubmitOtpAsync
        // status = "send_birthday" → prompt user, call SubmitBirthdayAsync
        // status = "pending"       → call PollUntilCompleteAsync
        // status = "success"       → charge completed
    }
}

List transactions with pagination

var result = await transactions.ListAsync(new ListTransactionsRequest(
    PerPage: 50,
    Page: 1,
    Status: "success"
));

if (result.IsSuccess)
{
    foreach (var tx in result.Data!.Items) { /* ... */ }

    var meta = result.Data.Meta;
    // meta.Total, meta.Page, meta.PerPage, meta.PageCount
}

Poll until a pending charge completes

var final = await charge.PollUntilCompleteAsync(
    reference: "abc123",
    maxAttempts: 20,
    intervalSeconds: 5,
    ct: cancellationToken
);

Fee absorption

Customers can absorb the Paystack processing fee so the merchant receives exactly the intended amount. Use PaystackFeeCalculator to show the fee up-front, or set AbsorbFee: true on any request to apply the gross-up automatically.

Show the fee before checkout

decimal fee = PaystackFeeCalculator.FeeOnly(100m);
// fee → 1.99  (1.95% of 101.99)

var breakdown = PaystackFeeCalculator.GrossUp(100m);
// breakdown.OriginalAmount → 100.00   (merchant receives)
// breakdown.FeeAmount      → 1.99     (customer absorbs)
// breakdown.TotalCharged   → 101.99   (passed to Paystack)

Apply the fee automatically

await transactions.InitializeAsync(new InitializeTransactionRequest(
    Email: email,
    Amount: 100m,
    AbsorbFee: true           // Paystack gets 101.99, merchant receives 100
));

Custom fee rate (e.g. international cards at 3.9%)

await transactions.InitializeAsync(new InitializeTransactionRequest(
    Email: email,
    Amount: 100m,
    AbsorbFee: true,
    FeeRate: 0.039m
));

The AbsorbFee flag is available on InitializeTransactionRequest, ChargeAuthorizationRequest, and MobileMoneyChargeRequest.

Transaction splits

Paystack supports two ways to split a single payment between your main account and a subaccount. Which one runs is decided by which fields you send on InitializeAsync / ChargeAuthorizationAsync — there is no separate endpoint.

Mode 1 — Flat split (pre-configured, reusable)

Create a split once via Paystack's dashboard or /split endpoint. You get back a split_code like SPL_xxx. On every transaction just pass the code:

await transactions.InitializeAsync(new InitializeTransactionRequest(
    Email: email,
    Amount: 100m,
    SplitCode: "SPL_xxx"            // Paystack applies the saved rules
));

Bearer and TransactionCharge are ignored when SplitCode is set.

Mode 2 — Dynamic split (per-transaction)

No pre-created split. Define the split inline with the Subaccount of the party to pay, optional Bearer (who pays the Paystack fee), and optional TransactionCharge (a flat fee the subaccount owes on this transaction):

await transactions.InitializeAsync(new InitializeTransactionRequest(
    Email: email,
    Amount: 100m,
    Subaccount: "ACCT_xxx",         // party to split to
    Bearer: "subaccount",           // "account" (you) or "subaccount" — optional
    TransactionCharge: 2.00m        // major units (GHS/NGN), converted to subunits — optional
));

Paystack picks the mode by presence of fields: SplitCode → Mode 1 · Subaccount without SplitCode → Mode 2 · neither → normal transaction.

The same four fields — SplitCode, Subaccount, Bearer, TransactionCharge — are also accepted on ChargeAuthorizationRequest.

Webhook verification

Paystack signs every webhook body with HMAC-SHA512 using your secret key and sends the hex digest in the x-paystack-signature header. Use PaystackWebhook.IsValid to verify it before trusting the payload.

using Paystack.SDK.Webhooks;

app.MapPost("/webhooks/paystack", async (HttpRequest req, IConfiguration config) =>
{
    using var reader = new StreamReader(req.Body);
    var rawBody = await reader.ReadToEndAsync();
    var signature = req.Headers[PaystackWebhook.SignatureHeader].ToString();
    var secretKey = config["Paystack:SecretKey"]!;

    if (!PaystackWebhook.IsValid(rawBody, signature, secretKey))
        return Results.Unauthorized();

    // Signature valid — safe to deserialize and handle the event
    return Results.Ok();
});

Important: verify against the raw request body bytes. Any re-serialization, reformatting, or model-binding before verification will break the signature.

API Reference

IPaystackTransactionService

IPaystackChargeService

IPaystackSettlementService

IPaystackSubaccountService

PaystackWebhook

PaystackFeeCalculator

PaystackResult<T>

PagedResult<T>

PaystackConfig

Defaults & behaviour

Supported networks (Ghana mobile money)

Use IPaystackChargeService.DetectMobileNetwork(phone) to auto-detect from a phone number (with or without +233 country code).

Requirements

• .NET 8 or .NET 10
• A Paystack account with API keys enabled