Skip to Content
SDKsNexus SDK (Cloud Integration).NET (C#)

.NET SDK (C#)

GitHub Repository: sunbay-nexus-sdk-net 

Official SUNBAY Nexus .NET SDK, providing complete payment integration capabilities for .NET applications.

Features

  • ✅ Multi-target: .NET Standard 2.0 / .NET 6.0 / .NET 8.0
  • ✅ Complete async API
  • ✅ Strong type definitions
  • ✅ Automatic authentication
  • ✅ Automatic retry for GET requests
  • ✅ Comprehensive exception handling
  • ✅ Connection pool management (SocketsHttpHandler on .NET 6+)
  • ✅ Integration with Microsoft.Extensions.Logging

Installation

Install-Package Sunbay.Nexus.Sdk

Quick Start

NexusClient uses an internal HTTP connection pool. Create it once and reuse it globally — do not create a new instance for every request. The client implements IAsyncDisposable; call DisposeAsync() on application shutdown.

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Sunbay.Nexus.Sdk;
using Sunbay.Nexus.Sdk.Models.Requests;
using Sunbay.Nexus.Sdk.Models.Common;
using Sunbay.Nexus.Sdk.Exceptions;
 
class Program
{
    static async Task Main(string[] args)
    {
        var apiKey = Environment.GetEnvironmentVariable("SUNBAY_API_KEY")
            ?? throw new InvalidOperationException("SUNBAY_API_KEY environment variable is required");
 
        // Optional: configure logging
        using var loggerFactory = LoggerFactory.Create(builder =>
            builder.AddConsole().SetMinimumLevel(LogLevel.Information));
 
        // Create client once, reuse globally
        var client = new NexusClient(new NexusClientOptions
        {
            ApiKey = apiKey,
            BaseUrl = "https://open.sunbay.us"
        }, loggerFactory);
 
        try
        {
            var request = new SaleRequest
            {
                AppId = "app_123456",
                MerchantId = "mch_789012",
                ReferenceOrderId = $"ORDER{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}",
                TransactionRequestId = Guid.NewGuid().ToString("N"),
                Amount = new SaleAmount
                {
                    OrderAmount = 10000L, // 100.00 USD, in cents
                    PriceCurrency = "USD"
                },
                Description = "Product purchase",
                TerminalSn = "T1234567890"
            };
 
            var response = await client.SaleAsync(request);
            Console.WriteLine($"Transaction ID: {response.TransactionId}");
        }
        catch (SunbayNetworkException ex)
        {
            Console.WriteLine($"Network error: {ex.Message}, Retryable: {ex.IsRetryable}");
        }
        catch (SunbayBusinessException ex)
        {
            Console.WriteLine($"API error: {ex.Code} - {ex.Message}, TraceId: {ex.TraceId}");
        }
        finally
        {
            await client.DisposeAsync();
        }
    }
}

API Methods

All methods are async and accept an optional CancellationToken. All return Task<*Response>.

In-Person Payment APIs

  • SaleAsync(request) - Payment transaction
  • AuthAsync(request) - Pre-authorization
  • ForcedAuthAsync(request) - Forced authorization
  • IncrementalAuthAsync(request) - Incremental authorization
  • PostAuthAsync(request) - Post-authorization completion
  • RefundAsync(request) - Refund
  • VoidAsync(request) - Void transaction
  • AbortAsync(request) - Abort transaction
  • TipAdjustAsync(request) - Tip adjustment
  • BatchQueryAsync(request) - Query open (unsettled) batches
  • BatchCloseAsync(request) - Batch settlement
  • BatchCloseListAsync(request) - Query closed (settled) batches

Online Payment APIs

  • CreateCheckoutSessionAsync(request) - Create hosted checkout session
  • ExpireCheckoutSessionAsync(request) - Expire a checkout session
  • DirectPaymentAsync(request) - Direct payment (server-to-server)
  • OnlineRefundAsync(request) - Online refund

Transaction Query APIs

  • QueryAsync(request) - Query transaction

Merchant APIs

  • MerchantQueryAsync(request) - Retrieve merchant information
  • MerchantTerminalsQueryAsync(request) - List terminals bound to a merchant

Configuration Options

var client = new NexusClient(new NexusClientOptions
{
    ApiKey = "sk_test_xxx",                                  // Required
    BaseUrl = "https://open.sunbay.us",                      // Default: https://open.sunbay.us
    Timeout = TimeSpan.FromSeconds(30),                      // Default: 30 seconds
    ConnectTimeout = TimeSpan.FromSeconds(10),               // Default: 10 seconds (.NET 6+ only)
    MaxRetries = 3,                                          // Default: 3 times (GET request retry)
    MaxTotalConnections = 200,                               // Default: 200
    MaxConnectionsPerEndpoint = 200,                         // Default: 200
    PooledConnectionLifetime = TimeSpan.FromMinutes(5),      // Default: 5 minutes (.NET 6+ only)
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(2),   // Default: 2 minutes (.NET 6+ only)
});

ConnectTimeout, PooledConnectionLifetime, and PooledConnectionIdleTimeout only take effect on .NET 6+ (SocketsHttpHandler). On .NET Standard 2.0, only Timeout and MaxConnectionsPerEndpoint apply.

Exception Handling

The SDK has three exception types, all inheriting from SunbayException:

  • SunbayBusinessException: Business logic errors (API returns non-zero code). Properties: Code, Message, TraceId
  • SunbayNetworkException: Network errors (timeout, connection failure). Properties: Message, IsRetryable
using Sunbay.Nexus.Sdk.Exceptions;
 
try
{
    var response = await client.SaleAsync(request);
}
catch (SunbayNetworkException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
    if (ex.IsRetryable) { /* Can retry */ }
}
catch (SunbayBusinessException ex)
{
    Console.WriteLine($"API error: {ex.Code} - {ex.Message}");
    if (!string.IsNullOrEmpty(ex.TraceId))
        Console.WriteLine($"Trace ID: {ex.TraceId}");
}

Enums

Available in Sunbay.Nexus.Sdk.Enums:

  • TransactionStatus - Initial (I), Processing (P), Success (S), Fail (F), Closed (C)
  • TransactionType - Sale, Auth, ForcedAuth, Incremental, PostAuth, Refund, Void
  • CardNetworkType - Credit, Debit, Ebt, Egc, Unknown
  • EntryMode - Manual, Swipe, FallbackSwipe, Contact, Contactless
  • AuthenticationMethod - NotAuthenticated, Pin, OfflinePin, ByPass, Signature
  • PaymentCategory - Card, CardCredit, CardDebit, QrMpm, QrCpm
  • PrintReceiptOption - None, Merchant, Customer, Both
  • BatchClosePrintReceiptOption - Total, Detail, Both, None, Auto
  • OnlineCheckoutPaymentMethod - GooglePay, ApplePay
  • PaymentMethodSubId - Snap, Voucher, Benefit
  • RelatedTransactionStatus - Voided, Incremental, Refunded, Capture, PartRefunded
  • TransactionBatchStatus - N, U, C

Logging

The SDK uses Microsoft.Extensions.Logging. Pass an ILoggerFactory to enable logging:

// Standalone
using var loggerFactory = LoggerFactory.Create(builder =>
    builder.AddConsole().SetMinimumLevel(LogLevel.Debug));
var client = new NexusClient(options, loggerFactory);
 
// ASP.NET Core DI
services.AddSingleton<NexusClient>(sp =>
    new NexusClient(new NexusClientOptions { ApiKey = "..." },
        sp.GetRequiredService<ILoggerFactory>()));

Without ILoggerFactory, logging is disabled.

System Requirements

  • .NET Standard 2.0 / .NET 6.0 / .NET 8.0
  • Microsoft.Extensions.Logging.Abstractions 8.0.0
  • Microsoft.Extensions.Http 8.0.0

License

MIT License

Last updated on
GoPython