# Payment Gateways

## 40+ Supported Gateways

MailTrixy supports over 40 payment gateways through a unified payment system. You can enable multiple gateways simultaneously, giving your users the freedom to pay with their preferred method.

Supported gateway categories include:

- International: Stripe, PayPal, Paddle, Lemon Squeezy, Razorpay, Paystack, Flutterwave, Mollie, 2Checkout
- Regional (Asia): PhonePe, Paytm, Instamojo, Midtrans, Xendit, GCash
- Regional (Africa): Paystack, Flutterwave, M-Pesa, Chipper Cash
- Regional (Latin America): MercadoPago, PagSeguro, Conekta
- Regional (Middle East): Tap, PayTabs, Fawry, Telr
- Crypto: Coinbase Commerce, NOWPayments, BTCPay Server
- Bank Transfer: Manual/offline payment with admin approval

To enable a gateway, go to Admin Panel → Payment Gateways and click the toggle for each gateway you want to activate.

## Step 1: Create a Stripe Account

If you do not already have a Stripe account, follow these steps:

1. Visit dashboard.stripe.com/register and sign up with your email.
2. Complete the onboarding process by providing your business details, bank account, and identity verification.
3. Stripe will review your account. Most accounts are approved instantly, but some may take 1-2 business days.
4. Once approved, you will have access to both Test mode and Live mode from the Stripe Dashboard.

> Tip: You can start integrating with MailTrixy immediately using Test mode keys while your account is being reviewed.

## Step 2: Get API Keys (Test + Live)

Stripe provides two sets of API keys -- one for testing and one for production.

1. Log in to the Stripe Dashboard.
2. Navigate to Developers → API Keys.
3. You will see two keys:
   - Publishable Key -- starts with `pk_test_` (test) or `pk_live_` (live)
   - Secret Key -- starts with `sk_test_` (test) or `sk_live_` (live)
4. Copy both keys. The Secret Key is only shown once -- store it securely.

To toggle between Test and Live keys, use the "Test mode" toggle switch in the top-right corner of the Stripe Dashboard.

Key Type | Test Mode Prefix | Live Mode Prefix | Purpose
--- | --- | --- | ---
Publishable Key | pk_test_ | pk_live_ | Used on the client side (checkout forms)
Secret Key | sk_test_ | sk_live_ | Used on the server side (never expose publicly)

> Security Warning: Never commit your Secret Key to version control or expose it in client-side code. The Secret Key grants full access to your Stripe account.

## Step 3: Configure Stripe in MailTrixy

Once you have your API keys, configure them in the MailTrixy admin panel:

1. Log in to your MailTrixy instance as an administrator.
2. Navigate to Admin Panel → Payment Gateways → Stripe.
3. Toggle the Enable Stripe switch to activate the gateway.
4. Enter the following credentials:
   - Publishable Key: Paste your `pk_test_` or `pk_live_` key
   - Secret Key: Paste your `sk_test_` or `sk_live_` key
5. Select the Mode dropdown: choose `Test` for development or `Live` for production.
6. Click Save Settings.

MailTrixy will validate the keys by making a test API call to Stripe. If the keys are invalid, you will see an error message.

## Step 4: Setup Webhook Endpoint

Webhooks (automated notifications — when a payment event happens in Stripe, it instantly sends the details to your MailTrixy server so records stay in sync) allow Stripe to notify MailTrixy about payment events in real-time (successful payments, failed charges, subscription changes, etc.).

1. In the Stripe Dashboard, go to Developers → Webhooks.
2. Click Add Endpoint.
3. Set the Endpoint URL to:

       https://yourdomain.com/stripe/webhook

   Replace `yourdomain.com` with your actual MailTrixy domain.
4. Under Events to send, select the following events:
   - `checkout.session.completed`
   - `invoice.payment_succeeded`
   - `invoice.payment_failed`
   - `customer.subscription.created`
   - `customer.subscription.updated`
   - `customer.subscription.deleted`
   - `payment_intent.succeeded`
   - `payment_intent.payment_failed`
5. Click Add Endpoint to save.
6. After the endpoint is created, click on it to reveal the Signing Secret (starts with `whsec_`).
7. Copy the Signing Secret and paste it into MailTrixy Admin Panel → Payment Gateways → Stripe → Webhook Signing Secret.
8. Click Save Settings in MailTrixy.

> Important: The webhook endpoint must be publicly accessible over HTTPS. If you are testing locally, use a tool like ngrok to expose your local server, or use the Stripe CLI to forward events.

You can verify the webhook is working by clicking Send test webhook in the Stripe Dashboard. MailTrixy will log the event in Admin Panel → System Logs.

## Step 5: Create Plans with Stripe Price IDs

MailTrixy subscription plans must be linked to Stripe Price objects for billing to work correctly.

### Create Products and Prices in Stripe

1. In the Stripe Dashboard, go to Products → Add Product.
2. Enter the product name (e.g., "MailTrixy Pro Plan").
3. Under Pricing, add one or more prices:
   - Set the billing period (Monthly, Yearly, etc.).
   - Set the price amount and currency.
   - Choose Recurring for subscription plans.
4. Click Save product.
5. Copy the Price ID (starts with `price_`) for each price you created.

### Link Prices to MailTrixy Plans

1. In MailTrixy, go to Admin Panel → Plans & Subscriptions.
2. Create a new plan or edit an existing one.
3. In the Stripe Price ID (Monthly) field, paste the monthly price ID (e.g., `price_1N2abc...`).
4. In the Stripe Price ID (Yearly) field, paste the yearly price ID if applicable.
5. Configure the plan features, limits, and other settings.
6. Click Save Plan.

