Tanzania Mobile Money

Tanzania Mobile Money

Mobile money is the dominant payment method in Tanzania, enabling customers to send, receive, and pay for goods and services directly from their mobile phones. By integrating Tanzania mobile money with PayOS, businesses can offer a secure and convenient payment option to their customers across all major networks in the country.

Introduction

Tanzania has broad coverage across four major mobile money networks — Airtel, Tigo, Halotel, and Vodacom — making mobile money an essential payment method for any business operating in the Tanzanian market. Integrating Tanzania mobile money with PayOS allows you to accept payments, initiate transfers to mobile wallets, and send payouts to bank accounts — all within a single integration. This guide provides a comprehensive overview of how to integrate Tanzania mobile money into your application or website using PayOS.

Pre-requisites

Before accepting mobile money payments in Tanzania through PayOS, ensure you meet the following requirements:

• PayOS Integration:
  You have integrated with PayOS, either using our hosted checkout, SDK (BETA), or server-to-server API.

• Payment Processor Configuration:
  You have set up a payment processor integration for Tanzania mobile money in PayOS. Ensure the commercial relationship with the relevant payment processor is in place or can be utilised through PayOS.

• Enable Tanzania Mobile Money:
  You have enabled Tanzania mobile money as a payment option in your PayOS configuration through the PayOS Portal.

• Meta Fields Setup:
  If Tanzania mobile money requires specific meta fields (such as mobile number or mobile money operator), ensure these fields are correctly configured under Merchant configurations -> Meta fields on your PayOS dashboard and included in your requests.

Ways to Integrate Tanzania Mobile Money with PayOS

PayOS supports multiple integration methods for offering mobile money in Tanzania at checkout:

1. PayOS Hosted Checkout
   Using PayOS’s hosted checkout is the simplest way to accept Tanzania mobile money payments. With this option:

   • Minimal development is required on your end.
   • PayOS automatically displays the mobile money payment method during checkout.
   • You can control the payment methods offered through the session creation API call, specifying mobile money as a restricted method if desired.

2. PayOS SDK (BETA)
   If you prefer more control over your checkout experience, you can integrate with the PayOS SDK:

   • The SDK provides UI components to include mobile money as a payment method seamlessly.
   • It simplifies capturing any required inputs (like mobile number and operator selection) and initiating transactions without extensive server-side coding.
   • Consult the PayOS SDK documentation for detailed steps on integrating Tanzania mobile money.

3. Server-to-Server Integration
   For complete control over your payment process and checkout flow, you can integrate Tanzania mobile money using PayOS’s server-to-server APIs:

   • This approach offers greater flexibility in implementing the payment flow and handling customer data.
   • You will be responsible for capturing necessary inputs (e.g., mobile number, operator) and forwarding them to PayOS securely.

Let’s explore the server-to-server approach in more detail.

Retrieving Available Payment Methods

Using the PayOS API, you can retrieve a list of available payment methods for a given checkout session by calling the GET /v1/payment/available-methods endpoint with a sessionId. For Tanzania mobile money, the method type is returned as mobilemoney.

Request:

$
curl -G https://api.payos.money/api/v1/payment/available-methods \
>
     -d sessionId={sessionId}

Response:

1
{
2
  "success": true,
3
  "availableMethods": [
4
    {
5
      "type": "mobilemoney",
6
      "name": "Mobile Money",
7
      "requiredInput": [
8
        {
9
          "name": "mobileNumber",
10
          "type": "text",
11
          "label": "Mobile Number"
12
        },
13
        {
14
          "name": "provider",
15
          "type": "select",
16
          "label": "Mobile Money Operator",
17
          "options": ["Airtel", "Tigo", "Halotel", "Vodacom"]
18
        }
19
      ]
20
    },
21
    ...other methods...
22
  ]
23
}

Creating a Checkout Session

To create a checkout session that includes Tanzania mobile money as a payment option, make a POST request to the /v1/checkout/session endpoint.

$
curl -X POST https://api.payos.money/api/v1/checkout/session \
>
     -H "Content-Type: application/json" \
