FirstChekout 1.0.1

FirstChekout SDK for .NET

The FirstChekout SDK simplifies the integration of FirstBank's payment gateway into .NET applications. It provides a strongly-typed, dependency-injection-friendly wrapper around the FirstChekout APIs, including Token Generation, Card Payments, USSD, and Pay With Transfer features.

Features

• Standardized Configuration: Easy setup using appsettings.json or code-based configuration.
• Dependency Injection: Seamless integration with .NET generic host and DI container.
• Environment Switching: Built-in support for Sandbox and Production environments.
• Strongly Typed Models: Request and Response models aligned with the API specifications.
• Security: Helper service for AES-GCM encryption of sensitive card data.
• Automated Transaction Creation: "Composite Initiation" automatically creates transactions if a reference is not provided, simplifying the flow.
• Async/Await: Fully asynchronous API calls.

Supported Payment Methods

Note: The currently available payment options for this SDK are Card, PayWithAccount, and USSD.

Coming Soon: QR, BNPL, and PayWithPhone.

Installation

To install the lastest version of the SDK, run the following command in your project directory:

dotnet add package FirstChekout 

To install a specific version of the SDK, run the following command in your project directory:

dotnet add package FirstChekout --version 1.0.0

Or via the Package Manager Console:

Install-Package FirstChekout -Version 1.0.0

Getting Started

1. Configuration

Add the following configuration section to your appsettings.json:

{
  "FirstChekout": {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "MerchantId": "your-merchant-id",
    "MerchantPublicKey": "your-public-key",
    "MerchantSecretKey": "your-secret-key",
    "MerchantAesKey": "your-aes-key",
    "CacheTokenExpirationTimeInSeconds" : 300,
    "Environment": "Sandbox" 
  }
}

Configuration Details

Note: For Production, change "Environment" to "Production".

2. Dependency Injection Registration

In your Program.cs or Startup.cs, register the SDK services:

using FirstChekout.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Option A: Configuration via appsettings.json
builder.Services.AddFirstChekout(options => 
    builder.Configuration.GetSection("FirstChekout").Bind(options));

// Option B: Manual Code-Based Configuration
builder.Services.AddFirstChekout(options =>
{
    options.Environment = FirstChekout.Options.FirstChekoutEnvironment.Sandbox;
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.MerchantId = "your-merchant-id";
    options.MerchantPublicKey = "your-public-key";
    options.MerchantSecretKey = "your-secret-key";
    options.MerchantAesKey = "your-aes-key";
    options.CacheTokenExpirationTimeInSeconds = 300;
});

3. Usage

Inject the required service interface into your controllers or business logic.

Note: The SDK automatically handles several complex flows to simplify integration:

• Authentication: Automatically manages OAuth 2.0 token retrieval, caching, and renewal. You do not need to manually generate tokens.
• Encryption: Automatically handles AES-GCM encryption for sensitive card data before sending it to the gateway.
• Transaction Initiation: Automatically creates a new transaction tied to the payment Option on Initiating a new Payment request and returns the Transaction Reference.

Card Payments (Initiate → Complete)

1. Initiate: Call InitiateAsync with card details. The SDK handles encryption.
2. Complete: If the response is successful, call CompleteAsync with the OTP (if required).

public async Task<IActionResult> PayWithCard(ICardPaymentService cardService, PaymentRequestModel model)
{
    // 1. Initiate Payment
    var initRequest = new CardInitiateRequest
    {
        Amount = model.Amount,
        CustomerEmail = model.Email,
        CustomerName = model.Name,
        PaymentReference = model.PaymentReference,
        Description = "Payment for Items",
        CallbackUrl = "https://your-app.com/callback",
        CardNumber = model.CardNumber,
        ExpiryDate = model.ExpiryDate,
        Cvv = model.Cvv,
        Pin = model.Pin
    };

    var initResponse = await cardService.InitiateAsync(initRequest);

    if (!initResponse.IsSuccess)
        return BadRequest(initResponse.Error);

    // 2. Complete Payment (e.g., after user enters OTP)
    var completeRequest = new CardCompleteRequest
    {
        TransactionReference = initResponse.Data.TransactionReference,
        Otp = "123456" // Collected from user
    };

    var completeResponse = await cardService.CompleteAsync(completeRequest);
    
    return Ok(completeResponse.Data);
}

USSD Payments (Get Institutions → Initiate → Query)

1. Get Institutions: Retrieve the list of banks to get the FinancialInstitutionId.
2. Initiate: Call InitiateAsync with the selected bank ID.
3. Query: After the user dials the USSD code and pays, call QueryTransactionAsync to confirm status.

public async Task<IActionResult> PayWithUssd(IUssdService ussdService)
{
    // 1. Get Financial Institutions
    var banksResponse = await ussdService.GetFinancialInstitutionsAsync();
    var bankId = banksResponse.Data.First(b => b.Name == "First Bank").Id;

    // 2. Initiate USSD
    var initRequest = new UssdInitiateRequest
    {
         Amount = 1000,
         CustomerEmail = "user@example.com",
         FinancialInstitutionId = bankId
    };

    var initResponse = await ussdService.InitiateAsync(initRequest);
    var ussdCode = initResponse.Data.UssdCode;
    var txRef = initResponse.Data.TransactionReference;

    // 3. Query Status (Poll or Webhook)
    var statusResponse = await ussdService.QueryTransactionAsync(txRef);
    // Check statusResponse.Data for success
}

Pay With Transfer (Initiate → Complete)

1. Initiate: Call InitiateAsync to get the virtual account details.
2. Complete: After user transfers money, call CompleteAsync to verify.

public async Task<IActionResult> PayWithTransfer(IPayWithTransferService pwtService)
{
    // 1. Initiate
    var initRequest = new PayWithTransferInitiateRequest
    {
        Amount = 5000,
        CustomerEmail = "user@example.com",
        Description = "Wallet Topup"
    };
    
    var initResponse = await pwtService.InitiateAsync(initRequest);
    
    // 2. Complete
    var completeRequest = new PayWithTransferCompleteRequest
    {
        UniqueReference = initResponse.Data.UniqueReference,
        VirtualAccountNo = initResponse.Data.AccountDetails.VirtualAccountNo,
        VirtualAccountToken = initResponse.Data.AccountDetails.VirtualAccountToken
    };

    var completeResponse = await pwtService.CompleteAsync(completeRequest);
}

Transaction Querying

public async Task<IActionResult> CheckStatus(ITransactionService transactionService, string refId)
{
    var response = await transactionService.QueryTransactionAsync(refId);
    // Access response.Data.Status, response.Data.Amount, etc.
}

Testing

The solution includes an Integration Test project FirstChekout.IntegrationTests.

To run tests:

1. Update appsettings.json in the test project or set Environment Variables with valid Sandbox credentials.
2. Run dotnet test.

Note: These tests hit the real Sandbox API. Ensure you have network connectivity to https://www.firstchekoutdev.com/apigateway and https://www.firstchekoutdev.com/identityserver.

Contributing

Please ensure any changes to models reflect the official API documentation.