uss_sdk 0.3.1

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

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: '[phone]',
      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