GLASS.DotNet.SDK 1.0.0

GLASS DOTNET SDK Implementation guide

This document explains how to install, configure and use the GLASS.DotNet.SDK library from this repository. It covers packaging, local testing, configuration options, public API surface and examples using the implemented classes and services.

Table of contents

• Introduction
• Requirements
• Install (NuGet / Local)
• Configuration (GlassSDKOptions)
• Quick start
• API reference (high level)
  • GlassSDK
  • PaymentService
  • IGlassHttpClient / GlassHttpClient
  • AuthService / authentication behavior
• Models
• Packaging & CI (pack + GitHub Action)
• Local testing / consuming the package
• Error handling & logging
• Contributing
• License

Introduction

GLASS.DotNet.SDK is a small client SDK that wraps PelPay/GLASS payment HTTP endpoints. It provides an opinionated PaymentService and support classes to authenticate and call endpoints.

The implementation in this repository targets .NET 8 and C# 12.

Requirements

• .NET SDK 8.x (check with dotnet --version)
• Internet access for calls to the configured BaseUrl

Install

There are two common ways to use the SDK in your project:

1. Install from nuget.org (when published):

   dotnet add package GLASS.DotNet.SDK --version <version>

2. Install from a local folder feed (during development):

   • Pack the project from the repository root: dotnet pack GLASS_DotNet_SDK/GLASS_DotNet_SDK.csproj -c Release -o ./nupkgs /p:Version=1.0.0
   • In your consumer project: dotnet add package GLASS.DotNet.SDK --version 1.0.0 --source ../nupkgs

Alternative for fast development: use a project reference to the SDK project instead of packing:

dotnet add reference ../GLASS_DotNet_SDK/GLASS_DotNet_SDK.csproj

Configuration (GlassSDKOptions)

Create and configure a GlassSDKOptions instance. Main properties:

