Refunds

A refund sends money back to the customer using the same payment method they used to pay. If they paid with a credit card, the refund goes back to that card. If they paid with M-Pesa, it goes back to their M-Pesa account.

You can refund the full amount or just part of it. For example, if a customer paid $100 but wants to return one item worth $25, you can refund just $25.

You can create refunds from the Dashboard or using the API.

From the Dashboard

1. Go to Payments in your Dashboard
2. Find the payment you want to refund and click on it
3. Click the Refund button
4. Enter the amount (or leave it as the full amount)
5. Add a reason (optional but helpful for your records)
6. Click Refund

Using the API

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

// Refund the entire payment
const refund = await clappay.refunds.create({
  payment_intent: 'pi_abc123...',
  reason: 'requested_by_customer',
});

console.log('Refund created:', refund.id);
console.log('Status:', refund.status);

// Refund only part of the payment
const refund = await clappay.refunds.create({
  payment_intent: 'pi_abc123...',
  amount: 2500,  // $25.00 in cents
  reason: 'requested_by_customer',
});

When creating a refund, you can specify a reason. This helps with reporting and understanding why customers ask for refunds.

The time it takes for a refund to appear depends on the payment method:

The refund shows as "pending" in your Dashboard until it reaches the customer. Some banks take longer than others to process refunds.

• Time limit - You can refund payments made in the last 180 days. After that, you'll need to send money another way.
• Amount limit - You can't refund more than the original payment amount.
• Multiple refunds - You can issue multiple partial refunds, as long as the total doesn't exceed the original amount.

Refunds go through these statuses:

Set up webhooks to get notified when refund status changes:

app.post('/webhooks/clappay', async (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case 'refund.created':
      console.log('Refund started:', event.data.object.id);
      break;
      
    case 'refund.updated':
      const refund = event.data.object;
      if (refund.status === 'succeeded') {
        console.log('Refund completed:', refund.id);
        // Update your order status
        await markOrderRefunded(refund.payment_intent);
      }
      break;
      
    case 'refund.failed':
      console.log('Refund failed, may need manual action');
      break;
  }
  
  res.status(200).send('OK');
});

Refunds and chargebacks both return money to customers, but they work very differently:

Best practice: If a customer wants their money back, give them a refund before they file a chargeback. It's cheaper and keeps everyone happier.

• Have a clear refund policy - Tell customers upfront when refunds are allowed.
• Process refunds quickly - Don't make customers wait. Fast refunds prevent chargebacks.
• Send confirmation - Email customers when you process their refund so they know to expect it.
• Keep records - Track why refunds happen. If you see patterns, fix the underlying problem.
• Use partial refunds - If only part of an order has issues, refund just that part.