Accept your first payment

This page walks through the shortest path to a real M-Pesa Express payment: create the payment, let the customer approve it on their phone, then poll until it settles.

Prerequisites

You need:

An API key from the Pesaswap dashboard.
A profile_id from the dashboard.
A phone number that can receive an M-Pesa STK prompt.

Creating a merchant account, generating an API key, and setting up a connector are covered elsewhere in these docs — this page assumes you already have all three.

Create and confirm the payment

Send a POST request to /payments with confirm: true. This creates the payment and immediately attempts to confirm it in one call, so a customer-facing STK prompt is triggered as soon as the request returns.

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;

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

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

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

The customer approves

The customer sees the STK push notification on their handset and enters their M-Pesa PIN. Nothing else for you to build here — this happens on their phone, outside your API calls.

Poll for the result

Once the customer has approved (or rejected, or ignored) the prompt, retrieve the payment to find out what happened. Use force_sync=true so the request checks with the connector instead of returning a stale status.

curl --request GET \
  --url "https://api.sandbox.pesaswap.io/payments/{payment_id}?force_sync=true" \
  --header "api-key: {{api_key}}"

const response = await fetch(
  `https://api.sandbox.pesaswap.io/payments/${paymentId}?force_sync=true`,
  {
    method: "GET",
    headers: {
      "api-key": "{{api_key}}",
    },
  }
);

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

import requests

response = requests.get(
    f"https://api.sandbox.pesaswap.io/payments/{payment_id}",
    params={"force_sync": "true"},
    headers={"api-key": "{{api_key}}"},
)

payment = response.json()
print(payment)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.sandbox.pesaswap.io/payments/{$paymentId}?force_sync=true",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "api-key: {{api_key}}",
    ],
]);

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

echo $response;

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`	Waiting on the customer to respond to the prompt.	Keep polling.
`processing`	The connector is finalizing the result.	Keep polling.
`succeeded`	The payment settled. The money has moved.	Stop — settled.
`failed`	The customer declined, the PIN was wrong too many times, or the prompt timed out.	Stop — failed.

You may also see other values from the full status set (requires_confirmation, requires_payment_method, requires_merchant_action, cancelled, requires_capture, partially_captured, partially_captured_and_capturable) depending on the payment method and configuration, but a straightforward M-Pesa Express flow moves through requires_customer_action → processing → succeeded or failed.

Next steps

Wallet payments

M-Pesa Express, Airtel Money, and MTN MoMo in one place.

Card payments and 3DS

Cards, redirects, and authentication.

Mandates and recurring

Save a payment method and charge it later.

Refunds

Send money back to a customer.

Payouts

Send money out to a recipient.

About Pesaswap

Payments Guide

Account Setup

Use Cases

Explore Pesaswap

Checklist for Production

FAQ

Accept your first payment

Prerequisites

Status reference

Next steps

Wallet payments

Card payments and 3DS

Mandates and recurring

Refunds

Payouts

​Prerequisites

​Status reference

​Next steps

Wallet payments

Card payments and 3DS

Mandates and recurring

Refunds

Payouts

Prerequisites

Status reference

Next steps