VantagePay SDK for .NET

VantagePay.SDK is the official C# client SDK for integrating with VantagePay APIs.

It provides:

• typed API clients backed by VantagePay.Models
• automatic token refresh for authenticated calls
• automatic HTTP retries for transient failures
• real-time payment and broadcast updates via SignalR

The TypeScript SDK on NPM covers client capabilities only. This .NET SDK includes both client and admin capabilities.

---

Table of Contents

• Installation
• Supported Frameworks
• Client Types
• Basic Usage
• Configuration and Construction
• Authentication and Tokens
• Error Handling
• Public API Surface
• Payments and Signals
• Server-side Admin Usage
• Migration Guide

---

Installation

dotnet add package VantagePay.SDK

Or with NuGet Package Manager Console:

Install-Package VantagePay.SDK

---

Supported Frameworks

VantagePay.SDK currently targets:

• .NET 8 (net8.0)
• .NET 9 (net9.0)
• .NET 10 (net10.0)

---

Client Types

Use the client that matches your integration model:

Client	Intended use	Authentication model
VantagePayClient	Client-facing integrations (web/mobile apps, POS apps, merchant/consumer flows)	Access/refresh token session (LoginAsync)
VantagePayAdminClient	Trusted server-side admin integrations	API key (apiKey)

---

Basic Usage

VantagePayClient (client-facing)

using VantagePay.SDK;
using VantagePay.Models.Lookups;

var client = new VantagePayClient("https://sandbox-api.vantagepay.dev");

await client.Authentication.LoginAsync("233548306110", "Password123!");

var currencies = await client.Lookups.GetCurrenciesAsync();

var summary = await client.Reports.GetTransactionSummaryAsync(Currency.GHS);

VantagePayAdminClient (server-side)

using VantagePay.SDK;

var adminClient = new VantagePayAdminClient(
    "https://sandbox-api.vantagepay.dev",
    apiKey: "your-admin-api-key");

var userReference = await adminClient.Users.CreateUserAsync("partner.user", "StrongPassword123!");

---

Configuration and Construction

Constructors

VantagePayClient:

• new VantagePayClient(environmentUrl)
• new VantagePayClient(environmentUrl, loggerFactory)
• new VantagePayClient(environmentUrl, accessToken, refreshToken)
• new VantagePayClient(environmentUrl, accessToken, refreshToken, loggerFactory)

VantagePayAdminClient:

• new VantagePayAdminClient(environmentUrl, apiKey)
• new VantagePayAdminClient(environmentUrl, apiKey, loggerFactory)

Logging

Pass an ILoggerFactory to integrate SDK logs into your logging pipeline.

using Microsoft.Extensions.Logging;
using VantagePay.SDK;

using var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());

var client = new VantagePayClient(
    "https://sandbox-api.vantagepay.dev",
    accessToken: null,
    refreshToken: null,
    loggerFactory: loggerFactory);

Retry and refresh behavior

• HTTP retries are automatic for transient failures.
• access tokens are refreshed automatically when possible using the current refreshToken.
• SignalR hubs are configured with automatic reconnect.

---

Authentication and Tokens

Login and token storage

var token = await client.Authentication.LoginAsync("233548306110", "Password123!");

// Tokens are persisted in-memory on the client instance.
string? accessToken = client.ApiTokens.AccessToken;
string? refreshToken = client.ApiTokens.RefreshToken;

Restore existing tokens

var client = new VantagePayClient(
    "https://sandbox-api.vantagepay.dev",
    accessToken: storedAccessToken,
    refreshToken: storedRefreshToken);

Session helpers

bool loggedIn = client.Authentication.IsLoggedIn();
await client.Authentication.RefreshAsync();
await client.Authentication.LogoutAsync();

Token claim helpers

var userReference = client.Authentication.GetCurrentUserReference();
var merchantReference = client.Authentication.GetCurrentMerchantReference();
var consumerReference = client.Authentication.GetCurrentConsumerReference();
var terminalReference = client.Authentication.GetCurrentTerminalReference();
var emailAddress = client.Authentication.GetCurrentEmailAddress();

---

Error Handling

SDK operations throw ApiException derivatives for API failures.

