# Paystack Payment Integration Setup Guide

This guide will help you set up Paystack payment processing for your TellerPro application.

## 1. Get Your Paystack API Keys

1. Sign up or log in to your [Paystack Dashboard](https://dashboard.paystack.com/)
2. Go to **Settings** > **API Keys**
3. Copy your **Test Public Key** and **Test Secret Key**
4. For production, you'll need the **Live Public Key** and **Live Secret Key**

## 2. Configure Paystack Settings

Edit `config/paystack.php` and add your API keys:

```php
// Test Environment
'test' => [
    'public_key' => 'pk_test_your_test_public_key_here',
    'secret_key' => 'sk_test_your_test_secret_key_here',
    // ...
],

// Live Environment (for production)
'live' => [
    'public_key' => 'pk_live_your_live_public_key_here',
    'secret_key' => 'sk_live_your_live_secret_key_here',
    // ...
],
```

## 3. Run Database Migration

Run the migration script to add Paystack columns to your database:

```bash
php database/migrations/add_paystack_columns.php
```

Or execute the SQL manually:

```sql
-- Add to subscriptions table
ALTER TABLE subscriptions 
ADD COLUMN payment_method ENUM('manual','paystack','stripe') DEFAULT 'manual',
ADD COLUMN paystack_reference VARCHAR(100) NULL,
ADD COLUMN paystack_subscription_code VARCHAR(100) NULL,
ADD COLUMN paystack_customer_code VARCHAR(100) NULL;

-- Add to plans table  
ALTER TABLE plans 
ADD COLUMN paystack_plan_code VARCHAR(100) NULL;
```

## 4. Configure Webhook URL

In your Paystack Dashboard:

1. Go to **Settings** > **Webhooks**
2. Add your webhook URL: `https://yourdomain.com/billing/webhook`
3. Select the events you want to receive:
   - `invoice.payment_success`
   - `invoice.payment_failed`
   - `subscription.create`
   - `subscription.disable`

## 5. Test the Integration

1. Make sure you're using test keys (environment set to 'test' in config)
2. Go to the billing page in your app
3. Try upgrading to a paid plan
4. Use Paystack test cards for testing:
   - Card Number: `50606 66666 66666 6666`
   - Expiry: Any future date
   - CVV: Any 3 digits
   - PIN: `3310`

## 6. Features Implemented

### Payment Methods
- **Paystack Inline**: Modal payment flow on the same page
- **Paystack Standard**: Redirect to Paystack payment page
- **Webhook Processing**: Automatic subscription status updates

### Subscription Management
- One-time payments and recurring subscriptions
- Automatic payment verification
- Subscription status tracking
- Cancellation support

### Security
- Webhook signature validation
- CSRF protection
- Secure API key handling

## 7. Production Checklist

Before going live:

1. [ ] Switch to live API keys in config
2. [ ] Update webhook URL to production domain
3. [ ] Test with real payment methods
4. [ ] Set up proper error monitoring
5. [ ] Configure email notifications for payment failures
6. [ ] Test subscription cancellation flow

## 8. Troubleshooting

### Common Issues

**"Payment initialization failed"**
- Check your secret key is correct
- Verify your callback URL is accessible
- Ensure the plan exists in database

**"Webhook unauthorized"**
- Verify webhook URL is correct in Paystack dashboard
- Check webhook signature validation
- Ensure your server can receive POST requests

**"Transaction verification failed"**
- Check reference is passed correctly from callback
- Verify transaction exists in Paystack system
- Check network connectivity to Paystack API

### Test Cards

Use these test cards for testing:

```
Success Card: 50606 66666 66666 6666
Fail Card:    50606 66666 66666 6665
3DS Card:     50606 66666 66666 6664
```

For more test cards and scenarios, visit the [Paystack Test Documentation](https://paystack.com/docs/guides/testing).

## 9. Support

If you encounter issues:

1. Check Paystack dashboard for transaction logs
2. Review your application logs
3. Verify webhook delivery in Paystack dashboard
4. Test with different payment methods

## 10. Next Steps

Consider implementing:

- Email notifications for payment events
- Invoice generation and PDF downloads
- Multiple payment method support
- Advanced subscription management features
- Analytics and reporting for payments
