How to Add a New Payment Gateway
Prerequisites
- Familiarity with the PayWith library
- Access to your payment gateway's API documentation
- A valid account with the payment gateway provider
include/helpers/PayWithConfig.phpinclude/helpers/core/ConfigManagerHelper.php- Test Donation Flow
- Verify in Admin Panel
- Verify Currency Customization
- Account-Specific Currencies: Your payment gateway account typically only supports specific currencies. Always verify which currencies your account actually supports. Example - PayStack:
- PayStack supports many countries/currencies globally
- However, your specific account may only support one currency by default
- Always check your account's actual supported currencies Example - NowPayments:
- NowPayments supports almost unlimited cryptocurrencies
- They accept only a few as main payment currencies (e.g., USD)
- Users select USD, then NowPayments shows additional currencies they can pay with
- This approach is acceptable as the main currency remains fixed
- Research First: Before integrating, check your gateway provider's documentation for supported currencies
- Test Thoroughly: Test with multiple currencies if your account supports them
- Document Your Gateway: Add comments explaining any special configurations
- Security First: Never hardcode API keys or credentials in your gateway file
- Check the PayWith documentation
- Review existing gateway implementations for reference
- Contact support at support@equalfaith.org | technical@equalfaith.org
---
Step 1: Create Your Gateway
Create your gateway class in the PayWith library following the PayWith documentation. Name it appropriately (e.g., NewTest.php).
---
Step 2: Add Gateway to Project
Copy your gateway file (e.g., NewTest.php) to the following path in your EqualFaith Welfare project:
include/helpers/PayWith/---
Step 3: Configure Supported Currencies
Update the supported_currency variable in config.php to include your gateway and its supported currencies.
$supported_currency = '(gateway_name:CURRENCY1,CURRENCY2,CURRENCY3)';$supported_currency = '(paypal:USD,CAD,EUR,GBP),(paystack:NGN,USD),(yourgateway:USD,EUR)';---
Step 4: Update Configuration Files
Update the following files to support your new gateway:
- Add your gateway configuration
- Follow existing patterns
- Add your gateway to the getPaymentGateways() method
- Follow existing patterns
Rule: Always follow the examples already present. Do not invent new patterns or structures.---
Step 5: Test Your Gateway
- Navigate to /donations
- Complete a test donation using your gateway
- Fix any logic issues in your gateway file if errors occur
- Go to /account/configs-manager/payment-gateways
- Locate your gateway (use pagination if not on the first page)
- Verify your gateway appears with api keys configuration
- Go to /account/configs-manager/advanced
- Scroll down to the gateway currencies section
- Verify you can customize which currencies your gateway supports
---
Important Compliance Notes
Currency Support Limitations
For compliance and security reasons, do not support unlimited currencies.
---
Best Practices
---
Congratulations! 🎉
You have successfully integrated a new payment gateway into EqualFaith Welfare!
Share Your Work
If you'd like to share your gateway with the community, contact us at:
📧 share-gateways@equalfaith.org
---
Troubleshooting
| Issue | Solution |
|-------|----------|
| Gateway not appearing in admin | Check ConfigManagerHelper.php and ensure your gateway is added properly |
| Currencies not saving | Verify the supported_currency format is correct |
| Payments fail | Check your gateway's API credentials and error logs |
| Gateway not found in PayWith | Ensure the file is in the correct directory |
---
Need Help?
Please do not iemail us twise for same reason. Also, use technical or share-gateways for code related to ensure the right team sees your message faster.