Download the PHP package mhaggag/laravel-payments without Composer

Laravel Payments

A comprehensive and flexible Laravel package for handling payments, subscriptions, and webhooks across multiple gateways including Stripe, PayPal, and Paymob.

Requirements

• PHP: >= 8.2
• Laravel: >= 11

Table of Contents

• 1. Installation
• 2. Publishing Package Files
• 3. Configuration
• 4. Environment Variables
• 5. Supported Gateways
• 6. Using Gateway Enums
• 7. Using the Payment Facade
• 8. Using the Payable Trait
• 9. Using the Subscribable Trait
• 10. Gateway Payload & Parameters
• 11. Web & Webhook Routes
• 12. Events & Listeners
• 13. Models & Database
• 14. Views & Translations
• 15. Debug Mode & Logging
• 16. Custom Gateways
• 17. Screenshots from default routes
• 18. Testing
• 19. License
• 20. Contact

1. Installation

Install the package via Composer:

2. Publishing Package Files

Publish all package assets:

Or publish selectively:

Run migrations:

3. Configuration (config/payments.php)

All package behavior is controlled from one config file:

4. Environment Variables

Add these variables to your .env file to configure the package:

5. Supported Gateways

• Stripe
• PayPal
• Paymob
• Easily extendable with custom gateways

Each gateway has:

• Its own config section
• Its own payload definition

6. Using Gateway Enums

Select the gateway for a payment process using the GatewayName enum:

Example:

7. Using the Payment Facade

The Payment facade provides a fluent interface to construct and execute payment requests.

Available Methods

• gateway(string $name): Set the payment gateway driver, or use the default in config/payments.php with default key.
• withPayload(array $payload): Pass gateway-specific parameters (including the next methods parameters and any custom parameters).

Or you can set your payload as separate methods:

• amount(float $amount, ?string $currency = null): Set the amount to charge.
• currency(string $currency): Set the currency (e.g., 'USD').
• for(Model $payable): Associate the payment with a model.
• isSubscription(bool $isSubscription = true): Flag as subscription.
• items(array $items): Set items. See gateway documentation for structure.
• metadata(array $metadata): Set metadata.
• description(string $description): Set description.
• redirectUrls(string $successUrl, string $cancelUrl): Set success and cancel URLs. Default URLs are configured in config/payments.php under the route key.

You can review the Gateways Payloads & Parameters section for more details and any custom parameters you may need to pass to the gateway individually.

Execution Methods

• create(): Create a payment intent/transaction.
• checkout(): Initiate a checkout session that will return checkout_url for redirect to payment page.
• refund(Model $payment, ?float $amount = null): Refund a payment.
• handleRedirect(string $gateway, array $payload): Handle gateway redirect.
• verifySignature(string $gateway, Request $request): Handle gateway verification signature.
• handleWebhook(string $gateway, array $payload): Process incoming webhooks.

Examples

Basic Payment:

8. Using the Payable Trait

Attach payments to any Eloquent model:

Usage:

Available Methods

• payment(string $gateway): Initiate a payment process, and using all previous methods in the payment facade.

• payments(): Get all payments relationship.
• successfulPayments(): Get successful payments relationship.
• pendingPayments(): Get pending payments relationship.
• failedPayments(): Get failed payments relationship.
• refundedPayments(): Get refunded payments relationship.
• lastPayment(): Get the latest payment model.
• totalPaid(): Get total amount paid.
• totalRefunded(): Get total amount refunded.
• hasPayments(): Check if model has any payments.
• hasSuccessfulPayment(): Check if model has successful payment.
• hasPendingPayment(): Check if model has pending payment.

Scopes

• hasPaymentWithStatus(string $status): Filter models by payment status.
• hasPaymentWithGateway(string $gateway): Filter models by gateway.

9. Using the Subscribable Trait

Using it with Payable Trait when you want to support subscriptions mode.

Usage:

Available Methods

• subscribe(string $gateway): Initiate a subscription process, and using all previous methods in the payment facade.

• subscriptions(): Get all subscriptions relationship.
• activeSubscriptions(): Get active subscriptions relationship.
• canceledSubscriptions(): Get canceled subscriptions relationship.
• trialingSubscriptions(): Get trialing subscriptions relationship.
• latestSubscription(): Get the latest subscription model.
• isSubscribed(): Check if model has an active subscription.
• onTrial(): Check if model is currently on trial.

Scopes

• hasSubscriptionWithStatus(string $status): Filter models by subscription status.
• hasSubscriptionWithGateway(string $gateway): Filter models by gateway.

10. Gateway Payload & Parameters

Each gateway defines specific parameters.

Stripe

Test Card Details Card Number: 4242424242424242 Expiration Date: 12/34 CVV: 123

PayPal

Paymob

Card Test Credentials Card Number: 2223000000000007 Expiration Date: 01/39 CVV: 100 Card Holder Name: Test Account

Wallet Test Credentials Wallet Number: 01010101010 MPin Code: 123456 OTP: 123456

11. Web & Webhook Routes

Enable or disable routes from config, and by default the webhook routes use the payments.verify_signature middleware to verify the signature or use the verifySignature method on the facade. You can control all these by route and webhook keys in config/payments.php:

Default web URLs (you can see the screenshots below):

• POST /payments/checkout
• GET /payments/success/{gateway}
• GET /payments/cancel/{gateway}

Default webhook URLs:

• POST /payments/webhook/{gateway}

Also, you can create webhook events by this commands:

• This command will create a webhook by default values in config/payments.php under the webhook key.
• By this key, you can custom the webhook url and events that you want to handle.
• Default webhook url is: https://domain.com/payments/webhook/{gateway}.

• And default events that will create. Will be the package need to handle the all payment/subscription process logic to all functions.

12. Events & Listeners

You can customize your events instead of using in config/payments.php by adding them to the events key:

Available Events on using handleRedirect method on facade

• events.payment.received default is PaymentRedirectReceived
• events.payment.processed default is PaymentRedirectProcessed

Available Events on using handleWebhook method on facade

• events.webhook.received default is PaymentWebhookReceived
• events.webhook.processed default is PaymentWebhookProcessed

Listening to Events

13. Models & Database

Published migrations create tables for:

• payments
• subscriptions (if enabled)

Override models in config:

14. Views & Translations

Views

Publish views:

Customize checkout, success, and error pages.

Translations

Publish language files:

Add your own language:

15. Debug Mode & Logging

Enable debug mode:

This logs:

• Gateway requests
• Payloads
• Responses
• Webhook data

16. Custom Gateways

You can add your own gateway by extending the MHaggag\Payments\Gateways\BaseGateway class.

1. Create your gateway class:

2. Register in config/payments.php:

17. Screenshots from default routes

Success

Cancel

Error

18. Testing

bash ./vendor/bin/phpunit

Mock gateways are included for local testing.

---

## 19. License

MIT License.

---

## Final Notes

This package is designed to be:
- Framework-native
- Fully configurable
- Easy to extend
- Safe for production use

If you need custom gateways, advanced subscriptions, or multi-tenant support, extend the base gateway class or contact me for assistance.

Happy coding 🚀

## 20. Contact

If you have any questions, suggestions, or need support, feel free to contact me:

- **Email**: [[email protected]](mailto:[email protected])
- **Phone**: +201121300234
- **LinkedIn**: [Mahmoud Haggag](https://linkedin.com/in/mahmoudhaggag641)