Skip to main content

​
Overview

The Hubtel Merchant Checkout SDK supports mobile money payments from all major mobile network operators in Ghana. Mobile money is one of the most popular payment methods, allowing customers to pay directly from their mobile wallets.

​
Supported Providers

The SDK supports the following mobile money providers:

MTN Mobile Money

Ghana’s largest mobile money network

Telecel Cash

Formerly Vodafone Cash

AirtelTigo Cash

Combined Airtel and Tigo network

​
Provider Configuration

The SDK automatically handles provider identification and configuration. Each provider is represented by the MomoProvider class: 
class MomoProvider {
  String? name;
  String? logoUrl;
  String? alias;
  String? receiveMoneyPromptValue;
  String? directDebitValue;
  String? preapprovalConfirmValue;
}

​
Provider Aliases

Each provider has a specific alias used for API communication:
ProviderAliasDirect Debit Value
MTNmtn-ghmtn-gh-direct-debit
Vodafone/Telecelvodafone-ghvodafone-gh-direct-debit
AirtelTigotigo-ghtigo-gh-direct-debit

​
Payment Flow

1

Customer Selects Mobile Money

The customer selects mobile money as their payment method in the checkout interface.
2

Choose Provider

The customer selects their mobile network provider (MTN, Vodafone, or AirtelTigo).
3

Enter Mobile Number

The customer enters their registered mobile money number.
4

Authorization Prompt

The customer receives a USSD prompt on their phone to authorize the payment by entering their mobile money PIN.
5

Payment Confirmation

Once authorized, the payment is processed and the customer receives a confirmation.

​
Mobile Money Response

When a mobile money payment is initiated, the SDK returns a MomoResponse object: 
class MomoResponse {
  String? transactionId;
  double? charges;
  double? amount;
  double? amountAfterCharges;
  double? amountCharged;
  double? deliveryFee;
  String? description;
  String? clientReference;
  String? hubtelPreapprovalId;
  String? otpPrefix;
  String? customerMsisdn;
  bool? skipOtp;
  String? verificationType;
  String? customerName;
  String? invoiceNumber;
  String? email;
}

​
Key Response Fields

  • transactionId: Unique identifier for the transaction
  • customerMsisdn: The customer’s mobile money number
  • hubtelPreapprovalId: ID for pre-approved transactions
  • skipOtp: Whether OTP verification can be skipped
  • verificationType: The type of verification required

​
Usage Example

import 'package:hubtel_merchant_checkout_sdk/hubtel_merchant_checkout_sdk.dart';

// Configure checkout with purchase info
final purchaseInfo = PurchaseInfo(
  customerMsisdn: '0241234567', // Customer's phone number
  amount: 50.00,
  description: 'Payment for goods',
);

final config = HubtelCheckoutConfiguration(
  merchantApiKey: 'your_api_key',
  merchantID: 'your_merchant_id',
  callbackUrl: 'https://your-callback-url.com',
);

// Navigate to checkout screen
final result = await Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => CheckoutScreen(
      purchaseInfo: purchaseInfo,
      configuration: config,
    ),
  ),
);

// Handle result
if (result is CheckoutCompletionStatus && 
    result.status == UnifiedCheckoutPaymentStatus.paymentSuccess) {
  print('Payment successful: ${result.transactionId}');
}

​
Authorization Methods

​
USSD Prompt

Customers receive an authorization prompt on their phone. If they don’t receive it, they can manually check:
MTN Customers: Dial *170# → My Account → Approvals

​
OTP Verification

Some merchants may require OTP verification for mobile money payments: 
// Check if OTP is required
if (channelResponse.requireMobileMoneyOTP == true) {
  // Customer will need to enter OTP
  // SDK handles OTP screen automatically
}

​
Pre-Approval (Mandates)

For recurring payments, the SDK supports mobile money pre-approvals:
Pre-approvals allow customers to authorize recurring payments without entering their PIN each time.

​
Creating a Mandate ID

For G-Money (GCB) users:
1

Dial USSD Code

Dial *422#
2

Select G-Money

Select Option 2 (G-Money)
3

Payment Services

Select Option 5 (Payment Services)
4

Mandate

Select Option 6 (Mandate)
5

Create Mandate

Select Option 1 (Create Mandate)

​
Wallet Management

For Hubtel internal merchants, customers can save mobile money wallets for faster checkout: 
class Wallet {
  final String? accountNo;        // Mobile money number
  final String? accountName;      // Account holder name
  final String? provider;         // Provider identifier
  final String? type;             // Wallet type
  
  String get providerName {
    if (provider?.toLowerCase().contains('mtn') == true) {
      return 'MTN Mobile Money';
    }
    if (provider?.toLowerCase().contains('vodafone') == true) {
      return 'Telecel Cash';
    }
    if (provider?.toLowerCase().contains('tigo') == true || 
        provider?.toLowerCase().contains('airtel') == true) {
      return 'AT Money';
    }
    return provider ?? '';
  }
}

​
Best Practices

Testing: Use test credentials provided by Hubtel for development and staging environments.
Customer Phone Numbers: Always validate that the phone number matches the format required by the mobile network operator.

​
Error Handling

final result = await Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => CheckoutScreen(
      purchaseInfo: purchaseInfo,
      configuration: config,
    ),
  ),
);

if (result is CheckoutCompletionStatus) {
  switch (result.status) {
    case UnifiedCheckoutPaymentStatus.paymentSuccess:
      // Payment successful
      break;
    case UnifiedCheckoutPaymentStatus.pending:
      // Payment pending authorization
      break;
    case UnifiedCheckoutPaymentStatus.paymentFailed:
      // Payment failed
      break;
    case UnifiedCheckoutPaymentStatus.userCancelledPayment:
      // User cancelled
      break;
    case UnifiedCheckoutPaymentStatus.unknown:
      // Unknown status
      break;
  }
}

​
Troubleshooting

​
Customer Doesn’t Receive Prompt

  1. Verify the mobile number is correct
  2. Check if the customer’s mobile money wallet is active
  3. Ask customer to manually check for pending approvals using their provider’s USSD code

​
Payment Timeout

Mobile money payments have a timeout period. If the customer doesn’t approve in time:
  • The payment status will be expired
  • Customer can retry the payment
  • Check the transaction status using the transaction ID

Build docs developers (and LLMs) love

Get started for freeTalk to us