MailTrixy Plan | Stripe Price ID (Monthly) | Stripe Price ID (Yearly) | Amount
--- | --- | --- | ---
Starter | price_1N2starter_mo | price_1N2starter_yr | $19/mo or $190/yr
Pro | price_1N2pro_mo | price_1N2pro_yr | $49/mo or $490/yr
Enterprise | price_1N2ent_mo | price_1N2ent_yr | $99/mo or $990/yr

> Note: You must create separate Stripe products/prices for test mode and live mode. Test mode prices will not work in live mode and vice versa.

## Step 6: Test Mode vs Live Mode

Always test your payment integration thoroughly before going live.

### Test Mode

- Uses keys prefixed with `pk_test_` and `sk_test_`.
- No real money is charged. All transactions are simulated.
- Use Stripe's test card numbers to simulate different scenarios:

Card Number | Scenario
--- | ---
4242 4242 4242 4242 | Successful payment
4000 0000 0000 9995 | Payment declined (insufficient funds)
4000 0000 0000 0077 | Charge succeeds, but dispute is created
4000 0025 0000 3155 | Requires 3D Secure authentication

Use any future expiry date (e.g., 12/30) and any 3-digit CVC.

### Switching to Live Mode

When you are ready to accept real payments:

1. Ensure your Stripe account verification is complete.
2. Create products and prices in Live mode on Stripe (test mode products do not carry over).
3. In the Stripe Dashboard, toggle off Test mode and copy the Live API keys.
4. In MailTrixy, go to Admin Panel → Payment Gateways → Stripe.
5. Replace the test keys with your live keys (`pk_live_` and `sk_live_`).
6. Update the Mode dropdown to `Live`.
7. Update the plans in MailTrixy with the new live Stripe Price IDs.
8. Create a new webhook endpoint in live mode with the same URL and events.
9. Update the Webhook Signing Secret in MailTrixy with the live webhook secret.
10. Click Save Settings.

> Important: Do not mix test and live keys. Using a test publishable key with a live secret key (or vice versa) will cause errors.

## PayPal Setup

To accept payments via PayPal:

1. Log in to the PayPal Developer Dashboard.
2. Navigate to Apps & Credentials and click Create App.
3. Give your app a name (e.g., "MailTrixy") and select Merchant as the app type.
4. Copy the Client ID and Secret from the app details page.
5. In MailTrixy, go to Admin Panel → Payment Gateways → PayPal.
6. Paste the Client ID and Secret into the corresponding fields.
7. Set the mode to Sandbox for testing or Live for production.
8. Click Save and run a test transaction to confirm.

Tip: Use PayPal Sandbox test accounts for testing. Create buyer and seller test accounts in the PayPal Developer Dashboard under Sandbox → Accounts.

For other payment gateways, the setup process is similar: obtain API credentials from the gateway provider's dashboard and enter them in the corresponding section of Admin Panel → Payment Gateways.

## Troubleshooting

Common issues and their solutions when setting up Stripe with MailTrixy:

### Webhook Events Not Being Received

- Verify your webhook URL is publicly accessible over HTTPS.
- Check that the webhook endpoint URL is exactly `https://yourdomain.com/stripe/webhook` (no trailing slash).
- Ensure the Webhook Signing Secret in MailTrixy matches the one shown in the Stripe Dashboard.
- In the Stripe Dashboard, go to Developers → Webhooks and check the endpoint's delivery attempts for error details.
- If using Cloudflare or another CDN/WAF, ensure the webhook URL is excluded from firewall rules or bot protection that might block POST requests.

### Payment Fails with "Invalid API Key"

- Confirm you are using the correct key pair (both publishable and secret must be from the same mode -- test or live).
- Re-copy the keys from Stripe and paste them again in MailTrixy, ensuring no extra whitespace.
- Check that the Mode dropdown in MailTrixy matches the key type (Test keys require Test mode).

### Subscription Not Activating After Payment

- This is usually a webhook issue. Verify the webhook is configured and receiving events.
- Check the Admin Panel → System Logs for webhook processing errors.
- Ensure the Stripe Price ID in the MailTrixy plan exactly matches the Price ID in your Stripe Dashboard.
- If using test mode, make sure both the keys and the Price IDs are from test mode.

### "No such price" Error

- The Stripe Price ID entered in MailTrixy does not exist in your Stripe account.
- If you switched from test to live mode, remember that test prices do not exist in live mode. Create new prices in live mode and update MailTrixy accordingly.
- Double-check for typos in the Price ID (it should start with `price_`).

### Webhook Signature Verification Failed

- The Signing Secret in MailTrixy does not match the webhook endpoint's secret in Stripe.
- If you deleted and re-created the webhook endpoint in Stripe, the signing secret changes. Copy the new secret and update MailTrixy.
- Ensure your server clock is synchronized (NTP). Stripe rejects signatures with timestamps that differ by more than 5 minutes.

### Customers Seeing "Something Went Wrong" at Checkout

- Check the browser console for JavaScript errors related to Stripe.js.
- Verify the Publishable Key is correct and matches the current mode.
- Ensure your domain is not blocked by Stripe (check the Stripe Dashboard for any account alerts).
- If using a Content Security Policy (CSP), ensure `*.stripe.com` is allowed in your script-src and frame-src directives.