Suregifts.MerchantClient.SDK 1.3.0

Suregifts Merchant Client SDK

Official .NET SDK for integrating with the Suregifts Merchant Client API v2. This SDK provides a simple and type-safe way to interact with the Suregifts voucher system.

Features

• ✅ Type-safe request/response models
• ✅ Basic Authentication support
• ✅ Easy configuration via appsettings.json or direct setup
• ✅ Dependency injection support for ASP.NET Core
• ✅ Standalone / console application support
• ✅ Custom HttpClient configuration support
• ✅ Testable via ISuregiftsVoucherClient interface
• ✅ Async/await support
• ✅ Targets net6.0 (minimum .NET 6 LTS)

Installation

dotnet add package Suregifts.MerchantClient.SDK

Install-Package Suregifts.MerchantClient.SDK

Registration & Setup

There are multiple ways to create and register ISuregiftsVoucherClient / SuregiftsVoucherClient depending on your application type.

Authentication: The Suregifts API uses Basic Authentication (Authorization: Basic base64(apiKey:apiSecret)). When using the DI options below, set this on the HttpClient via the configureClient action (Option 3) or DefaultRequestHeaders on your pre-configured client. For standalone usage, see Option 4 for a full example.

Option 1: ASP.NET Core DI — Simple (recommended)

The most common approach. Registers ISuregiftsVoucherClient with a typed HttpClient.

// Program.cs
using Suregifts.MerchantClient.SDK.Extensions;

builder.Services.AddSuregiftsMerchantClient(
    baseUrl: builder.Configuration["Suregifts:BaseUrl"]!,
    timeoutSeconds: 30  // optional, defaults to 30
);

// appsettings.json
{
  "Suregifts": {
    "BaseUrl": "https://onlinemerchants.suregifts.com"
  }
}

Option 1b: ASP.NET Core DI — With Basic Authentication

Use this overload when you need to provide API credentials for basic authentication.

// Program.cs
using Suregifts.MerchantClient.SDK.Extensions;

builder.Services.AddSuregiftsMerchantClient(
    baseUrl: builder.Configuration["Suregifts:BaseUrl"]!,
    apiKey: builder.Configuration["Suregifts:ApiKey"]!,
    apiSecret: builder.Configuration["Suregifts:ApiSecret"]!,
    timeoutSeconds: 30  // optional, defaults to 30
);

// appsettings.json
{
  "Suregifts": {
    "BaseUrl": "https://onlinemerchants.suregifts.com",
    "ApiKey": "your-api-key",
    "ApiSecret": "your-api-secret"
  }
}

Then inject ISuregiftsVoucherClient anywhere:

public class PaymentService(ISuregiftsVoucherClient voucherClient) { }

Option 2: ASP.NET Core DI — With Options Pattern

Bind the dedicated SuregiftsMerchantClientOptions configuration section, then pass values to the registration.

// appsettings.json
{
  "SuregiftsMerchantClient": {
    "BaseUrl": "https://onlinemerchants.suregifts.com",
    "ApiKey": "your-api-key",
    "ApiSecret": "your-api-secret",
    "TimeoutSeconds": 30
  }
}

// Program.cs
using Suregifts.MerchantClient.SDK.Configuration;
using Suregifts.MerchantClient.SDK.Extensions;

var options = builder.Configuration
    .GetSection(SuregiftsMerchantClientOptions.SectionName)
    .Get<SuregiftsMerchantClientOptions>()!;

builder.Services.AddSuregiftsMerchantClient(
    baseUrl: options.BaseUrl,
    apiKey: options.ApiKey,
    apiSecret: options.ApiSecret,
    timeoutSeconds: options.TimeoutSeconds
);

Option 3: ASP.NET Core DI — Custom HttpClient Configuration

Use this overload when you need full control over the HttpClient (e.g. custom headers, base path, message handlers).

// Program.cs
using Suregifts.MerchantClient.SDK.Extensions;

