Wallet payments

Pesaswap supports three mobile money wallets in Kenya: M-Pesa Express, Airtel Money, and MTN MoMo. All three use the same request shape — the only thing that changes is payment_method_type. In every case, the customer approves the payment on their own handset; you never collect a PIN or OTP yourself.

You need an API key, a profile_id, and a customer_id before making a wallet payment.

Request

Send a POST request to /payments with payment_method: "wallet" and confirm: true. This creates the payment and immediately confirms it, which triggers the prompt on the customer’s phone. The example below uses M-Pesa Express (m_pesa_express).

curl --request POST \
  --url https://api.sandbox.pesaswap.io/payments \
  --header "api-key: {{api_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 100,
    "currency": "KES",
    "confirm": true,
    "customer_id": "{{customer_id}}",
    "profile_id": "{{profile_id}}",
    "payment_method": "wallet",
    "payment_method_type": "m_pesa_express",
    "phone": "{{phone}}",
    "phone_country_code": "254"
  }'

const response = await fetch("https://api.sandbox.pesaswap.io/payments", {
  method: "POST",
  headers: {
    "api-key": "{{api_key}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 100,
    currency: "KES",
    confirm: true,
    customer_id: "{{customer_id}}",
    profile_id: "{{profile_id}}",
    payment_method: "wallet",
    payment_method_type: "m_pesa_express",
    phone: "{{phone}}",
    phone_country_code: "254",
  }),
});

const payment = await response.json();
console.log(payment);

import requests

response = requests.post(
    "https://api.sandbox.pesaswap.io/payments",
    headers={
        "api-key": "{{api_key}}",
        "Content-Type": "application/json",
    },
    json={
        "amount": 100,
        "currency": "KES",
        "confirm": True,
        "customer_id": "{{customer_id}}",
        "profile_id": "{{profile_id}}",
        "payment_method": "wallet",
        "payment_method_type": "m_pesa_express",
        "phone": "{{phone}}",
        "phone_country_code": "254",
    },
)

payment = response.json()
print(payment)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.sandbox.pesaswap.io/payments",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "api-key: {{api_key}}",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 100,
        "currency" => "KES",
        "confirm" => true,
        "customer_id" => "{{customer_id}}",
        "profile_id" => "{{profile_id}}",
        "payment_method" => "wallet",
        "payment_method_type" => "m_pesa_express",
        "phone" => "{{phone}}",
        "phone_country_code" => "254",
    ]),
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

To use a different wallet, change payment_method_type and currency — everything else in the request stays the same.

Wallet	`payment_method_type`	Currency	Notes
M-Pesa Express	`m_pesa_express`	`KES`	STK push; customer approves on handset
Airtel Money	`airtel_money`	`KES`	Customer approves on handset
MTN MoMo	`momo_mtn`	`EUR`	Customer approves on handset

Response

A successful call returns a 200 with a payment object. The fields that matter right now:

{
  "payment_id": "pay_...",
  "status": "requires_customer_action",
  "amount": 100,
  "currency": "KES"
}

The money has not moved yet. status: requires_customer_action means the prompt is now on the customer’s phone, waiting for them to approve or decline. Nothing settles until they respond.

What to do next

Poll GET /payments/{payment_id}?force_sync=true until the status settles. See the quickstart for the full polling loop.

force_sync defaults to false. Without it, this endpoint returns the last stored status — it does not contact the connector. If you omit force_sync=true, your polling loop will keep reading a stale requires_customer_action status and will never see the payment settle.

Status reference

Status	What it means	What to do
`requires_customer_action`	The prompt is on the customer’s handset.	Keep polling.
`processing`	The customer has responded and the connector is finalizing the result.	Keep polling.
`succeeded`	The payment settled. The money has moved.	Stop — settled.
`failed`	The customer declined, the prompt timed out, or the connector rejected the payment.	Stop — failed.

Common errors

Wrong phone_country_code

It is a separate field from phone — do not prefix the number with the country code yourself. Sending 254 in both phone and phone_country_code will send the prompt to the wrong number or fail validation.

Wallet not enabled on the profile

Each wallet (M-Pesa Express, Airtel Money, MTN MoMo) has to be connected on the profile_id you’re using. A request for a wallet that isn’t configured fails before any prompt is sent.

Customer doesn't respond

If the customer ignores the prompt, the payment stays in requires_customer_action until the prompt expires, then moves to failed. There’s nothing to retry on your side except creating a new payment.

Next steps

Quickstart

The full create-and-poll payment loop.

Card payments and 3DS

Accept cards with 3DS redirects.

Mandates and recurring

Save a wallet for repeat charges.

Refunds

Refund a settled wallet payment.

About Pesaswap

Payments Guide

Account Setup

Use Cases

Explore Pesaswap

Checklist for Production

FAQ

Request

Response

What to do next

Status reference

Common errors

Next steps

Quickstart

Card payments and 3DS

Mandates and recurring

Refunds

​Request

​Response

​What to do next

​Status reference

​Common errors

​Next steps

Quickstart

Card payments and 3DS

Mandates and recurring

Refunds

Request

Response

What to do next

Status reference

Common errors

Next steps