# Setup Instructions
## 1. Plugin credentials
Go to your app → **Plugins → MPESA (Mobile)** and fill in:

| Field | Value |
|---|---|
| `consumer_key` | Daraja app Consumer Key |
| `consumer_secret` | Daraja app Consumer Secret |
| `business_short_code` | Your till / pay bill number |
| `passkey` | Lipa Na M-Pesa Passkey |
| `use_sandbox` | `true` for testing, `false` for live |

---

## 2. Create a Payment record in your DB

Add a **Payment** data type with fields: `phone_number` (text), `amount` (number), `checkout_request_id` (text), `status` (text: pending / paid / cancelled).

---

## 3. Backend workflow — Initiate Payment

Create a backend workflow `initiate_mpesa_payment` with parameters `phone_number`, `amount`, `payment_id`.

**Action 1 — MPesa STK Push:**
- `phone_number` → parameter
- `amount` → parameter
- `party_b` → your till number
- `transaction_type` → `CustomerBuyGoodsOnline`
- `callback_url` → your webhook URL
- `account_reference` → your app name (max 12 chars)

**Action 2 — Make changes to Payment** (find by `payment_id`):
- Set `checkout_request_id` → Step 1's result
- Set `status` → `pending`

---

## 4. Frontend button workflow

1. **Create Payment** — create a new Payment record, save as a state
2. **Schedule API Workflow** → `initiate_mpesa_payment`, When: now, pass phone/amount/payment ID
3. **Show message** → "Check your phone to complete payment"

---

## 5. Callback (payment confirmation)

M-Pesa POSTs the result to your `callback_url` when the customer pays or cancels.

**Bubble option:** Enable Workflow API in Settings → API. Create a backend workflow `mpesa_callback` (no auth required). Add parameters `checkout_request_id`, `result_code`, `mpesa_receipt`. Inside, find the matching Payment and update its status.

Use this as your callback URL:
```
https://your-app.bubbleapps.io/api/1.1/wf/mpesa_callback
```

**Result codes:** `0` = paid · `1032` = cancelled · `1037` = timeout · `2001` = wrong PIN

---

## 6. Query status (optional)

Create a backend workflow `check_payment_status` with parameters `checkout_request_id`, `payment_id`.

**Action 1 — MPesa STK Push Query:** pass `checkout_request_id`

**Action 2 — Make changes to Payment:** update status based on `result_code`.