builder.Services.AddSuregiftsMerchantClient(client =>
{
    client.BaseAddress = new Uri("https://onlinemerchants.suregifts.com");
    client.Timeout = TimeSpan.FromSeconds(60);
    client.DefaultRequestHeaders.Add("X-App-Name", "MyApp");
    
    // Basic authentication can also be set manually here
    var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes("your-api-key:your-api-secret"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);
});

Option 4: Standalone / Console Application

No DI container required. Build an HttpClient manually and pass it to SuregiftsVoucherClient directly.

Authentication: The Suregifts API uses Basic Authentication internally. Set the Authorization header on your HttpClient using your API key and secret encoded as base64(apiKey:apiSecret).

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Suregifts.MerchantClient.SDK.Services;

var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes("your-api-key:your-api-secret"));

var httpClient = new HttpClient
{
    BaseAddress = new Uri("https://onlinemerchants.suregifts.com"),
    Timeout = TimeSpan.FromSeconds(30)
};
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", credentials);

ISuregiftsVoucherClient voucherClient = new SuregiftsVoucherClient(httpClient);

var result = await voucherClient.CheckBalance(new CheckBalanceRequest
{
    VoucherCode = "548546765649",
    Pin = "1234"
});

Option 5: Standalone with Pre-configured HttpClient

If you already have a fully configured HttpClient (e.g. from IHttpClientFactory in a non-DI context or tests), pass it directly:

using Suregifts.MerchantClient.SDK.Services;

// httpClient must already have BaseAddress and auth headers configured
ISuregiftsVoucherClient voucherClient = new SuregiftsVoucherClient(httpClient);

Option 6: Using ISuregiftsVoucherClient Without SuregiftsVoucherClient (Testing / Custom Implementation)

ISuregiftsVoucherClient is a plain interface. You can implement it yourself or mock it without ever using SuregiftsVoucherClient. This is the recommended pattern for unit tests and for scenarios where you want a stub/fake implementation.

Custom implementation

using Suregifts.MerchantClient.SDK.Models;
using Suregifts.MerchantClient.SDK.Models.Requests;
using Suregifts.MerchantClient.SDK.Services;

public class FakeVoucherClient : ISuregiftsVoucherClient
{
    public Task<OnlineMerchantResult<CheckBalanceData>> CheckBalance(
        CheckBalanceRequest request, CancellationToken cancellationToken = default)
        => Task.FromResult(new OnlineMerchantResult<CheckBalanceData>
        {
            StatusCode = "00",
            Data = new CheckBalanceData { Balance = 5000m }
        });

    public Task<OnlineMerchantResult<TransactionResult>> RedeemVoucher(
        RedeemVoucherRequest request, CancellationToken cancellationToken = default)
        => Task.FromResult(new OnlineMerchantResult<TransactionResult> { StatusCode = "00" });

    public Task<OnlineMerchantResult<TransactionResult>> VerifyTransaction(
        string reference, CancellationToken cancellationToken = default)
        => Task.FromResult(new OnlineMerchantResult<TransactionResult> { StatusCode = "00" });

    public Task<OnlineMerchantResult<TransactionResult>> ReverseTransaction(
        string reference, CancellationToken cancellationToken = default)
        => Task.FromResult(new OnlineMerchantResult<TransactionResult> { StatusCode = "00" });

    public Task<OnlineMerchantResult<IEnumerable<TransactionResult>>> GetRecentTransactions(
        CancellationToken cancellationToken = default)
        => Task.FromResult(new OnlineMerchantResult<IEnumerable<TransactionResult>>
        {
            StatusCode = "00",
            Data = Enumerable.Empty<TransactionResult>()
        });
}

Register the custom implementation in DI

// Program.cs — no HttpClient needed
builder.Services.AddScoped<ISuregiftsVoucherClient, FakeVoucherClient>();

Mocking with Moq (unit tests)

using Moq;
using Suregifts.MerchantClient.SDK.Services;

var mockClient = new Mock<ISuregiftsVoucherClient>();

mockClient
    .Setup(x => x.CheckBalance(It.IsAny<CheckBalanceRequest>(), It.IsAny<CancellationToken>()))
    .ReturnsAsync(new OnlineMerchantResult<CheckBalanceData>
    {
        StatusCode = "00",
        Data = new CheckBalanceData { Balance = 5000m }
    });