>
     -d '{
>
  "amount": 5000,
>
  "currency": "TZS",
>
  "integrationType": "hosted",
>
  "merchantReference": "ORDER12345",
>
  "redirectUrl": "https://merchant.com/redirect",
>
  "merchantId": "12345678-1234-5678-1234-567812345678",
>
  "payerDetails": {
>
    "fullName": "Jane Doe",
>
    "emailAddress": "jane.doe@example.com",
>
    "phoneNumber": "255712345678",
>
    "location": "TZA"
>
  }
>
}'

Response:

1
{
2
  "sessionId": "SESSION_abcdef123456",
3
  "paymentLink": "https://payos.money/checkout/SESSION_abcdef123456"
4
}

In this example:

• The session is created for the Tanzania market (currency: "TZS" and location: "TZA"), where mobile money is available.
• The sessionId in the response references this specific checkout session, which can be used to complete the payment or make further adjustments before checkout completion.

Handling the Payment

After creating a session, your application can direct customers to the paymentLink if using the hosted checkout. If you’re using the PayOS SDK or a server-to-server integration, you’ll use the session details to process the mobile money payment. This involves:

• Initiating Mobile Money Payments:
  Follow these steps to initiate a Tanzania mobile money payment:

  1. Collect the Required Details:
     Gather the customer’s mobile number and their mobile money operator (Airtel, Tigo, Halotel, or Vodacom).

  2. Send the Payment Request:
     Send a POST /payment request to PayOS with the required information.

  3. Handle the Approval Process:
     Inform the customer to approve the payment request on their mobile device via their mobile money app or USSD prompt. The transaction is initiated as pending_approval until the customer confirms.

• Verifying Payment Status:
  You can verify the status of the payment in the following ways:

  • Webhooks: If you have webhooks enabled, monitor the payment status through webhook notifications once the transaction is finalised.
  • Callback URLs: For payments with a callback_id, PayOS will send the payment details and status to the specified callback URL.

Supported Regions / Countries

Tanzania mobile money through PayOS is supported exclusively in Tanzania.

Supported Mobile Money Operators:

(Note: Support for additional regions and countries may be added in the future. Check PayOS documentation or contact support for updates.)

Supported Workflows and Services

The following table outlines the workflows and services supported when using Tanzania mobile money with PayOS:

Ensuring a Seamless and Secure Payment Experience

To optimise your integration and ensure customer satisfaction, consider the following best practices:

• Prioritise Security and Compliance:
  Protecting customer data is paramount. PayOS adheres to PCI DSS standards and other relevant regulations. Ensure you also follow any additional region-specific compliance requirements when handling sensitive financial information in Tanzania.

• Focus on a Smooth User Experience:
  Present payment methods clearly and intuitively. Prompt customers to select their mobile money operator and enter their mobile number accurately to avoid failed transactions. Communicate clearly that an approval prompt will appear on their mobile device.

• Monitor Performance and Reliability:
  Keep an eye on transaction success rates and processing times. PayOS’s dashboard provides insights into each payment method’s performance, enabling you to resolve any latency or downtime issues quickly to maintain customer trust.

• Scale with Your Business Growth:
  As your business expands, your payment needs may evolve. PayOS’s flexible infrastructure makes it easy to adjust configurations and handle increased transaction volumes without compromising performance.

Additional Resources and Next Steps

With PayOS, managing and enabling diverse payment methods becomes more efficient and manageable. For detailed integration instructions, coding examples, and advanced customisation options, explore these resources:

• PayOS API Documentation
  Dive deeper into PayOS’s API endpoints and discover how to implement server-to-server integrations, handle advanced payment flows, and manage transactions programmatically.

• Integration Guides
  Review step-by-step guides for integrating PayOS’s SDKs or connecting to supported payment processors, ensuring a smooth setup experience regardless of your technical background or business model.

By configuring Tanzania mobile money with PayOS, you can offer your customers a streamlined and secure payment experience tailored to local preferences. Continuously refine your payment configurations and leverage PayOS’s robust features to stay agile in an ever-evolving payments landscape.