Mobile Money Payments

Mobile money lets people send and receive money using their phone number. Instead of a bank account, they have a mobile money account linked to their phone.

It's very popular in Africa, where many people don't have bank accounts but do have mobile phones. Services like M-Pesa in Kenya have over 50 million users.

When a customer pays with mobile money, they get a prompt on their phone. They enter their PIN to confirm, and the money moves from their mobile wallet to your account.

Here's what happens when a customer pays with mobile money:

1. Customer starts checkout - They enter their phone number and choose mobile money as the payment method.
2. You create a payment - Your server sends the amount, currency, and phone number to ClapPay.
3. Customer gets a prompt - An STK Push (SIM Toolkit Push) appears on their phone asking them to confirm the payment.
4. Customer enters PIN - They enter their mobile money PIN to authorize the payment.
5. Payment completes - ClapPay receives confirmation and sends you a webhook.

The whole process usually takes 15-30 seconds.

Here's how to accept an M-Pesa payment in Kenya:

const clappay = require('@clappay/sdk')('sk_live_...');

// Create a mobile money payment
const payment = await clappay.paymentIntents.create({
  amount: 1000,          // 1000 KES
  currency: 'kes',
  payment_method_types: ['mobile_money'],
  payment_method_data: {
    type: 'mobile_money',
    mobile_money: {
      provider: 'mpesa',
      phone_number: '+254712345678',  // Customer's number
    }
  },
  confirm: true,  // Send STK push immediately
});

// The customer will receive an STK push on their phone
console.log('Payment status:', payment.status);
// 'requires_action' means waiting for customer to enter PIN

After creating the payment, the customer has about 60 seconds to enter their PIN. If they don't respond, the payment expires.

Mobile money payments go through these statuses:

Since mobile money payments happen on the customer's phone, you need webhooks to know when they complete:

// Handle mobile money payment webhook
app.post('/webhooks/clappay', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'payment_intent.succeeded') {
    const payment = event.data.object;
    
    // Check if it's a mobile money payment
    if (payment.payment_method_types.includes('mobile_money')) {
      console.log('Mobile money payment received!');
      console.log('Amount:', payment.amount);
      console.log('Provider:', payment.charges.data[0].payment_method_details.mobile_money.provider);
      
      // Fulfill the order
      await fulfillOrder(payment.metadata.order_id);
    }
  }
  
  res.status(200).send('OK');
});

• Tell customers what to expect - Let them know they'll receive a prompt on their phone and should have it ready.
• Show a waiting screen - Display a message like "Waiting for you to confirm on your phone..." while they enter their PIN.
• Handle timeouts gracefully - If the payment expires, offer to resend the prompt.
• Use the right currency - Mobile money payments must be in the local currency. You can't charge M-Pesa in USD.
• Verify phone numbers - Consider sending an OTP to verify the phone number before charging.