splashpay_sdk #

A standalone, production-ready Flutter/Dart package for integrating the SplashPay Tanzania REST API.

Published by dukanitech.com on pub.flutter-io.cn.

This package is a standalone SDK that can be consumed by any Flutter application as a normal dependency.

Features #

• Mobile Money payment initiation
• Payment status check
• Cancel pending payment
• Typed request and response models
• Payment status enum mapping
• Idempotency key support
• Webhook payload models and signature verification helper (for backend use)
• Comprehensive exception hierarchy

Installation #

pub.flutter-io.cn #

dependencies:
  splashpay_sdk: ^1.0.0

flutter pub get

Local path dependency #

dependencies:
  splashpay_sdk:
    path: ../splashpay_sdk

Git dependency #

dependencies:
  splashpay_sdk:
    git:
      url: https://github.com/dukanitech/splashpay_sdk.git
      ref: main

Initialization #

import 'package:splashpay_sdk/splashpay_sdk.dart';

final splashPay = SplashPay(
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  environment: SplashPayEnvironment.sandbox, // or production
);

Authentication uses documented headers:

• X-API-KEY
• X-API-SECRET
• Content-Type: application/json
• Accept: application/json

Use pk_test_ / sk_test_ credentials for sandbox and pk_live_ / sk_live_ for production. Both environments use the documented base URL: https://api.splashpay.co.tz/api/v1.

Mobile Money #

Initiate a Mobile Money payment per the official documentation:

final result = await splashPay.mobileMoney(
  amount: 1000,
  currency: 'TZS', // optional, defaults to TZS
  phone: '255712345678',
  reference: 'INV-1234',
  customerName: 'John Doe',
  customerEmail: 'john.doe@example.com',
  metadata: {'order_id': '12345'}, // optional
  idempotencyKey: 'unique-payment-key', // optional
);

Required fields: amount, currency (TZS), reference, phone, customer_name, customer_email.

A successful API response does not mean the customer has paid. The initial transaction status is typically pending. Use webhooks or the status API for the final outcome.

Response #

print(result.success);           // API request succeeded
print(result.code);              // e.g. PAYMENT_INITIATED
print(result.message);
print(result.paymentStatus);     // PaymentStatus.pending, etc.
print(result.reference);
print(result.transactionId);     // provider_reference
print(result.data?.fee);
print(result.data?.netAmount);

Payment statuses #

Unknown future status values are mapped to PaymentStatus.unknown without throwing.

Payment status check #

final status = await splashPay.paymentStatus(reference: 'INV-1234');
print(status.paymentStatus);

Cancel payment #

final cancelled = await splashPay.cancelPayment(reference: 'INV-1234');

Only pending (and optionally processing) payments can be cancelled.

Error handling #

try {
  final result = await splashPay.mobileMoney(
    amount: 1000,
    phone: '255712345678',
    reference: 'INV-1234',
    customerName: 'John Doe',
    customerEmail: 'john@example.com',
  );
} on SplashPayAuthenticationException catch (e) {
  // Invalid API credentials (401 / UNAUTHORIZED)
} on SplashPayValidationException catch (e) {
  // Invalid request payload
} on SplashPayTimeoutException catch (e) {
  // Request timed out
} on SplashPayNetworkException catch (e) {
  // Network connectivity issues
} on SplashPayApiException catch (e) {
  // API returned an error
} on SplashPayException catch (e) {
  print(e.message);
  print(e.code);
}

Idempotency #

SplashPay requires an Idempotency-Key header for Mobile Money requests.

• If you pass idempotencyKey, that value is used.
• If omitted, the SDK generates a deterministic key from the request body so retries with identical parameters reuse the same key.
• Reuse the same key only when retrying the same request. Use a new key for distinct payments.

Security #

Do not embed API secrets in distributed Flutter apps if they must remain confidential. SplashPay documentation states:

Never expose your API Secret in frontend applications, mobile apps, or public repositories.

Recommended architecture for production:

Flutter App  →  Your Backend  →  SplashPay API

Your backend holds X-API-KEY and X-API-SECRET. The mobile app calls your backend, not SplashPay directly.

Use [SplashPay.forMerchant] only on the server. The SDK does not log API keys, secrets, or sensitive customer data.

Flutter apps (backend proxy) #

Distributed apps should never construct SplashPay(...) / SplashPay.forMerchant(...) with real credentials.

Instead:

1. Call your authenticated backend (POST /billing/subscribe, status, cancel, webhooks).
2. Reuse SDK models/helpers on the client for status interpretation:

import 'package:splashpay_sdk/splashpay_sdk.dart';

final status = PaymentStatus.fromString(payment['status'] as String?);
if (status.isSuccess) { /* activate UI */ }
if (status.isTerminal) { /* stop polling */ }

PaymentStatus.fromString also accepts common backend aliases (paid → success, reject → failed).

Backend Dart services #

Server-side Dart may use the full merchant client:

final splashPay = SplashPay.forMerchant(
  apiKey: Platform.environment['SPLASHPAY_API_KEY']!,
  apiSecret: Platform.environment['SPLASHPAY_API_SECRET']!,
  environment: SplashPayEnvironment.production,
);

Webhooks #

A Flutter package cannot safely act as the production webhook endpoint. Webhook handling belongs on your backend:

SplashPay → webhook → Backend → Database → Flutter application

The SDK provides models and a signature verifier for backend Dart services:

final event = SplashPayWebhookEvent.fromJsonString(payload);
final valid = SplashPayWebhookVerifier.verify(
  payload: rawBody,
  timestamp: timestamp,
  signature: signature,
  webhookSecret: 'YOUR_WEBHOOK_SECRET',
);

Verify signatures using HMAC_SHA256(timestamp + "." + request_body, WEBHOOK_SECRET) per SplashPay documentation.

Example app #

cd example
cp .env.example .env
# Edit .env with your credentials
flutter run

The example loads SPLASHPAY_API_KEY, SPLASHPAY_API_SECRET, and SPLASHPAY_ENVIRONMENT from .env. Never commit real API keys.

API reference #

Base URL: https://api.splashpay.co.tz/api/v1

License #

MIT — see LICENSE.

Publishing #

Published under the dukanitech.com verified publisher on pub.flutter-io.cn.

See PUBLISHING.md for deployment and publisher transfer instructions.