# Yo Uganda Mobile Money Integration

## Setup Instructions

To enable Mobile Money donations through the Yo Uganda API, add the following constants to your `wp-config.php` file:

```php
// Yo Uganda API Configuration
define( 'YO_UGANDA_API_KEY', 'your_api_key_here' );
define( 'YO_UGANDA_VENDOR_ID', 'your_vendor_id_here' );
```

## Getting Yo Uganda Credentials

1. Visit [Yo Uganda Developer Portal](https://developer.yo.co.ug)
2. Create an account or sign in
3. Create a new application/integration
4. Generate API credentials
5. Note your API Key and Vendor ID
6. Add them to your `wp-config.php` as shown above

## API Flow

1. **User Initiates Donation**: User fills donation form and selects Mobile Money
2. **Record Saved**: Donation record is saved to database with status "pending"
3. **Mobile Prompt**: Yo Uganda API sends USSD prompt to user's phone
4. **User Confirms**: User enters Mobile Money PIN to confirm transaction
5. **Async Callback**: Yo Uganda API response is processed asynchronously
6. **Record Updated**: Upon success, record status changes to "completed" and donation totals are updated

## Mobile Money Status Flow

- **pending**: Initial state, waiting for user confirmation on phone
- **completed**: Transaction was successful, funds received
- **failed**: Transaction was declined or cancelled

## Transaction Tracking

Each transaction includes:
- Unique external reference: `DONATION_{record_id}_{timestamp}`
- Transaction ID from Yo Uganda API
- Phone number used for the transaction
- Amount in UGX

## Error Handling

If Yo Uganda API is not configured:
- Error message: "Yo Uganda API credentials not configured"
- Donation record is still saved as pending
- User is notified to contact support

If API call fails:
- Donation record status is marked as "failed"
- User receives error message
- Record can be manually reviewed and retried if needed

## Async Processing

Mobile Money payment processing happens asynchronously:
- Frontend: User sees confirmation dialog after clicking "Proceed to Payment"
- Backend: Donation record saved immediately with "pending" status
- Backend: Yo Uganda API call happens async without blocking user interface
- Frontend: Results are displayed in confirmation modal as they arrive
- Database: Only "completed" transactions update the campaign donation totals