• BaseUrl (string) � Base API URL (default https://api.pelpay.ng).
• ClientId (string) � client id used for authentication.
• ClientSecret (string) � client secret used for authentication.
• MerchantId (string) � optional merchant id.
• IntegrationKey (string) � optional integration key used on requests.

Example:

var options = new GlassSDKOptions
{
    BaseUrl = "https://api.pelpay.ng",
    ClientId = "Nai0000319",
    ClientSecret = "your-secret",
    MerchantId = "your-merchant-id",
    IntegrationKey = "your-integration-key"
};

Quick start

Instantiate the SDK and call payment operations:

using GLASS_DotNet_SDK;
using GLASS_DotNet_SDK.Models.Requests;

var options = new GlassSDKOptions { BaseUrl = "https://api.pelpay.ng", ClientId = "...", ClientSecret = "...", IntegrationKey = "..." };
var sdk = new GlassSDK(options);

// Create an advice (payment order)
var adviceRequest = new AdviceRequest
{
    amount = "2000",
    merchantRef = "order-123",
    narration = "Order #123",
    callBackUrl = "https://example.com/callback",
    integrationKey = options.IntegrationKey,
    customer = new Customer
    {
        customerId = "cust-1",
        customerFirstName = "Jane",
        customerLastName = "Doe",
        customerEmail = "jane@example.com",
        customerPhoneNumber = "08012345678"
    }
};

var result = await sdk.Payment.CreateAdviceAsync(adviceRequest);
if (result.requestSuccessful)
{
    var advice = result.responseData;
    string paymentUrl = advice?.paymentUrl;

    // redirect user to the Payment URL to continue payment... or log the advice reference for later retrieval
    Console.WriteLine($"Advice created, reference: {advice?.adviceReference}");
}
else
{
    Console.WriteLine($"CreateAdvice failed: {result.message}");
}

// Retrieve advice or transaction
var adviceResp = await sdk.Payment.GetAdviceAsync("advice-ref-123");
var transaction = await sdk.Payment.GetTransactionByPaymentReference("payment-ref-123");

// Generate client-side payment link
var paymentLink = await sdk.Payment.GetPaymentLinkAsync("advice-ref-123");

API reference (high level)

• GlassSDK � root SDK object. Construct with GlassSDKOptions and access services as properties. Example: var sdk = new GlassSDK(options); then sdk.Payment.

• PaymentService � main service for payments. Public methods:

  • Task<ResponseModel<AdviceResponse>> CreateAdviceAsync(AdviceRequest request) � creates a payment order (advice).
  • Task<ResponseModel<AdviceResponse>> GetAdviceAsync(string adviceReference) � retrieves advice details.
  • Task<ResponseModel<TransactionResponse>> GetTransactionByPaymentReference(string paymentReference)
  • Task<ResponseModel<TransactionResponse>> GetTransactionByAdviceReference(string adviceReference)
  • Task<ResponseModel<TransactionResponse>> GetTransactionByClientReference(string clientReference)
  • Task<string> GetPaymentLinkAsync(string adviceReference) � builds a client-side payment link.

  Each returns a ResponseModel<T> describing success, data and status message.

• IGlassHttpClient � interface for the HTTP client used by services. Methods:

  • Task<HttpResponseMessage> PostAsync<T>(string url, T payload)
  • Task<HttpResponseMessage> GetAsync(string url)

• GlassHttpClient � default implementation. It uses an AuthService to obtain a bearer token and sets Authorization headers for requests.

• AuthService � obtains and caches a token from POST {BaseUrl}/api/Account/login using ClientId/ClientSecret. Token caching uses _expiry set from expires_in returned by the auth response.

Models

Primary request/response models shipped in the SDK:

• AdviceRequest � fields include: amount, currency, merchantRef, narration, callBackUrl, splitCode, shouldTokenizeCard, customer, integrationKey, channels, etc. See Models/Requests/AdviceRequest.cs.

• Customer nested model inside AdviceRequest � customer details such as customerFirstName, customerLastName, customerEmail, customerPhoneNumber.

• PayWithBankTransferRequest � bankCode, adviceReference.

• SimulatePaymentRequest � virtualAccountNumber, amount (useful for testing bank transfer flows).

• AdviceResponse � returned when creating or fetching advice. See Models/Responses/AdviceResponse.cs for fields like adviceReference, paymentUrl, channels, status.

• TransactionResponse � fields for transaction details returned by the transaction endpoints.

• ResponseModel<T> � wrapper used across the service methods with fields: requestSuccessful, responseData, message, responseCode.

Error handling & logging

• The SDK returns ResponseModel<T> when possible. If the HTTP call fails or deserialization fails, a ResponseModel<T> is still returned with requestSuccessful = false and message containing error details or raw body.

• PaymentService accepts an optional ILogger<PaymentService> in its constructor. If you need logging, create a logger and pass it to new PaymentService(...) when constructing services directly. When using GlassSDK (which creates the PaymentService), there is no logger injected by default.

• AuthService.GetTokenAsync throws an exception when authentication fails; the GlassHttpClient does not catch that internally, so callers could see exceptions when auth cannot be obtained.

Packaging & CI

This repository contains a GitHub Actions workflow at .github/workflows/nuget-publish.yml that will pack and push the .nupkg to nuget.org when a git tag matching v*.*.* is pushed. The workflow expects a repository secret named NUGET_API_KEY.

Command-line pack example:

dotnet pack GLASS_DotNet_SDK/GLASS_DotNet_SDK.csproj -c Release -o ./nupkgs /p:Version=1.0.0

To publish from your machine:

dotnet nuget push ./nupkgs/GLASS.DotNet.SDK.1.0.0.nupkg -k <YOUR_KEY> -s https://api.nuget.org/v3/index.json

Local testing / consuming the package

• Pack the SDK and add the ./nupkgs folder as a source in your consumer project (one-shot or persistent). See the "Install" section above for commands.

• Alternatively reference the SDK project directly while developing (faster iteration):

  dotnet add reference ../GLASS_DotNet_SDK/GLASS_DotNet_SDK.csproj

Contributing

• Run tests (if any) in Tests/GLASS_DotNet_SDK.Tests.
• Make small, focused PRs. Ensure API compatibility unless intentionally introducing a breaking change.