Skip to main content

​
Overview

CheckoutCompletionStatus contains information about the completion state of a checkout transaction, including the payment status, transaction details, and payment method used.

​
Constructor

CheckoutCompletionStatus({
  required UnifiedCheckoutPaymentStatus status,
  required String transactionId,
  String? paymentChannel,
  String? paymentType,
})

​
Parameters

​
status
UnifiedCheckoutPaymentStatus
required
The final status of the payment transaction. See UnifiedCheckoutPaymentStatus for possible values.
​
transactionId
String
required
The unique transaction identifier generated by Hubtel. Use this ID to track and verify the transaction.
​
paymentChannel
String?
Optional. The payment channel used for the transaction (e.g., ‘mtn-gh’, ‘vodafone-gh’, ‘visa’, ‘mastercard’).
​
paymentType
String?
Optional. The type of payment method used (e.g., ‘mobile-money’, ‘card’, ‘bank-transfer’).

​
Properties

​
status
UnifiedCheckoutPaymentStatus
The payment status indicating whether the transaction succeeded, failed, is pending, or was cancelled.
​
transactionId
String
The unique Hubtel transaction ID for this payment.
​
paymentChannel
String?
The specific payment channel used (e.g., MTN Mobile Money, Vodafone Cash, Visa).
​
paymentType
String?
The payment method category (e.g., mobile money, card payment).

​
UnifiedCheckoutPaymentStatus Enum

The UnifiedCheckoutPaymentStatus enum defines the possible states of a payment transaction: 
enum UnifiedCheckoutPaymentStatus {
  paymentFailed,
  paymentSuccess,
  pending,
  unknown,
  userCancelledPayment
}

​
Status Values

​
paymentSuccess
enum
The payment was completed successfully and funds were transferred.
​
paymentFailed
enum
The payment failed due to an error (insufficient funds, network issue, etc.).
​
pending
enum
The payment is still being processed. Final status is not yet determined.
​
userCancelledPayment
enum
The user explicitly cancelled the payment process.
​
unknown
enum
The payment status could not be determined.

​
Usage Example

import 'package:hubtel_merchant_checkout_sdk/hubtel_merchant_checkout_sdk.dart';

void handleCheckoutCompletion(CheckoutCompletionStatus completionStatus) {
  switch (completionStatus.status) {
    case UnifiedCheckoutPaymentStatus.paymentSuccess:
      print('Payment successful!');
      print('Transaction ID: ${completionStatus.transactionId}');
      print('Payment Channel: ${completionStatus.paymentChannel}');
      print('Payment Type: ${completionStatus.paymentType}');
      // Update order status, show success message
      break;
      
    case UnifiedCheckoutPaymentStatus.paymentFailed:
      print('Payment failed');
      print('Transaction ID: ${completionStatus.transactionId}');
      // Show error message, allow retry
      break;
      
    case UnifiedCheckoutPaymentStatus.pending:
      print('Payment pending');
      // Show pending status, poll for updates
      break;
      
    case UnifiedCheckoutPaymentStatus.userCancelledPayment:
      print('User cancelled payment');
      // Return to previous screen
      break;
      
    case UnifiedCheckoutPaymentStatus.unknown:
      print('Unknown payment status');
      // Show generic error, contact support
      break;
  }
}

​
Integration with CheckoutScreen

import 'package:flutter/material.dart';
import 'package:hubtel_merchant_checkout_sdk/hubtel_merchant_checkout_sdk.dart';

class PaymentPage extends StatelessWidget {
  void _onCheckoutComplete(CheckoutCompletionStatus status) {
    if (status.status == UnifiedCheckoutPaymentStatus.paymentSuccess) {
      // Verify transaction on your backend
      verifyTransaction(status.transactionId);
      
      // Show success UI
      showSuccessDialog(
        transactionId: status.transactionId,
        paymentMethod: status.paymentChannel ?? 'Unknown',
      );
    }
  }
  
  @override
  Widget build(BuildContext context) {
    return CheckoutScreen(
      purchaseInfo: purchaseInfo,
      configuration: configuration,
    );
  }
}

​
Best Practices

Always verify the payment status on your backend server using the transactionId before fulfilling orders. Never rely solely on the client-side status.

​
Status Handling

  1. Success: Update order status and fulfill the purchase
  2. Failed: Log the error and allow the user to retry
  3. Pending: Poll for status updates or wait for webhook notification
  4. Cancelled: Return to the previous screen without changes
  5. Unknown: Log for investigation and contact support

​
Transaction Verification

  • Store the transactionId in your database
  • Verify the transaction status via Hubtel’s API on your backend
  • Handle webhook notifications for asynchronous status updates
  • Implement idempotency to prevent duplicate order fulfillment

​
Payment Channel Information

The paymentChannel and paymentType fields help you:
  • Track which payment methods are most popular
  • Provide targeted customer support
  • Analyze payment success rates by channel
  • Optimize your payment flow based on user preferences

Build docs developers (and LLMs) love

Get started for freeTalk to us