# Updated Payment API - Quick Test

## ✅ Updated Payload Format

The public payment API now requires **4 fields** including phone_number:

```json
{
  "client_id": "1fa69aeb-568e-4a14-92ae-7b50fa75e0fe",
  "package_id": "7c92d779-a4ba-4e33-82e4-cb0d2e664ab9", 
  "phone_number": "+254712345678",
  "description": "Payment description"
}
```

### Field Details:

| Field | Type | Example | Notes |
|-------|------|---------|-------|
| `client_id` | UUID | `1fa69aeb-568e-4a14-92ae-7b50fa75e0fe` | Client identifier |
| `package_id` | UUID | `7c92d779-a4ba-4e33-82e4-cb0d2e664ab9` | Internet package to purchase |
| `phone_number` | String | `+254712345678` | M-Pesa phone number (format: +254xxxxxxxxx) |
| `description` | String | `Payment description` | Transaction description |

---

## 🧪 Test with cURL

```bash
curl -X POST http://localhost:8080/api/v1/payments/initiate \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "1fa69aeb-568e-4a14-92ae-7b50fa75e0fe",
    "package_id": "7c92d779-a4ba-4e33-82e4-cb0d2e664ab9",
    "phone_number": "+254712345678",
    "description": "Payment description"
  }'
```

---

## 📋 Response Format

**Success (200 OK):**
```json
{
  "transaction_id": "770e8400-e29b-41d4-a716-446655440002",
  "checkout_id": "abc123xyz456",
  "message": "Payment initiated successfully",
  "status": "pending"
}
```

**Save the `checkout_id`** for status checking later.

---

## 🔍 Check Status

Once you have the `checkout_id`, check status with:

```bash
curl -X POST http://localhost:8080/api/v1/payments/status \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "1fa69aeb-568e-4a14-92ae-7b50fa75e0fe",
    "checkout_id": "abc123xyz456"
  }'
```
**Response (Status queried directly from Safaricom):**
```json
{
  "transaction_id": "e60288d4-e97c-45dd-a64a-cab33e20b693",
  "checkout_id": "6RRGlABSLndXeT_xh7grvA==",
  "status": "completed",
  "amount": 500,
  "reference": "STARTER-PL-20260128172108-8BoAUA",
  "phone_number": "254740782174"
}
```
---

## 🎯 Seeded Test Data

### Client (TechCorp Kenya)
```
ID: 1fa69aeb-568e-4a14-92ae-7b50fa75e0fe
Phone: +254712345678
Email: admin@techcorp.ke
```

### Packages (for this client)
```
1. Starter (10Mbps, 500 KES)
   ID: 7c92d779-a4ba-4e33-82e4-cb0d2e664ab9

2. Professional (50Mbps, 1500 KES)
   ID: 681ac607-811a-4cbe-b84a-bf010d6c737b

3. Enterprise (100Mbps, 5000 KES)
   ID: 44abb3ed-c9a9-4332-9ace-e11d9fb888d8
```

---

## ✨ What's New

✅ **Phone number is now a required field** in the payload
✅ **More flexible** - Different phone numbers can make payments
✅ **Better control** - You decide which phone receives the STK prompt
✅ **Validation** - Phone number is validated and formatted automatically
✅ **Error handling** - Clear error if phone number format is invalid

---

## 🚀 Next Steps

1. Run the application: `go run main.go`
2. Test the endpoint with your desired phone number
3. M-Pesa STK prompt will be sent to that phone number
4. Monitor the callback from M-Pesa
5. Check payment status using the `checkout_id`

---

## 📖 Full Documentation

See `docs/PUBLIC_PAYMENT_API.md` for complete documentation with all examples and error codes.