# Flutterwave Integration - Quick Reference

## Configuration (Required Before Using)

```bash
# Option 1: WordPress CLI
wp option add flutterwave_public_key "your_public_key_here"
wp option add flutterwave_secret_key "your_secret_key_here"

# Option 2: wp-config.php
define('FLUTTERWAVE_PUBLIC_KEY', 'your_public_key_here');
define('FLUTTERWAVE_SECRET_KEY', 'your_secret_key_here');
```

## AJAX Endpoints

### Get Public Key
- **URL:** `/wp-admin/admin-ajax.php?action=get_flutterwave_key`
- **Method:** POST
- **Response:** `{ "public_key": "PK_...", "error": null }`

### Verify Payment
- **URL:** `/wp-admin/admin-ajax.php?action=verify_flutterwave_payment`
- **Method:** POST
- **Payload:**
  ```json
  {
    "record_id": 42,
    "transaction_id": "1234567890",
    "tx_ref": "DONATION_42_1699987654"
  }
  ```
- **Response:** `{ "success": true, "message": "Payment verified" }`

## Frontend Flow

```javascript
// Card Payment Submission
$form.on('submit', function(e) {
  e.preventDefault();
  processCardPayment($form);
  // → Saves record
  // → Gets Flutterwave key
  // → Opens modal
  // → Verifies payment
});
```

## Database Records

Sample donation record after card payment:
```sql
INSERT INTO wp_missinterschools_donors (
  donation_id, donor_name, donor_phone, 
  donation_amount, payment_method, 
  transaction_id, status, created_at
) VALUES (
  5, 'John Doe', '+256701234567', 
  50000, 'card', 
  '1234567890', 'completed', NOW()
);
```

## Test Credentials

| Card Type | Number | Expiry | CVV |
|-----------|--------|--------|-----|
| Success | 4242 4242 4242 4242 | 12/25 | 123 |
| Decline | 5555 5555 5555 4444 | 12/25 | 123 |

## Files Modified

1. **`/js/donation.js`** - Frontend payment logic
   - 5 new functions: processCardPayment, initializeFlutterwaveCheckout, launchFlutterwaveCheckout, verifyFlutterwavePayment, submitMobileMoneyForm
   - Removed direct card capture fields

2. **`/includes/class-missinterschools-donation.php`** - Backend handlers
   - `get_flutterwave_key()` - Returns API key
   - `verify_flutterwave_payment()` - Verifies transaction

3. **`/includes/class-missinterschools.php`** - Hook registration
   - 4 AJAX hooks registered for Flutterwave actions

## Payment Statuses

- **Card (Flutterwave)**: `completed` (immediately, verified async)
- **Mobile Money (Yo Uganda)**: `pending` → `completed` (after Yo confirmation)

## Error Handling

### Common Issues

| Issue | Solution |
|-------|----------|
| "Failed to get Flutterwave key" | Verify `flutterwave_public_key` is in wp_options |
| "Payment verification failed" | Check `flutterwave_secret_key` and API connectivity |
| "SSL certificate error" | `sslverify` is disabled for development |
| "Transaction reference mismatch" | Verify tx_ref format: `DONATION_{id}_{timestamp}` |

## Currencies

- **Currency Code:** UGX (Uganda Shilling)
- **Amount Format:** In cents (e.g., 50,000 UGX = 5000000)
- **Minimum Amount:** Check Flutterwave limits

## API Endpoint

```
GET https://api.flutterwave.com/v3/transactions/{transaction_id}/verify
Authorization: Bearer {FLUTTERWAVE_SECRET_KEY}

Response: {
  "status": "success",
  "data": {
    "id": 12345678,
    "status": "successful",
    "amount": 50000,
    "currency": "UGX"
  }
}
```

## Documentation Files

- **Setup Guide:** `/FLUTTERWAVE_CONFIG.md`
- **Completion Summary:** `/FLUTTERWAVE_COMPLETION.md`
- **This File:** `/FLUTTERWAVE_QUICKREF.md`

---

**Last Updated:** November 22, 2024  
**Status:** Ready for Testing  
**Version:** Phase 4 Complete