uss_sdk

Dart/Flutter SDK for the Universal Subscription System payment, subscription, and transaction APIs.

Features

  • Create payment transactions
  • Fetch paginated transaction lists and full transaction details
  • Verify customer subscriptions by project
  • List available payment ways for a project
  • Typed request/response models that mirror the backend API
  • Clear error handling via UssException

Getting started

Add the package to your pubspec.yaml:

dependencies:
  uss_sdk:
    path: ../uss_sdk

Then install dependencies:

flutter pub get

Environment setup

Create a .env file in your app root (copy from .env.example):

USS_BASE_URL=http://84.247.138.251

Note: http://84.247.138.251/Dashboard/Client is the web dashboard sign-in page. The SDK uses the server root as the API base URL so requests go to paths like /api/transactionpayment/... and /api/paymenttransactions/....

Register it as a Flutter asset in your app's pubspec.yaml:

flutter:
  assets:
    - .env

Load dotenv before using the SDK:

import 'package:uss_sdk/uss_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await UssClient.loadEnv();

  runApp(const MyApp());
}

Quick start

import 'package:uss_sdk/uss_sdk.dart';

// After UssClient.loadEnv() in main()
final client = UssClient.fromEnv();

try {
  // 1. List payment ways for a project
  final ways = await client.projectPaymentWays.getProjectPaymentWays(
    ProjectPaymentWaysRequest(projectCode: 'MY_PROJECT'),
  );

  // 2. Create a payment transaction
  final created = await client.transactionPayments.createTransactionPayment(
    CreatePaymentTransactionRequest(
      projectCode: 'MY_PROJECT',
      customerInformationId: 42,
      customerInformationName: 'Jane Doe',
      customerPayingPhoneNumber: '+255712345678',
      paymentTypeOptionCode: ways.paymentWays.first.paymentTypeOptionCode,
      currency: 'TZS',
    ),
  );

  // 3. Verify subscription
  final subscription = await client.subscriptions.checkingProjectSubscriptions(
    VerifySubscriptionRequest(
      customerInformationId: 42,
      customerInformationName: 'Jane Doe',
      projectCode: 'MY_PROJECT',
    ),
  );

  if (subscription.isActive) {
    print('Active until ${subscription.subscription?.endingDate}');
  }

  // 4. Fetch transaction details
  final details = await client.paymentTransactions.getTransactionDetails(
    created.id,
  );

  // 5. Fetch paginated transaction history
  final history = await client.paymentTransactions.getTransactionList(
    PaymentTransactionListRequest(
      customerInformationId: 42,
      customerInformationName: 'Jane Doe',
      projectCode: 'MY_PROJECT',
    ),
  );

  print('Total transactions: ${history.totalCount}');
} on UssException catch (error) {
  print('API error (${error.statusCode}): ${error.message}');
} finally {
  client.close();
}

API reference

UssClient

Main SDK entry point.

Member Description
loadEnv() Loads .env file (call in main())
fromEnv() Creates client using USS_BASE_URL from dotenv
transactionPayments Create payment transactions
paymentTransactions Fetch transaction lists and details
subscriptions Verify customer subscriptions
projectPaymentWays List payment ways for a project
close() Disposes the underlying HTTP client

UssConfig

Member Description
baseUrlKey Dotenv key: USS_BASE_URL
fromEnv() Reads base URL from dotenv
UssConfig(baseUrl: ...) Manual config (useful for tests)

TransactionPaymentService

Method HTTP Endpoint Description
createTransactionPayment POST /api/transactionpayment/createtransactionpayment Creates a payment transaction for a project

PaymentTransactionsService

Method HTTP Endpoint Description
getTransactionList POST /api/paymenttransactions/gettransactionlist Returns a paginated list filtered by customer and project
getTransactionDetails GET /api/paymenttransactions/gettransactiondetails/{id} Returns full transaction details

SubscriptionsService

Method HTTP Endpoint Description
checkingProjectSubscriptions POST /api/subscriptions/checkingprojectsubscriptions Verifies whether a customer has an active subscription

ProjectPaymentWaysService

Method HTTP Endpoint Description
getProjectPaymentWays POST /api/projectpaymentways/getprojectpaymentways Returns all payment ways configured for a project

Create transaction

Request: CreatePaymentTransactionRequest

Field Required Description
projectCode Yes Project code used to resolve payment configuration
paymentTypeOptionId No Select a payment way when multiple exist
paymentTypeOptionCode No Alternative selector for payment way
currency No Currency code
customerInformationId No Customer ID in your system
customerInformationName No Customer display name
customerPayingPhoneNumber No Mobile money or phone-based payment number
customerPayingAccountNumber No Card or bank account number
customerPayingExpire No Card expiry
customerPayingCvv No Card CVV
createdBy No User ID creating the transaction

Response: CreatePaymentTransactionResponse

Common errors:

Status Meaning
400 Validation failed, no active payment configuration, or multiple payment ways without a selector

