# M-Pesa STK Push (Kenya)

This sends an M-Pesa prompt to the customer's phone. They enter their PIN and the funds arrive in your KES wallet.

**cURL**

```bash
curl -X POST https://api.intasend.com/api/v1/payment/mpesa-stk-push/ \
  -H "Authorization: Bearer $INTASEND_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "phone_number": "254712345678", "api_ref": "order-123"}'
```

**Python**

```python
resp = requests.post(
    "https://api.intasend.com/api/v1/payment/mpesa-stk-push/",
    headers={"Authorization": f"Bearer {SECRET_KEY}"},
    json={"amount": 100, "phone_number": "254712345678", "api_ref": "order-123"},
)
invoice_id = resp.json()["invoice"]["invoice_id"]
```

**Node.js**

```js
const res = await fetch('https://api.intasend.com/api/v1/payment/mpesa-stk-push/', {
  method: 'POST',
  headers: {Authorization: `Bearer ${SECRET_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({amount: 100, phone_number: '254712345678', api_ref: 'order-123'}),
});
const {invoice} = await res.json();
```

## Request

| Field | Required | Description |
|---|---|---|
| `amount` | Yes | Amount in KES. It is rounded up to a whole shilling. |
| `phone_number` | Yes | `2547XXXXXXXX`, `2541XXXXXXXX`, `07XXXXXXXX` or `01XXXXXXXX`. Digits only. |
| `api_ref` | No | Your reference, for example an order ID. It is returned on the invoice and in webhooks. |
| `wallet_id` | No | KES wallet to credit. Defaults to your settlement wallet. |
| `mobile_tarrif` | No | `BUSINESS-PAYS` or `CUSTOMER-PAYS`. |

## Response

```json
{
  "id": "5b9d…",
  "invoice": {"invoice_id": "ABC123", "state": "PENDING", "provider": "M-PESA", "value": 100, "account": "254712345678", "api_ref": "order-123"},
  "customer": {"customer_id": "…", "phone_number": "254712345678"},
  "created_at": "…"
}
```

Then track the payment with [payment status](https://developers.intasend.com/guides/collections/overview/#check-payment-status) or the `collection_event` [webhook](https://developers.intasend.com/guides/webhooks/).

## Common failures

| `failed_code` | Meaning | What to do |
|---|---|---|
| `1032` | The customer cancelled the prompt | Ask them to try again |
| `1037` | The phone couldn't be reached (off, no network, or an old SIM) | The customer may get paybill instructions to pay manually |
| `1` | Insufficient M-Pesa balance | |
| `2001` | Wrong PIN | |