// Inject mockClient.Object wherever ISuregiftsVoucherClient is expected

API Methods

Usage Examples

Check Voucher Balance

var result = await voucherClient.CheckBalance(new CheckBalanceRequest
{
    VoucherCode = "548546765649",
    Pin = "1234"
});

if (result.IsSuccess)
{
    Console.WriteLine($"Balance: {result.Data.Balance:N2}");
    Console.WriteLine($"Usable Amount: {result.Data.UsableAmount:N2}");
    Console.WriteLine($"Serial Number: {result.Data.SerialNumber}");

    foreach (var transaction in result.Data.Transactions)
        Console.WriteLine($"  - {transaction.TransactionType}: {transaction.Amount:N2}");
}
else
{
    Console.WriteLine($"Error: {result.Message} (Code: {result.StatusCode})");
}

Redeem Voucher

var result = await voucherClient.RedeemVoucher(new RedeemVoucherRequest
{
    VoucherCode = "548546765649",
    Pin = "1234",
    Amount = 1000.00m,
    Reference = "TXN-" + Guid.NewGuid()
});

if (result.IsSuccess)
{
    Console.WriteLine($"Transaction ID: {result.Data.TransactionId}");
    Console.WriteLine($"Amount: {result.Data.Amount:N2}");
    Console.WriteLine($"Reference: {result.Data.Reference}");
}

Verify Transaction

var result = await voucherClient.VerifyTransaction("TXN-12345");

if (result.IsSuccess)
{
    Console.WriteLine($"Type: {result.Data.TransactionType}");
    Console.WriteLine($"Amount: {result.Data.Amount:N2}");
    Console.WriteLine($"Date: {result.Data.Timestamp}");
}

Reverse Transaction

var result = await voucherClient.ReverseTransaction("TXN-12345");

if (result.IsSuccess)
{
    Console.WriteLine($"Reversal ID: {result.Data.TransactionId}");
    Console.WriteLine($"Refund Status: {result.Data.RefundStatus}");
}

Get Recent Transactions

var result = await voucherClient.GetRecentTransactions();

if (result.IsSuccess)
{
    foreach (var tx in result.Data.Take(10))
    {
        Console.WriteLine($"{tx.TransactionType}: {tx.Amount:N2} — {tx.Reference}");
    }
}

Error Handling

try
{
    var result = await _voucherClient.RedeemVoucher(request);

    if (result.IsSuccess)
    {
        // success path
    }
    else
    {
        switch (result.StatusCode)
        {
            case "30": /* Insufficient balance */ break;
            case "40": /* Duplicate reference */ break;
            case "50": /* Invalid voucher */ break;
            default:
                Console.WriteLine($"Error: {result.Message} (Code: {result.StatusCode})");
                break;
        }
    }
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
}
catch (TaskCanceledException ex)
{
    Console.WriteLine($"Request timeout: {ex.Message}");
}

API Response Status Codes

Models

Request Models

Response Models

Configuration Model

Properties: BaseUrl, ApiKey, ApiSecret, TimeoutSeconds (default: 30)

Best Practices

1. Use unique references — Always generate a unique Reference per redemption to avoid 40 duplicate errors.

   Reference = "TXN-" + Guid.NewGuid()
   

2. Prefer ISuregiftsVoucherClient over SuregiftsVoucherClient in your own classes to keep them testable and decoupled from the HTTP implementation.

3. Use the DI overloads for ASP.NET Core apps — they manage HttpClient lifetime correctly via IHttpClientFactory.

4. Set a suitable timeout — The default is 30 seconds. Adjust for your network conditions via timeoutSeconds or the options model.

Building and Publishing

dotnet build -c Release
dotnet pack -c Release
dotnet nuget push bin/Release/Suregifts.MerchantClient.SDK.1.1.0.nupkg \
    --api-key YOUR_NUGET_API_KEY \
    --source https://api.nuget.org/v3/index.json

Support

For API documentation and support, contact the Suregifts support team.

License

Copyright © Suregifts. All rights reserved.