Fetch transaction list

Request: PaymentTransactionListRequest

Field Required Default Description
customerInformationId Yes — Customer ID
customerInformationName Yes — Customer name
projectCode Yes — Project code
page No 1 One-based page number
pageSize No 10 Items per page (max 100 on API)

Response: PagedResult<PaymentTransactionListItem>

Fetch transaction details

Parameter: transaction id

Response: PaymentTransactionDetails

Common errors:

Status Meaning
404 Transaction not found

Verify subscription

Request: VerifySubscriptionRequest

Field Required Description
customerInformationId Yes Customer ID
customerInformationName Yes Customer name
projectCode Yes Project code

Response: VerifySubscriptionResponse

Field Description
isActive true when subscription exists and is not expired
message Reason when inactive (not found or expired and removed)
subscription Details when isActive is true

This endpoint returns HTTP 200 for all outcomes — check isActive instead of catching errors for inactive subscriptions.

Get project payment ways

Request: ProjectPaymentWaysRequest

Field Required Description
projectCode Yes Project code

Response: ProjectPaymentWaysResponse

Use paymentTypeOptionId or paymentTypeOptionCode from each ProjectPaymentWay when calling createTransactionPayment.

Error handling

Non-success HTTP responses throw UssException:

try {
  await client.paymentTransactions.getTransactionDetails(999);
} on UssException catch (error) {
  // error.statusCode -> 404
  // error.message    -> "Payment transaction 999 was not found."
}

Subscription verification does not throw for inactive subscriptions — inspect VerifySubscriptionResponse.isActive instead.

Testing

1. Unit tests (offline, no server needed)

From the uss_sdk folder:

flutter pub get
flutter analyze
flutter test

These tests use mock HTTP responses and do not call your server. You should see 8 tests passed.

2. Live server smoke test

Verifies the SDK against your deployed API at http://84.247.138.251:

flutter test test/live_smoke_test.dart --dart-define=RUN_LIVE_TESTS=true

This checks:

  • Payment ways for project USS-DEMO
  • Subscription verification for demo customer 100001
  • Transaction list + details

Optional overrides:

flutter test test/live_smoke_test.dart --dart-define=RUN_LIVE_TESTS=true --dart-define=USS_LIVE_BASE_URL=http://84.247.138.251 --dart-define=USS_LIVE_PROJECT_CODE=USS-DEMO

3. Quick API check (PowerShell)

Confirm the server is up without Flutter:

Invoke-RestMethod `
  -Uri "http://84.247.138.251/api/projectpaymentways/getprojectpaymentways" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"projectCode":"USS-DEMO"}'

Expected: JSON with "count": 1 and a payment way named Monthly.

4. Test from your Flutter app

pubspec.yaml (your app):

dependencies:
  uss_sdk:
    path: ../uss_sdk

flutter:
  assets:
    - .env

.env (your app root):

USS_BASE_URL=http://84.247.138.251

main.dart:

import 'package:flutter/widgets.dart';
import 'package:uss_sdk/uss_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await UssClient.loadEnv();

  final client = UssClient.fromEnv();

  try {
    final ways = await client.projectPaymentWays.getProjectPaymentWays(
      const ProjectPaymentWaysRequest(projectCode: 'USS-DEMO'),
    );
    debugPrint('Payment ways: ${ways.count}');

    final sub = await client.subscriptions.checkingProjectSubscriptions(
      const VerifySubscriptionRequest(
        customerInformationId: 100001,
        customerInformationName: 'Demo Customer 0001',
        projectCode: 'USS-DEMO',
      ),
    );
    debugPrint('Subscription active: ${sub.isActive}');
  } on UssException catch (e) {
    debugPrint('API error ${e.statusCode}: ${e.message}');
  } finally {
    client.close();
  }

  runApp(const MyApp());
}

Run the app and check the debug console for output.

5. Demo data on the server

Value Example
Project code USS-DEMO or USS-SANDBOX
Customer ID 100001
Customer name Demo Customer 0001
Dashboard http://84.247.138.251/Dashboard/Client

Troubleshooting

Problem Fix
UssEnvException: Missing USS_BASE_URL Call await UssClient.loadEnv() and add .env to Flutter assets
Connection timeout Check server is running and device/emulator can reach 84.247.138.251
400 on create transaction Use USS-DEMO and pass paymentTypeOptionCode: 'monthly' if needed
404 on transaction details Use an ID from getTransactionList, not a random number

The SDK accepts a custom http.Client for mocking in your own tests:

final client = UssClient(
  config: UssConfig(baseUrl: 'https://example.com'),
  httpClient: mockHttpClient,
);

Backend controllers

This SDK mirrors:

  • TransactionPaymentController
  • PaymentTransactionsController
  • SubscriptionsController
  • ProjectPaymentWaysController

Libraries

uss_sdk
Dart/Flutter SDK for the Universal Subscription System payment APIs.