Deposits

Accept deposits into user wallets via M-Pesa STK Push, Bank Transfer, Card Payments, or PayPal. Each method has different use cases and fee structures.

Overview

The Deposits API supports:

M-Pesa STK Push - Customer receives push notification to enter PIN (instant, no fees)
Bank Transfer - Generate bank account details for manual transfer (1-2 business days)
Card Payment - Accept Visa, Mastercard, and other cards (instant, 2.9% + 30 KES fee)
PayPal - Accept payments via PayPal checkout (instant, 3.9% + $0.30 fee, multi-currency support)

M-Pesa Deposit Flow

Call the deposit endpoint with customer phone number
Customer receives STK Push prompt on their phone
Customer enters M-Pesa PIN
Funds are credited to the wallet
Webhook is sent with deposit status

API Reference

Get Deposit Providers

Expand

Create M-Pesa Deposit

Expand

Card Payment Flow

Call the card deposit endpoint with card details or payment token
Customer is redirected to 3D Secure authentication (if required)
Payment is processed and verified
Funds are credited to the wallet (minus processing fee)
Webhook is sent with deposit status

Create Card Deposit

Expand

Note: Card deposits have a processing fee of 2.9% + 30 KES. The netAmount shows what will be credited to the wallet. If 3D Secure is required, redirect the customer to the redirectUrl.

PayPal Deposit Flow

Call the PayPal deposit endpoint with wallet ID and redirect URLs
Receive PayPal order ID and approval URL
Redirect user to PayPal approval URL
User logs in and approves payment on PayPal
PayPal redirects user back to your return URL
Call the capture endpoint to complete the payment
Funds are credited to the wallet (minus processing fee)
Webhook is sent with deposit status

Create PayPal Deposit

Expand

After creating the deposit, redirect the user to the approvalUrl. Once they approve the payment on PayPal, they will be redirected to your returnUrl with the deposit ID. You must then call the capture endpoint to complete the payment.

Capture PayPal Payment

Expand

Note: PayPal deposits have a processing fee of 3.9% + $0.30. PayPal supports multiple currencies including KES, USD, EUR, GBP, NGN, GHS, and ZAR. The capture endpoint must be called after the user approves the payment on PayPal.

Get Deposit Status

Expand

Code Examples

M-Pesa Deposit

mpesa-deposit.js

async function initiateMpesaDeposit(walletId, amount, phoneNumber) {
  const response = await fetch('https://api.wasaapay.com/api/v1/partner/deposits/mpesa', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.WASAAPAY_API_KEY,
      'X-Idempotency-Key': `dep_${Date.now()}`,
    },
    body: JSON.stringify({
      walletId,
      amount,
      phoneNumber,
    }),
  });

  const data = await response.json();

  if (data.success) {
    console.log('STK Push sent! Deposit ID:', data.data.id);
    // Wait for webhook or poll for status
  }

  return data;
}

Card Deposit

card-deposit.js

async function initiateCardDeposit(walletId, amount, cardDetails) {
  const response = await fetch('https://api.wasaapay.com/api/v1/partner/deposits/card', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.WASAAPAY_API_KEY,
      'X-Idempotency-Key': `card_dep_${Date.now()}`,
    },
    body: JSON.stringify({
      walletId,
      amount,
      ...cardDetails,
    }),
  });

  const data = await response.json();

  if (data.success) {
    console.log('Card deposit initiated! Deposit ID:', data.data.id);

    // Check if 3D Secure redirect is needed
    if (data.data.redirectUrl) {
      // Redirect customer to 3DS verification
      window.location.href = data.data.redirectUrl;
    }
  }

  return data;
}

// Example usage
initiateCardDeposit('wallet_abc123', 5000, {
  cardNumber: '4111111111111111',
  expiryMonth: '12',
  expiryYear: '25',
  cvv: '123',
  cardholderName: 'John Doe',
  email: 'john@example.com',
});

PayPal Deposit

paypal-deposit.js

async function initiatePayPalDeposit(walletId, amount, currency = 'USD') {
  // Step 1: Create PayPal deposit order
  const response = await fetch('https://api.wasaapay.com/api/v1/partner/deposits/paypal', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.WASAAPAY_API_KEY,
      'X-Idempotency-Key': `paypal_dep_${Date.now()}`,
    },
    body: JSON.stringify({
      walletId,
      amount,
      currency,
      returnUrl: 'https://yourapp.com/payment/success',
      cancelUrl: 'https://yourapp.com/payment/cancel',
    }),
  });

  const data = await response.json();

  if (data.success) {
    console.log('PayPal order created! Deposit ID:', data.data.id);
    // Redirect user to PayPal for approval
    window.location.href = data.data.approvalUrl;
  }

  return data;
}

// Step 2: After user returns from PayPal, capture the payment
async function capturePayPalDeposit(depositId) {
  const response = await fetch(
    `https://api.wasaapay.com/api/v1/partner/deposits/paypal/${depositId}/capture`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.WASAAPAY_API_KEY,
      },
    }
  );

  const data = await response.json();

  if (data.success) {
    console.log('Payment captured! Status:', data.data.status);
    // Wallet has been credited
  }

  return data;
}

// Usage: Create deposit and redirect
initiatePayPalDeposit('wallet_abc123', 100, 'USD');

// After redirect back, capture the payment (typically in your return URL handler)
// const depositId = getDepositIdFromUrl(); // Get from URL params
// capturePayPalDeposit(depositId);

Webhook Events

Event	Description
`deposit.initiated`	Deposit request initiated (STK push sent or card payment started)
`deposit.completed`	Payment received and credited to wallet
`deposit.failed`	Payment failed, cancelled, or card declined

Testing in Sandbox

M-Pesa Testing

The sandbox environment uses real M-Pesa STK Push for deposits. This means when you initiate a deposit, the customer will receive an actual STK push prompt on their phone.

Use real Kenyan phone numbers for testing
The customer must enter their actual M-Pesa PIN
Real funds will be deducted (use small test amounts)
Webhooks will be triggered upon completion or failure

Card Payment Testing

In sandbox mode, use these test card numbers:

Card Number	Result
`4111111111111111`	Successful payment (Visa)
`5500000000000004`	Successful payment (Mastercard)
`4000000000000002`	Card declined
`4000000000000069`	Expired card
`4000000000000127`	Insufficient funds

Use any future date for expiry (e.g., 12/25) and any 3-digit CVV (e.g., 123).

PayPal Testing

In sandbox mode, PayPal deposits use PayPal's sandbox environment:

Uses PayPal sandbox checkout (not real money)
Create a sandbox buyer account at developer.paypal.com
Use sandbox buyer credentials to approve test payments
Supports multiple currencies: USD, EUR, GBP, KES, NGN, GHS, ZAR
Webhooks are triggered upon completion or failure

Test Credentials: You can use any PayPal sandbox personal account to test. Create sandbox accounts in the PayPal Developer Dashboard.

Sandbox Balance

Sandbox wallets start with 0 KES balance. You need to make a deposit first to fund your wallet. M-Pesa deposits use real transactions, while card deposits use simulated processing with test cards, and PayPal deposits use PayPal's sandbox environment.