Installation

1. Install via Composer

composer require alphabalex/payment-made-easy

PHP: enable the bcmath extension (ext-bcmath); it is required by Composer for consistent amount conversion in drivers.

Stripe: the SDK is not installed with the package by default. If you use Payment::driver('stripe') or Stripe webhooks, add:

composer require stripe/stripe-php:^17.4

Without it, resolving the Stripe driver or handling Stripe webhooks throws a clear error pointing to this command.

Outbound gateway HTTP: drivers use Laravel’s Http facade (illuminate/http). Per-gateway http_timeout and http_verify in config apply to each request. For app-wide defaults (proxy, extra headers, timeouts), see the Laravel HTTP client documentation — Http::globalOptions() is available from Laravel 10.42 onward; on Laravel 8–10.41 rely on those config keys or extend drivers as needed.

Framework versions: this package supports Laravel 8.83+ through Laravel 13 on PHP 8.1+ (Laravel 13 requires PHP 8.3+). Match illuminate/* versions to your laravel/framework release.

2. Publish Configuration

php artisan vendor:publish --provider="Alphabalex\PaymentMadeEasy\PaymentServiceProvider"

3. (Optional) Publish & Run Migrations

The package ships with migrations for recording payment activity to your database. This is opt-in:

# Publish migrations
php artisan vendor:publish --tag=payment-gateways-migrations

# Run migrations
php artisan migrate

Then enable recording in your .env:

PAYMENT_RECORDING_ENABLED=true
PAYMENT_RECORD_WEBHOOKS=true
# Optional: persist transactions / transfers / subscriptions from first-class webhook events
PAYMENT_RECORDING_AUTO_WEBHOOK_EVENTS=false

4. Verify Your Setup

After adding credentials to your .env, run the following to confirm all gateways are configured correctly:

php artisan payment:gateways --configured

Gateways with missing credentials will be highlighted in yellow.

# Default gateway & currency
PAYMENT_GATEWAY=paystack
PAYMENT_CURRENCY=NGN

# Paystack
PAYSTACK_PUBLIC_KEY=pk_live_xxxxx
PAYSTACK_SECRET_KEY=sk_live_xxxxx
PAYSTACK_CALLBACK_URL=https://yoursite.com/payment/callback
PAYSTACK_WEBHOOK_SECRET=your_paystack_webhook_secret

# Flutterwave
FLUTTERWAVE_PUBLIC_KEY=FLWPUBK-xxxxx
FLUTTERWAVE_SECRET_KEY=FLWSECK-xxxxx
FLUTTERWAVE_ENCRYPTION_KEY=your_flutterwave_encryption_key
FLUTTERWAVE_CALLBACK_URL=https://yoursite.com/payment/callback
FLUTTERWAVE_WEBHOOK_SECRET=your_flutterwave_webhook_secret

# Stripe
STRIPE_PUBLIC_KEY=pk_live_xxxxx
STRIPE_SECRET_KEY=sk_live_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxx
STRIPE_CALLBACK_URL=https://yoursite.com/payment/callback

# Seerbit
SEERBIT_PUBLIC_KEY=your_seerbit_public_key
SEERBIT_SECRET_KEY=your_seerbit_secret_key
SEERBIT_BASE_URL=https://seerbitapi.com/api/v2
SEERBIT_CALLBACK_URL=https://yoursite.com/payment/callback
SEERBIT_WEBHOOK_SECRET=your_seerbit_webhook_secret

# Monnify
MONNIFY_API_KEY=your_monnify_api_key
MONNIFY_SECRET_KEY=your_monnify_secret_key
MONNIFY_CONTRACT_CODE=your_monnify_contract_code
MONNIFY_WALLET_ACCOUNT_NUMBER=your_monnify_wallet_account
MONNIFY_CALLBACK_URL=https://yoursite.com/payment/callback
MONNIFY_WEBHOOK_SECRET=your_monnify_webhook_secret

# Squad (GTCo)
SQUAD_SECRET_KEY=your_squad_secret_key
SQUAD_PUBLIC_KEY=your_squad_public_key
SQUAD_BENEFICIARY_ACCOUNT=your_squad_beneficiary_account
SQUAD_CALLBACK_URL=https://yoursite.com/payment/callback
SQUAD_WEBHOOK_SECRET=your_squad_webhook_secret

# Remita
REMITA_API_KEY=your_remita_api_key
REMITA_MERCHANT_ID=your_remita_merchant_id
REMITA_SERVICE_TYPE_ID=your_remita_service_type_id
REMITA_SOURCE_ACCOUNT=your_remita_source_account
REMITA_CALLBACK_URL=https://yoursite.com/payment/callback

# Budpay
BUDPAY_SECRET_KEY=your_budpay_secret_key
BUDPAY_PUBLIC_KEY=your_budpay_public_key
BUDPAY_CALLBACK_URL=https://yoursite.com/payment/callback
BUDPAY_WEBHOOK_SECRET=your_budpay_webhook_secret

# Mono
MONO_SECRET_KEY=your_mono_secret_key
MONO_PUBLIC_KEY=your_mono_public_key
MONO_CALLBACK_URL=https://yoursite.com/payment/callback
MONO_WEBHOOK_SECRET=your_mono_webhook_secret

# Interswitch
INTERSWITCH_CLIENT_ID=your_interswitch_client_id
INTERSWITCH_CLIENT_SECRET=your_interswitch_client_secret
INTERSWITCH_MERCHANT_CODE=your_interswitch_merchant_code
INTERSWITCH_PAYABLE_CODE=your_interswitch_payable_code
INTERSWITCH_TERMINAL_ID=your_interswitch_terminal_id
INTERSWITCH_CALLBACK_URL=https://yoursite.com/payment/callback
INTERSWITCH_WEBHOOK_SECRET=your_interswitch_webhook_secret

# PayPal
PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_client_secret
PAYPAL_CURRENCY=USD
PAYPAL_BASE_URL=https://api.paypal.com
PAYPAL_CALLBACK_URL=https://yoursite.com/payment/callback
PAYPAL_CANCEL_URL=https://yoursite.com/payment/cancel

# M-Pesa (Safaricom)
MPESA_CONSUMER_KEY=your_mpesa_consumer_key
MPESA_CONSUMER_SECRET=your_mpesa_consumer_secret
MPESA_SHORTCODE=your_mpesa_shortcode
MPESA_PASSKEY=your_mpesa_passkey
MPESA_INITIATOR_NAME=your_mpesa_initiator
MPESA_SECURITY_CREDENTIAL=your_mpesa_security_credential
MPESA_CALLBACK_URL=https://yoursite.com/webhooks/payment-gateways/mpesa
MPESA_RESULT_URL=https://yoursite.com/webhooks/payment-gateways/mpesa
MPESA_TIMEOUT_URL=https://yoursite.com/webhooks/payment-gateways/mpesa

# MTN MoMo
MTNMOMO_COLLECTION_USER_ID=your_mtnmomo_collection_user_id
MTNMOMO_COLLECTION_API_KEY=your_mtnmomo_collection_api_key
MTNMOMO_COLLECTION_SUBSCRIPTION_KEY=your_mtnmomo_collection_subscription_key
MTNMOMO_DISBURSEMENT_USER_ID=your_mtnmomo_disbursement_user_id
MTNMOMO_DISBURSEMENT_API_KEY=your_mtnmomo_disbursement_api_key
MTNMOMO_DISBURSEMENT_SUBSCRIPTION_KEY=your_mtnmomo_disbursement_subscription_key
MTNMOMO_ENVIRONMENT=sandbox
MTNMOMO_CURRENCY=EUR
MTNMOMO_CALLBACK_URL=https://yoursite.com/webhooks/payment-gateways/mtnmomo

# Razorpay
RAZORPAY_KEY_ID=rzp_live_xxxxx
RAZORPAY_KEY_SECRET=your_razorpay_key_secret
RAZORPAY_ACCOUNT_NUMBER=your_razorpay_x_account_number
RAZORPAY_CURRENCY=INR
RAZORPAY_CALLBACK_URL=https://yoursite.com/payment/callback
RAZORPAY_WEBHOOK_SECRET=your_razorpay_webhook_secret

# Paddle
PADDLE_API_KEY=your_paddle_api_key
PADDLE_CLIENT_TOKEN=your_paddle_client_token
PADDLE_WEBHOOK_SECRET=your_paddle_webhook_secret
PADDLE_CURRENCY=USD
PADDLE_BASE_URL=https://api.paddle.com
PADDLE_CALLBACK_URL=https://yoursite.com/payment/callback

# Webhook settings
PAYMENT_WEBHOOKS_ENABLED=true
PAYMENT_WEBHOOK_VERIFY_SIGNATURE=true
# When true with verify on, HMAC gateways must have webhook_secret (or Monnify secret_key / Interswitch client_secret) set
PAYMENT_WEBHOOK_REQUIRE_SIGNING_SECRET=true
PAYMENT_WEBHOOK_LOG_EVENTS=true
PAYMENT_WEBHOOK_QUEUE_EVENTS=false
# full = log payload data; minimal = gateway + event type only (less PII in logs)
PAYMENT_WEBHOOK_LOG_DETAIL=full
# When true with log_detail=full, sensitive keys are redacted before logging (see WebhookLogSanitizerInterface)
PAYMENT_WEBHOOK_LOG_SANITIZE=true
# Optional: FQCN of a custom WebhookLogSanitizerInterface implementation
# PAYMENT_WEBHOOK_LOG_SANITIZER=
# Extra webhook keys to redact (merged with package defaults; suffix rules apply — see config)
# PAYMENT_WEBHOOK_LOG_REDACT_KEYS=
PAYMENT_WEBHOOK_IDEMPOTENCY_ENABLED=false
PAYMENT_WEBHOOK_IDEMPOTENCY_TTL=86400
# Optional abuse protection (see Webhooks section for middleware)
PAYMENT_WEBHOOK_THROTTLE_ENABLED=false
PAYMENT_WEBHOOK_THROTTLE_MAX_ATTEMPTS=60
PAYMENT_WEBHOOK_THROTTLE_DECAY_SECONDS=60
# Optional: force stack traces on unexpected webhook errors (HTTP 500). Omit to tie to APP_DEBUG (traces off in production).
# PAYMENT_WEBHOOK_LOG_UNEXPECTED_TRACE=

---