Primary exception types:

• ApiValidationException (400)
• ApiAuthorizationException (401)
• ApiForbiddenException (403)
• ApiNotFoundException (404)
• ApiException (other status codes)

using VantagePay.SDK.Exceptions;

try
{
    await client.Authentication.LoginAsync("user", "wrong-password");
}
catch (ApiAuthorizationException ex)
{
    Console.WriteLine($"Unauthorized ({ex.StatusCode}): {ex.Message}");

    if (ex.ErrorResponse?.MustChangePassword == true)
    {
        await client.Authentication.ChangePasswordAsync("OldPassword", "NewPassword123!");
    }

    if (ex.ErrorResponse?.MustValidatePhoneNumber == true ||
        ex.ErrorResponse?.MustValidateEmailAddress == true)
    {
        await client.Authentication.ResendOtpAsync();
        await client.Authentication.ValidateOtpAsync("123456");
    }
}
catch (ApiValidationException ex)
{
    Console.WriteLine($"Validation error ({ex.StatusCode}): {ex.Message}");
}
catch (ApiException ex)
{
    Console.WriteLine($"API error ({ex.StatusCode}): {ex.Message}");
    throw;
}

Note:

• many Get* methods return null when an entity is not found.
• CancellationToken is supported across all async methods.

---

Public API Surface

VantagePayClient modules

Module	Purpose
Authentication	Login/logout, refresh, OTP, password, face/liveness checks
Lookups	Countries, currencies, languages, banks, wallet operators, categories, product types, address resolution
Consumers	Consumer profile operations, files, limits, debit orders, broadcast listener
Merchants	Merchant profile operations, OTP verify, terminal setup/config, QR code retrieval, telemetry, broadcast listener
Products	Global product catalog browsing and merchant product management, broadcast listener
Payments	Payment and refund workflows, tokenization, status monitoring, interactive payment signals
Notifications	In-app message retrieval and lifecycle
QrCodes	Dynamic QR generation and QR validation
Reports	Recent transactions, summaries, daily and detailed transaction reporting
System	Health ping

Example API calls

// Lookups
var banks = await client.Lookups.GetBanksAsync();

// Consumer profile
var consumer = await client.Consumers.GetConsumerAsync();

// Merchant profile
var merchant = await client.Merchants.GetMerchantAsync();

// Products
var productTypes = await client.Products.GetActiveProductTypesAsync();

// Notifications
var messages = await client.Notifications.GetMessagesAsync();

// Reports
var recent = await client.Reports.GetRecentTransactionsAsync(limit: 10, successfulOnly: true);

// Health
bool isOnline = await client.System.PingAsync();

---

Payments and Signals

Payments supports both request/response and event-driven processing.

Basic payment submission

using System.Collections.Generic;
using VantagePay.Models.Lookups;
using VantagePay.Models.Payments;
using VantagePay.Models.Payments.Requests;

var payment = new PaymentRequest
{
    YourReference = "ORDER-1001",
    PaymentSources = new PaymentSources
    {
        MobileWallets = new List<MobileWalletSource>
        {
            new MobileWalletSource
            {
                MobileWalletOperator = MobileWalletOperator.MTN,
                Msisdn = "233555666112",
                AmountInCents = 5000,
                Currency = Currency.GHS,
            }
        }
    },
    PaymentDestinations = new PaymentDestinations
    {
        Merchants = new List<MerchantDestination>
        {
            new MerchantDestination
            {
                MerchantReference = "merchant-reference",
                AmountInCents = 5000,
                Currency = Currency.GHS,
                PaymentType = MerchantPaymentType.BuyingGoods,
            }
        }
    }
};

var initialStatus = await client.Payments.PayAsync(payment);

Subscribing to payment signals

using VantagePay.Models.Lookups;
using VantagePay.Models.Common;

client.Payments.OnPaymentStatusUpdate = status =>
{
    Console.WriteLine($"{status.PaymentReference}: {status.PercentageComplete}%");
};

client.Payments.OnPaymentComplete = status =>
{
    Console.WriteLine($"Payment complete: {status.PaymentReference}");
};

