ctechpay 0.1.0

Official Flutter and Dart SDK for CtechPay in-app Airtel Money payments and card checkout status checks.

CtechPay Flutter SDK

Official Flutter and Dart SDK for CtechPay mobile payments.

This package is designed for in-app mobile payment flows. Airtel Money payments can be initiated and polled inside the app. Card payments open a secure hosted payment page inside the app, then CtechPay returns the order reference and final status to your app.

Your CtechPay service token must never be exposed in public repositories. For production mobile apps, consider issuing payments from your backend or using a short-lived token strategy if one is available for your integration.

Installation

flutter pub add ctechpay

Basic Usage

import 'package:ctechpay/ctechpay.dart';

final ctechpay = CtechPayClient(
  token: 'YOUR_SERVICE_TOKEN',
);

You can also configure the API base URL and timeout:

final ctechpay = CtechPayClient(
  token: 'YOUR_SERVICE_TOKEN',
  baseUrl: 'https://new-api.ctechpay.com',
  timeout: const Duration(seconds: 30),
);

In-App Airtel Money Payment

Use payAndPoll when you want the SDK to initiate payment and keep checking status until the payment completes, fails, or times out.

final result = await ctechpay.airtel.payAndPoll(
  amount: 100,
  phone: '0999123456',
  customerReference: 'ORDER-1001',
  customerMessage: 'Order payment',
  onPoll: (status) {
    print('Latest status: $status');
  },
);

if (result.isCompleted) {
  print('Paid: ${result.transactionId}');
} else {
  print('Payment not completed: ${result.message}');
}

Airtel Money API Methods

Initiate Payment

final payment = await ctechpay.airtel.pay(
  amount: 100,
  phone: '0999123456',
  customerReference: 'ORDER-1001',
  customerMessage: 'Order payment',
);

Check Airtel Status

final status = await ctechpay.airtel.status('ID2601190847549183CTPAY');

Get Airtel Transaction Details

final details = await ctechpay.airtel.details('ID2601190847549183CTPAY');

Find CtechPay Transaction By Airtel Money ID

final reference = await ctechpay.airtel.reference('AIRTEL_MONEY_ID');

In-App Card Checkout

The ready-made checkout page opens a secure hosted card payment page inside the app using WebView. Your app does not collect or store card PAN/CVV.

final checkout = await ctechpay.cards.createPaymentPage(
  amount: 100,
  redirectUrl: 'https://ctechpay.com/sdk/card-success',
  cancelUrl: 'https://ctechpay.com/sdk/card-cancel',
  customerReference: 'ORDER-1001',
  customerMessage: 'Order payment',
);

After the WebView reaches the success redirect, check status:

final status = await ctechpay.cards.status(checkout.orderReference);

You can also poll for the final hosted card status:

final finalResult = await ctechpay.cards.pollHostedStatus(
  orderReference: checkout.orderReference,
);

Card Hosted Bank Page

If you prefer to create the hosted card checkout URL manually:

final checkout = await ctechpay.cards.createPaymentPage(
  amount: 100,
  customerReference: 'ORDER-1001',
  customerMessage: 'Order payment',
);

print(checkout.paymentPageUrl);

Open checkout.paymentPageUrl using your preferred in-app WebView package. After the card payment is completed, check status with:

final status = await ctechpay.cards.status(checkout.orderReference);

Ready-Made Flutter Checkout Page

CtechPayCheckoutPage gives you a responsive mobile payment screen with packaged CtechPay, Airtel Money, and card logos. Airtel Money polling is built in, and successful payments show a completion state with the transaction reference.

Navigator.of(context).push(
  MaterialPageRoute(
    builder: (_) => CtechPayCheckoutPage(
      client: ctechpay,
      amount: 100,
      customerReference: 'ORDER-1001',
      customerMessage: 'Order payment',
      onCompleted: (result) {
        print('Payment completed: ${result.transactionId}');
      },
      onFailed: (error) {
        print('Payment failed: $error');
      },
      onCancelled: () {
        print('Payment flow cancelled');
      },
      onCardCompleted: (result) {
        print('Card payment completed: ${result.orderReference}');
      },
      onCardCheckoutUrl: (checkout) {
        print('Card checkout opened: ${checkout.paymentPageUrl}');
      },
    ),
  ),
);

Error Handling

The SDK throws CtechPayException for failed requests.

try {
  final status = await ctechpay.airtel.status('ID2601190847549183CTPAY');
  print(status);
} on CtechPayException catch (error) {
  print(error.message);
  print(error.statusCode);
  print(error.response);
}

Security Notes

Do not store card details in your app. Card PAN/CVV is collected by the secure hosted payment page, not by your Flutter app.

Cancelling the checkout page stops the SDK payment flow and polling. If a network payment prompt was already sent, verify the final transaction status before starting another payment.