# Digital Marketplace - Payment Setup Guide

## Premium Version 2.0

---

## Supported Payment Gateways

1. **PayPal** - Global coverage
2. **Stripe** - Credit/Debit cards worldwide
3. **Paystack** - Africa-focused
4. **Flutterwave** - Africa-focused
5. **PayFast** - South Africa
6. **Ozow / Yoco** - South Africa
7. **Bank Transfer / EFT** - Manual processing
8. **Bitcoin / Cryptocurrency** - Crypto payments

---

## PayPal Setup

### 1. Create PayPal Account

1. Go to [developer.paypal.com](https://developer.paypal.com)
2. Sign up or log in with your PayPal account
3. Switch to "Live" mode for production

### 2. Create App

1. Go to **Dashboard > My Apps & Credentials**
2. Click "Create App"
3. Enter app name (e.g., "Digital Marketplace")
4. Select "Merchant" as app type
5. Click "Create App"

### 3. Get Credentials

Copy the following:
- **Client ID**
- **Secret** (click "Show" to reveal)

### 4. Configure in Admin Panel

1. Go to **Admin > Settings > Payments**
2. Find "PayPal" section
3. Enter:
   - Client ID
   - Secret
   - Mode: Sandbox (for testing) or Live (for production)
4. Enable PayPal
5. Save settings

### 5. Test Payment

**Sandbox Testing:**
1. Use PayPal sandbox buyer account
2. Test purchase flow
3. Verify payment webhook

**Live Testing:**
1. Switch mode to "Live"
2. Make small test purchase
3. Verify funds received

---

## Stripe Setup

### 1. Create Stripe Account

1. Go to [stripe.com](https://stripe.com)
2. Sign up for free account
3. Complete verification

### 2. Get API Keys

1. Go to **Developers > API Keys**
2. Copy:
   - **Publishable key** (pk_test_... or pk_live_...)
   - **Secret key** (sk_test_... or sk_live_...)

### 3. Configure in Admin Panel

1. Go to **Admin > Settings > Payments**
2. Find "Stripe" section
3. Enter:
   - Publishable Key
   - Secret Key
4. Enable Stripe
5. Save settings

### 4. Webhook Setup (Optional but Recommended)

1. Go to **Developers > Webhooks**
2. Click "Add endpoint"
3. Enter URL: `https://yourdomain.com/payments/stripe-webhook.php`
4. Select events:
   - `payment_intent.succeeded`
   - `payment_intent.payment_failed`
5. Copy webhook signing secret
6. Add to config if needed

### 5. Test Payment

1. Use Stripe test card numbers:
   - Success: `4242 4242 4242 4242`
   - Decline: `4000 0000 0000 0002`
2. Any future date for expiry
3. Any 3 digits for CVC
4. Any ZIP code

---

## Paystack Setup

### 1. Create Paystack Account

1. Go to [paystack.com](https://paystack.com)
2. Sign up for business account
3. Complete KYC verification

### 2. Get API Keys

1. Go to **Settings > API Keys**
2. Copy:
   - **Public Key**
   - **Secret Key**

### 3. Configure in Admin Panel

1. Go to **Admin > Settings > Payments**
2. Find "Paystack" section
3. Enter:
   - Public Key
   - Secret Key
4. Enable Paystack
5. Save settings

### 4. Webhook Setup

1. Go to **Settings > Webhooks**
2. Add webhook URL: `https://yourdomain.com/payments/paystack-webhook.php`
3. Select events:
   - `charge.success`
   - `charge.failed`

### 5. Test Payment

Use Paystack test mode with test cards provided in their documentation.

---

## Flutterwave Setup

### 1. Create Flutterwave Account

1. Go [flutterwave.com](https://flutterwave.com)
2. Sign up for business account
3. Complete verification

### 2. Get API Keys

1. Go to **Settings > API**
2. Copy:
   - **Public Key**
   - **Secret Key**
   - **Encryption Key**

### 3. Configure in Admin Panel

1. Go to **Admin > Settings > Payments**
2. Find "Flutterwave" section
3. Enter:
   - Public Key
   - Secret Key
   - Encryption Key
4. Enable Flutterwave
5. Save settings

### 4. Webhook Setup

1. Go to **Settings > Webhooks**
2. Add webhook URL: `https://yourdomain.com/payments/flutterwave-webhook.php`
3. Set secret hash

---

## PayFast Setup (South Africa)

### 1. Create PayFast Account

1. Go to [payfast.co.za](https://www.payfast.co.za)
2. Register as a merchant
3. Complete verification

### 2. Get Credentials

1. Go to **Settings > Integration**
2. Note:
   - **Merchant ID**
   - **Merchant Key**
   - **Passphrase** (if set)

### 3. Configure in Admin Panel

1. Go to **Admin > Settings > Payments**
2. Find "PayFast" section
3. Enter:
   - Merchant ID
   - Merchant Key
   - Passphrase (if applicable)
4. Enable PayFast
5. Save settings

### 4. ITN Setup

1. In PayFast settings, set ITN URL:
   `https://yourdomain.com/payments/payfast-itn.php`
2. Enable ITN notifications

---

## Bank Transfer / EFT Setup

### 1. Enable Payment Method

1. Go to **Admin > Settings > Payments**
2. Find "Bank Transfer" section
3. Enable the payment method

### 2. Enter Bank Details

Fill in your bank information:
- Bank Name
- Account Holder Name
- Account Number
- Branch Code
- SWIFT/BIC Code (for international)
- IBAN (for international)

### 3. Add Instructions

Add payment instructions for customers:
```
Please make payment to the following account:
Bank: [Your Bank]
Account: [Account Number]
Reference: Your Order Number

After payment, please email proof of payment to payments@yourdomain.com
```

### 4. Manual Order Processing

1. Customer places order with "Bank Transfer"
2. Order status: "Pending Payment"
3. Customer makes bank transfer
4. You receive payment notification
5. Go to **Orders** and mark as "Paid"
6. Customer receives download access

---

## Bitcoin / Cryptocurrency Setup

### 1. Choose Provider

Options:
- Coinbase Commerce
- BitPay
- Blockchain.info
- CoinGate

### 2. Coinbase Commerce Setup

1. Create account at [commerce.coinbase.com](https://commerce.coinbase.com)
2. Go to **Settings > API Keys**
3. Create API key
4. Copy API Key

### 3. Configure in Admin Panel

1. Go to **Admin > Settings > Payments**
2. Find "Bitcoin" section
3. Enter:
   - API Key
   - Webhook Secret
4. Enable Bitcoin
5. Save settings

### 4. Webhook Setup

1. In Coinbase Commerce, add webhook:
   `https://yourdomain.com/payments/bitcoin-webhook.php`
2. Select events:
   - `charge:confirmed`
   - `charge:failed`

---

## Testing Payments

### Test Mode Checklist

Before going live:

- [ ] Test each payment gateway in sandbox/test mode
- [ ] Verify order creation
- [ ] Verify payment status updates
- [ ] Test failed payment handling
- [ ] Verify email notifications
- [ ] Test refund process (if applicable)
- [ ] Check webhook functionality

### Test Card Numbers

**Stripe Test Cards:**
- Success: `4242 4242 4242 4242`
- Decline: `4000 0000 0000 0002`
- Insufficient funds: `4000 0000 0000 9995`

**PayPal Sandbox:**
- Use PayPal sandbox accounts
- Create buyer and seller accounts
- Test with sandbox credentials

---

## Going Live

### Pre-Launch Checklist

- [ ] Switch all gateways to "Live" mode
- [ ] Verify live API keys
- [ ] Test live payment (small amount)
- [ ] Confirm webhook URLs are correct
- [ ] Set up payment notifications
- [ ] Configure refund policy
- [ ] Add payment methods to checkout page
- [ ] Test on mobile devices

### Post-Launch Monitoring

1. Monitor payment success rates
2. Check for failed payments
3. Review webhook logs
4. Monitor for fraudulent transactions
5. Keep payment gateway accounts funded

---

## Troubleshooting

### Payment Not Processing

1. Check API keys are correct
2. Verify gateway is enabled
3. Check error logs
4. Test in sandbox mode
5. Contact gateway support

### Webhook Not Working

1. Verify webhook URL is accessible
2. Check SSL certificate is valid
3. Review webhook logs
4. Test webhook manually
5. Check firewall settings

### Orders Not Updating

1. Check webhook configuration
2. Review order status flow
3. Check database connection
4. Review error logs

---

## Security Best Practices

1. **Never commit API keys to version control**
2. **Use environment variables for sensitive data**
3. **Enable webhook signature verification**
4. **Use HTTPS for all payment pages**
5. **Implement fraud detection**
6. **Regularly rotate API keys**
7. **Monitor for suspicious activity**

---

## Support

For payment gateway support:
- PayPal: [developer.paypal.com/support](https://developer.paypal.com/support)
- Stripe: [support.stripe.com](https://support.stripe.com)
- Paystack: [support.paystack.com](https://support.paystack.com)
- Flutterwave: [developer.flutterwave.com](https://developer.flutterwave.com)
- PayFast: [support.payfast.co.za](https://support.payfast.co.za)