client.Payments.OnRequiresPin = data =>
{
    var pin = "1234";
    _ = client.Payments.SubmitPinCodeAsync(data.TransactionReference, pin);
};

client.Payments.OnRequiresConfirmation = data =>
{
    _ = client.Payments.SubmitConfirmationAsync(data.TransactionReference, confirm: true);
};

client.Payments.OnRequiresAddress = data =>
{
    var address = new Address
    {
        AddressType = AddressType.Billing,
        AddressLine1 = "10 Main Road",
        City = "Johannesburg",
        CountryIsoCode = Country.ZAF,
        PostalCode = "2196",
    };

    _ = client.Payments.SubmitAddressAsync(data.TransactionReference, address);
};

client.Payments.OnRequires3DSecure = data =>
{
    Console.WriteLine($"Open 3DS URL: {data.ThreeDSecureUrl}");
};

client.Payments.OnComplete3DSecure = () =>
{
    Console.WriteLine("3DS flow completed");
};

Waiting for completion

var finalStatus = await client.Payments.WaitForPaymentCompleteAsync();

Consumer, merchant, and product broadcast signals

client.Consumers.OnConsumerUpdate = () =>
{
    Console.WriteLine("Consumer profile updated");
};

client.Merchants.OnMerchantUpdate = () =>
{
    Console.WriteLine("Merchant profile updated");
};

client.Products.OnProductUpdate = () =>
{
    Console.WriteLine("Product catalog updated");
};

await client.Consumers.StartConsumerBroadcastListenerAsync();
await client.Merchants.StartMerchantBroadcastListenerAsync();
await client.Products.StartProductBroadcastListenerAsync();

Manual status-check control

await client.Payments.StartPaymentStatusCheckingAsync(); // listen for external incoming payment

await client.Payments.StopPaymentStatusCheckingAsync();  // stop all

Tokenization and receipts

using VantagePay.Models.Lookups;
using VantagePay.Models.Tokens;

var cardToken = await client.Payments.CreateCardTokenAsync(new CardRequest
{
    CardNumber = "4111111111111111",
    NameOnCard = "Jane Doe",
    ExpiryMonth = Month.March,
    ExpiryYear = 2027,
});

if (cardToken?.Token is not null)
{
    await client.Payments.ActivateCardTokenAsync(cardToken.Token);
}

var receipt = await client.Payments.GetPaymentReceiptAsync(paymentReference);
await client.Payments.SendEmailNotificationAsync(paymentReference.ToString(), "customer@example.com");

---

Server-side Admin Usage

Use VantagePayAdminClient with API key authorization for administrative workflows.

Admin modules

Module	Purpose
Authentication	Generate consumer/merchant tokens, reset passwords, OTP send/validate, lock/unlock/logout user
Consumers	Manage consumers, files, and KYC state
Merchants	Manage merchants, files, KYB state, business hierarchy, device lookup
Notifications	Manage templates and send targeted merchant/consumer in-app messages
Products	Assignable products, merchant product management, apply product catalogs
Payments	Admin payment/refund initiation and status/receipt operations (IPaymentsAdminApi)
Users	Create and deactivate users

Admin examples

// Generate a merchant-scoped token pair from the server side.
var merchantToken = await adminClient.Authentication.GenerateMerchantTokenAsync(merchantReference);

// Reset a user password.
await adminClient.Authentication.ResetPasswordAsync("partner.user", "NewStrongPassword123!");

// Create a targeted merchant message.
using VantagePay.Models.Notifications;
using VantagePay.Models.Notifications.Requests;

await adminClient.Notifications.CreateMerchantMessageAsync(
    new CreateMessageRequest
    {
        MessageType = MessageType.Information,
        MessageTarget = MessageTarget.Portal,
        MessagePlacement = MessagePlacement.Dashboard,
        Header = "Planned Maintenance",
        Body = "Service window starts at 22:00 UTC.",
        VisibleUntilDate = DateTimeOffset.UtcNow.AddDays(7),
    },
    merchantReference);

---

Migration Guide

If migrating from ZGA.Core.Web.Api.Client, apply these namespace/package updates:

• replace ZGA.Core.Web.Api.Client with VantagePay.SDK
• replace ZGA.Core.Models with VantagePay.Models