Download the PHP package shwary/php-sdk without Composer
On this page you can find all versions of the php package shwary/php-sdk. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download shwary/php-sdk
More information about shwary/php-sdk
Files in shwary/php-sdk
Package php-sdk
Short Description SDK PHP officiel pour l'API marchande Shwary - Paiements Mobile Money (RDC, Kenya, Ouganda)
License MIT
Homepage https://github.com/Tresor-Kasenda/shwary-php-sdk
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package php-sdk
Shwary PHP SDK
Official PHP SDK for the Shwary API - Mobile Money Payments for DRC, Kenya, and Uganda.
📋 Table of Contents
- Introduction
- Requirements
- Installation
- Configuration
- Quick Start Guide
- Detailed Usage
- Handling Webhooks
- Sandbox Mode (Testing)
- Error Handling
- Laravel Integration
- Complete Reference
- FAQ & Troubleshooting
- Contributing
🎯 Introduction
What is Shwary?
Shwary is a Mobile Money payment platform that enables merchants to accept payments from:
- 🇨🇩 DRC (Democratic Republic of Congo) - Payments in Congolese Francs (CDF)
- 🇰🇪 Kenya - Payments in Kenyan Shillings (KES)
- 🇺🇬 Uganda - Payments in Ugandan Shillings (UGX)
What does this SDK do?
This SDK allows you to easily integrate Shwary into your PHP application to:
- ✅ Initiate Mobile Money payments
- ✅ Receive payment notifications (webhooks)
- ✅ Check transaction status
- ✅ Test your integrations in sandbox mode
How does a Mobile Money payment work?
📦 Requirements
Before you begin, make sure you have:
Technical Requirements
- PHP 8.2 or higher - Download PHP
- Composer - Install Composer
- JSON extension - Usually included by default
Check your PHP version
Shwary Account
- An active Shwary merchant account
- Your Merchant ID (unique identifier)
- Your Merchant Key (secret key)
💡 Where to find your credentials?
Log in to your Shwary Dashboard → Settings → API
🔧 Installation
Step 1: Install the SDK via Composer
Open your terminal in your project folder and run:
Step 2: Verify the installation
Create a test file test-shwary.php:
Run it:
⚙️ Configuration
There are 3 ways to configure the SDK. Choose the one that suits your needs.
Method 1: Environment Variables (Recommended ⭐)
Why is this recommended? Your credentials are not in the code, which is more secure.
Step A: Create a .env file at the root of your project
Step B: Load the variables (if you're not using a framework)
Step C: Initialize the SDK
Method 2: Array Configuration
Useful if you store your configurations in a PHP file or database.
Method 3: Manual Configuration (Full Control)
For advanced developers who want full control.
🚀 Quick Start Guide
Your first payment in 5 minutes
Here's a complete, working example:
Expected output:
📚 Detailed Usage
Payments by Country
🇨🇩 Payment in DRC (Democratic Republic of Congo)
⚠️ Important for DRC:
- Minimum amount is 2901 CDF
- Phone number must start with +243
🇰🇪 Payment in Kenya
🇺🇬 Payment in Uganda
Generic Method with Country
If you want to handle multiple countries dynamically:
Using PaymentRequest (Advanced Control)
For full control over the payment request:
🔔 Handling Webhooks
What is a webhook?
A webhook is an automatic notification sent by Shwary to your server when a payment status changes (confirmed, failed, etc.).
Webhook Configuration
Step 1: Create an endpoint on your server
Step 2: Register the webhook URL
Configure the URL https://your-site.com/webhook.php in your Shwary Dashboard.
Parse a webhook manually
If you retrieve the payload differently (e.g., framework):
🧪 Sandbox Mode (Testing)
Sandbox mode allows you to test without making real payments.
Enable sandbox mode
Make a sandbox payment
Sandbox vs Production differences
| Aspect | Sandbox | Production |
|---|---|---|
| Real payment | ❌ No | ✅ Yes |
| Status | Immediately completed |
pending then completed/failed |
| Webhooks | Simulated | Real |
| Money charged | ❌ No | ✅ Yes |
⚠️ Error Handling
Exception Types
The SDK defines several error types to help you handle them:
Complete Error Handling Example
Common Error Codes
| Code | Meaning | Recommended Action |
|---|---|---|
| 400 | Invalid request | Check parameters |
| 401 | Unauthenticated | Verify merchant_id and merchant_key |
| 404 | Resource not found | The number is not registered |
| 422 | Validation failed | Correct the sent data |
| 500 | Server error | Retry or contact support |
| 502 | Gateway error | Temporary issue, retry |
🎨 Laravel Integration
Installation
Configuration
1. Create the configuration file
2. Add environment variables
3. Create a Service Provider
4. Register the provider
Using in a Controller
Webhook Controller
Routes
📖 Complete Reference
Supported Countries
| Constant | Country | Currency | Dial Code | Minimum Amount |
|---|---|---|---|---|
Country::DRC |
DR Congo | CDF | +243 | > 2900 CDF |
Country::KENYA |
Kenya | KES | +254 | > 0 KES |
Country::UGANDA |
Uganda | UGX | +256 | > 0 UGX |
Transaction Statuses
| Constant | Value | Description |
|---|---|---|
TransactionStatus::PENDING |
pending |
Waiting for confirmation |
TransactionStatus::COMPLETED |
completed |
Payment successful |
TransactionStatus::FAILED |
failed |
Payment failed |
Transaction Properties
Transaction Methods
Shwary Facade Methods
❓ FAQ & Troubleshooting
Frequently Asked Questions
Q: How can I test without making real payments?
A: Use sandbox mode by setting sandbox: true in your configuration.
Q: Why does my payment stay in "pending"?
A: The pending status means the customer hasn't confirmed on their phone yet. Wait for the confirmation webhook.
Q: How do I know if a payment was successful?
A: Check with $transaction->isCompleted() or wait for the webhook.
Q: What's the difference between pay() and payDRC()?
A: payDRC() is a shortcut for pay(..., Country::DRC). They do the same thing.
Common Errors
"Merchant ID is required"
"Amount must be greater than 2900 CDF for DRC"
"Phone number must start with +243 for DRC"
"Callback URL must use HTTPS"
🧪 Tests
Run tests
Statistics
- 113 tests
- 278 assertions
- PHPStan level max
🤝 Contributing
Contributions are welcome! Here's how to proceed:
- Fork the repository
- Create a branch for your feature (
git checkout -b feature/my-feature) - Commit your changes (
git commit -m 'Add my feature') - Push to the branch (
git push origin feature/my-feature) - Open a Pull Request
Code Standards
- PSR-12 for code style
- PHPStan level max
- Pest tests for any new feature
📄 License
This project is licensed under the MIT License. See the LICENSE file for details.
📞 Support
- 📧 Email: [email protected]
- 📚 Documentation: docs.shwary.com
- 🐛 Issues: GitHub Issues
Made with ❤️ by the Shwary Team
