# Installation Guide

## Quick Start

### 1. Download and Install

1. Download the plugin zip file
2. Log into your WordPress admin panel
3. Navigate to **Plugins > Add New**
4. Click **Upload Plugin**
5. Choose the zip file and click **Install Now**
6. Activate the plugin

### 2. Basic Configuration

1. Navigate to **WooCommerce > Settings > Payments**
2. Find "RedPay" and click **Set up**
3. Check **Enable RedPay**
4. Configure the basic settings:
   - **Title**: What customers see at checkout
   - **Description**: Payment method description
   - **Test Mode**: Enable for testing

### 3. API Setup

1. Get your API credentials from [RedPay API keys](https://gateway-merchant.redpay.africa/app/api-keys)
2. In the plugin settings:
   - **Test API Key**: Your test environment key
   - **Test API Secret**: Your test environment secret
   - **Live API Key**: Your production key (when ready)
   - **Live API Secret**: Your production secret (when ready)

### 4. Webhook Configuration

1. Copy the webhook URL from the plugin settings
2. In your RedPay dashboard:
   - Go to webhook settings
   - Add new webhook with the copied URL
   - Copy the webhook secret
3. Paste the webhook secret in plugin settings

### 5. Test the Setup

1. Ensure **Test Mode** is enabled
2. Place a test order using test card numbers
3. Verify payment processing works correctly
4. Check webhook notifications are received

## Detailed Setup

### Prerequisites

Before installing the plugin, ensure your site meets these requirements:

- **WordPress**: 5.0 or higher
- **WooCommerce**: 5.0 or higher  
- **PHP**: 7.4 or higher
- **SSL Certificate**: Required for live payments
- **RedPay merchant account**: [Sign up here](https://gateway-merchant.redpay.africa/onboard/signup)

### Installation Methods

#### Method 1: WordPress Admin (Recommended)

1. Download the plugin zip file
2. In WordPress admin, go to **Plugins > Add New**
3. Click **Upload Plugin**
4. Choose the zip file and install
5. Activate the plugin

#### Method 2: FTP Upload

1. Extract the plugin zip file
2. Upload the `redpay-payment-gateway` folder to `/wp-content/plugins/`
3. In WordPress admin, activate the plugin

#### Method 3: WP-CLI

```bash
wp plugin install redpay-payment-gateway.zip --activate
```

### Configuration Steps

#### Step 1: Enable the Gateway

1. Go to **WooCommerce > Settings > Payments**
2. Find "RedPay" in the list
3. Click **Set up** or the toggle to enable
4. You'll be redirected to the configuration page

#### Step 2: Basic Settings

Configure these essential settings:

- **Enable RedPay**: Check this box
- **Title**: "Credit Card" or "RedPay"
- **Description**: "Pay securely with your credit card"

#### Step 3: API Credentials

Get your credentials from your merchant account:

1. Log into [RedPay](https://gateway-merchant.redpay.africa/) and go to [API keys](https://gateway-merchant.redpay.africa/app/api-keys)
2. Copy your Test and Live public/secret keys

In WordPress:
- **Test API Key**: Paste your test key
- **Test API Secret**: Paste your test secret
- **Live API Key**: Paste your live key (for production)
- **Live API Secret**: Paste your live secret (for production)

#### Step 4: Test Mode Configuration

For development and testing:

1. Check **Enable Test Mode**
2. Ensure test credentials are entered
3. Save settings

#### Step 5: Webhook Setup

Webhooks provide real-time payment updates:

1. In plugin settings, copy the **Webhook URL**
2. In your RedPay dashboard:
   - Go to **Webhooks** section
   - Click **Add Webhook**
   - Paste the URL
   - Select events: `payment.completed`, `payment.failed`, `payment.refunded`
   - Save and copy the generated secret
3. Paste the webhook secret in WordPress settings

### Testing

#### Test Cards

Use these test card numbers in test mode:

| Card Type | Number | CVV | Expiry |
|-----------|--------|-----|--------|
| Visa | 4111111111111111 | 123 | 12/25 |
| Visa (Declined) | 4000000000000002 | 123 | 12/25 |
| Mastercard | 5555555555554444 | 123 | 12/25 |
| American Express | 378282246310005 | 1234 | 12/25 |
| Discover | 6011111111111117 | 123 | 12/25 |

#### Test Scenarios

1. **Successful Payment**
   - Use valid test card
   - Complete checkout
   - Verify order status changes to "Processing"

2. **Failed Payment**
   - Use declined test card (4000000000000002)
   - Verify error message appears
   - Order should remain "Pending"

3. **Webhook Testing**
   - Complete test payment
   - Check order notes for webhook confirmations
   - Verify real-time status updates

#### Debugging

Enable debug logging:

1. In plugin settings, enable **Debug Mode**
2. Check logs at **WooCommerce > Status > Logs**
3. Select "RedPay" or "redpay" logs

### Going Live

#### Pre-Launch Checklist

- [ ] SSL certificate installed and working
- [ ] Live API credentials configured
- [ ] Webhook configured with live account
- [ ] Test mode disabled
- [ ] Test payments completed successfully
- [ ] Error handling tested
- [ ] Refund process tested

#### Launch Steps

1. **Disable Test Mode**
   - Uncheck **Enable Test Mode**
   - Save settings

2. **Verify Live Credentials**
   - Ensure live API key and secret are correct
   - Test connection if available

3. **Update Webhook**
   - Use live webhook URL in your live account
   - Update webhook secret if different

4. **Final Testing**
   - Process a small live transaction
   - Verify webhook notifications
   - Test refund process

### Troubleshooting

#### Common Issues

**"Gateway not available"**
- Ensure WooCommerce is activated
- Check plugin is enabled
- Verify API credentials

**"SSL Required"**
- Install SSL certificate
- Update WordPress URLs to HTTPS
- Verify certificate is valid

**"Payment Failed"**
- Check API credentials
- Verify test/live mode settings
- Review error logs

**"Webhook Not Working"**
- Verify webhook URL is accessible
- Check webhook secret matches
- Review webhook logs in merchant dashboard

#### Debug Information

The plugin provides debug information at:
**RedPay gateway** (WooCommerce > Settings > Payments > RedPay, or the RedPay dashboard if you use it)

This shows:
- Plugin version
- WordPress/WooCommerce versions
- PHP version
- SSL status
- Gateway configuration status

### Support

#### Getting Help

- **Documentation**: [RedPay documentation](https://gateway-documentation.redpay.africa/#/)
- **Support**: [RedPay](https://redpay.africa/)

#### Before Contacting Support

Please provide:
1. WordPress and WooCommerce versions
2. Plugin version
3. Error messages or screenshots
4. Steps to reproduce the issue
5. Whether it's test or live mode

#### Known Limitations

- Requires WooCommerce
- SSL required for live payments
- Some hosting providers may block webhook calls
- Minimum PHP 7.4 required

## Advanced Configuration

### Custom Hooks

The plugin provides hooks for customization:

```php
// Modify payment form
add_filter('redpay_payment_gateway_form_fields', 'custom_form_fields');

// Custom validation
add_filter('redpay_payment_gateway_validate_payment', 'custom_validation');

// Modify API request
add_filter('redpay_payment_gateway_api_request', 'custom_api_request');
```

### Custom Styling

Override styles by adding to your theme's CSS:

```css
#redpay-payment-gateway-form {
    /* Your custom styles */
}
```

### Multi-Site Setup

For WordPress multisite:
1. Network activate the plugin
2. Configure separately on each site
3. Each site needs its own API credentials