M-Pesa

M-Pesa

M-Pesa is a leading mobile money service that enables users to store and transfer money, pay for goods and services, and access financial services using their mobile phones. By integrating M-Pesa with CrissCross, businesses can offer a secure and convenient payment option to their customers, facilitating real-time transactions and enhancing the overall payment experience.

Introduction

M-Pesa, a mobile money service launched in 2007 by Safaricom and Vodacom, operates primarily in several African countries. It is an essential payment method for businesses targeting markets in Africa where mobile money services are extensively used. Integrating M-Pesa with CrissCross allows you to accept payments, initiate transfers, and manage financial transactions efficiently. This guide provides a comprehensive overview of how to integrate M-Pesa into your application or website using CrissCross.

M-Pesa’s extensive agent network and user-friendly platform have made it a significant player in promoting financial inclusion across these regions, serving millions of customers who may not have access to traditional banking services. In addition to its primary operations, M-Pesa has expanded its services to include international transfers, enhancing its functionality beyond just domestic transactions. Notably, users in Kenya can send money to countries such as Rwanda, Uganda, Botswana, Zambia, Malawi, Bangladesh, Pakistan, and Burundi.

Pre-requisites

Before accepting M-Pesa payments through CrissCross, ensure you meet the following requirements:

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

• Payment method enabled:
  You have enabled M-Pesa as a payment option in your CrissCross configuration through the CrissCross dashboard. As your merchant of record, CrissCross handles all payment provider relationships, so you can accept M-Pesa payments without needing to register with individual providers or establish commercial relationships.

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

Ways to Integrate M-Pesa with CrissCross

CrissCross supports multiple integration methods for offering M-Pesa at checkout:

1. CrissCross Hosted Checkout
   Using CrissCross’s hosted checkout is the simplest way to accept M-Pesa payments. With this option:

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

2. CrissCross SDK
   If you prefer more control over your checkout experience, you can integrate with the CrissCross SDK:

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

3. Server-to-Server Integration
   For complete control over your payment process and checkout flow, you can integrate M-Pesa using CrissCross’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) and forwarding them to CrissCross securely.

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

Retrieving Available Payment Methods

Using the CrissCross 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. Use the returned availableMethods[].type as your paymentMethodId when initiating the transaction.

Request:

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

Response:

{
  "success": true,
  "availableMethods": [
    {
      "type": "mobileMoney",
      "name": "M-Pesa",
      "requiredInput": [
        {
          "name": "payerMobileNumber",
          "type": "text",
          "label": "Mobile Number"
        },
        {
          "name": "provider",
          "type": "select",
          "label": "Mobile Money Provider",
          "options": ["M-Pesa"]
        }
      ]
    },
    ...other methods...
  ]
}

In this response:

• The M-Pesa payment method is listed with "type": "mobileMoney".
• The requiredInput field indicates that the customer must provide details such as their mobile number and provider.

Creating a Checkout Session

To create a checkout session, make a POST request to the /v1/checkout/session endpoint.

curl -X POST https://api.crisscross.money/v1/checkout/session \
     -H "Content-Type: application/json" \
     -d '{
  "merchantId": "YOUR_MERCHANT_ID",
  "merchantReference": "ORDER12345",
  "amount": 1000,
  "currency": "KES",
  "integrationType": "hosted",
  "redirectUrl": "https://merchant.com/redirect",
  "payerDetails": {
    "emailAddress": "[email protected]",
    "location": "KEN",
    "fullName": "John Doe",
    "phoneNumber": "254712345678"
  }
}'

Response:

{
  "sessionId": "SESSION_abcdef123456",
  "paymentLink": "https://crisscross.money/checkout/SESSION_abcdef123456"
}

In this example:

• The sessionId in the response references this specific checkout session, which can be used to retrieve available methods, 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 CrissCross SDK or a server-to-server integration, you’ll use the session details to process the M-Pesa payment. This involves:

• Initiating M-Pesa Payments (Direct Integration):

  1. Collect required details: use the requiredInput returned by GET /v1/payment/available-methods (typically a payer mobile number and provider).
  2. Initiate the transaction: call POST /v1/payment with your sessionId, the selected paymentMethodId, and paymentDetails.
  3. Complete authorization if needed: if the response/polling includes an authState (for example, a redirect), follow it and then call POST /v1/payment/authorize with the required authorizationData.

  Example initiate request:

  $
  curl -X POST https://api.crisscross.money/v1/payment \
  >
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  >
    -H "Content-Type: application/json" \
  >
    -d '{
  $
      "sessionId": "SESSION_abcdef123456",
  $
      "paymentMethodId": "mobileMoney",
  $
      "paymentDetails": {
  $
        "type": "mobilemoney",
  $
        "payerMobileNumber": "0712345678",
  $
        "provider": "M-Pesa"
  $
      }
  $
    }'

• Verifying Payment Status:

  • Polling: GET /v1/payment/{transactionId}
  • Webhooks: subscribe to webhook events and treat the webhook state as your source of truth.

Test Phone Numbers for Integration

During development and testing, you can use the following test phone numbers to simulate different transaction scenarios with M-Pesa in Kenya:

These test numbers allow you to simulate various success and failure scenarios during your integration testing phase, helping you handle different transaction states and error conditions appropriately in your application.

Supported Regions / Countries

M-Pesa, a mobile money service launched in 2007 by Safaricom and Vodacom, operates primarily in several African countries. Here is a list of the countries where M-Pesa is currently available:

• Kenya
• Tanzania
• Mozambique
• Democratic Republic of Congo (DRC)
• Lesotho
• Ghana
• Egypt

In addition to these, M-PESA has expanded its services to include international transfers to and from various countries, enhancing its functionality beyond just domestic transactions. Notably, users in Kenya can send money to countries such as Rwanda, Uganda, Botswana, Zambia, Malawi, Bangladesh, Pakistan, and Burundi.

Supported Currencies

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

Supported Workflows and Services

The following table outlines the workflows and services supported when using M-Pesa with CrissCross:

Ensuring a Seamless and Secure Payment Experience

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

• Prioritize Security and Compliance:
  Protecting customer data is paramount. CrissCross adheres to PCI DSS standards and other relevant regulations. Ensure you also follow any additional region-specific compliance requirements, especially when handling sensitive financial information across different countries.

• Focus on a Smooth User Experience:
  Present payment methods clearly and intuitively. When customers reach the checkout stage, they should easily recognize and trust the payment options available. For example, highlight local payment methods prominently in regions where they are popular.

• Monitor Performance and Reliability:
  Keep an eye on transaction success rates and processing times. CrissCross’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. CrissCross’s flexible infrastructure makes it easy to add new payment methods, integrate with additional PSPs, or adjust your configurations to handle increased transaction volumes without compromising performance.

Additional Resources and Next Steps

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

• CrissCross API Documentation
  Dive deeper into CrissCross’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 CrissCross’s SDKs, ensuring a smooth setup experience regardless of your technical background or business model.

• M-Pesa Developer Documentation
  Access comprehensive guides, API references, and best practices directly from M-Pesa to enhance your integration.

By configuring M-Pesa with CrissCross, you can offer your customers a streamlined and secure mobile money payment experience tailored to their preferences and regional payment norms. Continuously refine your payment configurations and leverage CrissCross’s robust features to stay agile in an ever-evolving e-commerce landscape.