Download the PHP package richnessagency/rich-payments without Composer

Rich Payments

richnessagency/rich-payments is a reusable Laravel payment package for building reliable online payment flows across Richness projects and community Laravel applications.

The package is designed around gateway drivers. Paymob is included as the first driver, and new gateways can be added without changing the checkout, webhook, credential storage, audit log, or admin management layers.

Goals

• Make online payments easy to add to any Laravel application.
• Keep gateway integrations isolated behind stable contracts.
• Store sensitive credentials encrypted in the database.
• Support hosted checkout redirects, callbacks, webhooks, inquiries, refunds, voids, and captures.
• Let each application customize routes, middleware, branding, result pages, and payment methods.
• Preserve backward compatibility for existing projects using earlier versions.

Installation

Install with Composer:

Run package migrations:

Seed the default Paymob gateway and payment methods:

Publish optional files:

Quick Start

1. Visit the admin gateway page:

2. Open the Paymob gateway.
3. Enter encrypted credentials:
   • secret_key
   • public_key
   • hmac_secret
   • api_key
4. Add or confirm integration identifiers for enabled methods:
   • cards
   • wallets
   • kiosk
   • bnpl
5. Enable the gateway.
6. Enable the payment methods you want customers to see.
7. Start a checkout session from your application or use the package start route.

Configuration

Publish the config file and edit config/rich-payments.php.

Important Config Keys

Environment Variables

The default config reads these values:

Payment secrets are intentionally managed from the encrypted database admin UI, not from frontend code.

Routes

Default public routes:

Default admin routes:

Route prefixes and middleware are configurable.

Starting A Payment From Code

Use the RichPayments service when your app owns the checkout/order flow.

Amounts use minor units. For EGP, 150000 means 1500.00 EGP.

Using The Built-in Start Route

The package can expose a generic start endpoint when:

Example form:

For production stores, prefer starting payments from your own checkout controller so you can calculate totals server-side and prevent amount tampering.

Success, Failure, Pending, And Callback Pages

Built-in result views:

• rich-payments::results.success
• rich-payments::results.failed
• rich-payments::results.pending
• rich-payments::checkout.methods

Publish views:

Published files are placed under:

Customize these pages like normal Blade files:

Redirecting Back To Your App

Set a verified redirect route:

When a gateway callback is verified, the package redirects to:

If verification fails, the package sends the user to the pending page. Redirect pages are never treated as proof of payment. Verified webhook/callback data and transaction inquiry are the source of truth.

Branding Built-in Pages

Configure:

Or edit the published Blade views for full control.

Credential Management

Gateway credentials are stored in rich_payment_credentials.

Security behavior:

• Secret values are encrypted before storage.
• Masked previews are shown after save.
• Raw secret values are never stored in audit logs.
• Credential rotations are audited.
• Frontend code must never receive secret keys.

Paymob default credential keys:

• secret_key
• public_key
• hmac_secret
• api_key

Method integration identifiers are stored per payment method and encrypted:

• cards
• wallets
• kiosk
• bnpl

Webhooks

Webhook endpoint:

The selected gateway driver receives the Laravel request and returns a WebhookResult.

The package then:

1. Stores a sanitized webhook event.
2. Verifies the gateway signature/HMAC.
3. Rejects invalid payloads with 400.
4. Processes valid events inside a database transaction.
5. Locks duplicate events using a canonical payload hash.
6. Updates the matching payment attempt.
7. Dispatches payment events.

Webhook payload snapshots are sanitized before storage.

Payment Status

Payment attempts use PaymentStatus:

• initiated
• redirected
• pending
• paid
• failed
• refunded
• cancelled

The status endpoint:

If the attempt is not final and has an external transaction id, the package may ask the gateway driver for an inquiry result and update the attempt.

Events

The package dispatches events your application can listen to:

• PaymentPaid
• PaymentFailed
• PaymentPending
• PaymentRefunded
• WebhookRejected

Use these events to update orders, send notifications, or queue fulfillment. Keep listeners idempotent because webhooks can be retried.

Refund, Void, And Capture

Drivers that support money actions implement ManagesTransactions.

Admin screens already expose inquiry, refund, void, and capture actions when the gateway supports them. Every money action should create transaction records and audit logs.

Adding A New Gateway

Add a driver class implementing PaymentGatewayDriver.

Register the driver in config/rich-payments.php:

Seed or create a rich_payment_gateways row with code stripe, then add methods such as cards, apple_pay, or google_pay.

Driver Contract Rules

A gateway driver should:

• Convert app payment requests into gateway sessions.
• Verify webhooks cryptographically before returning verified: true.
• Normalize gateway statuses into PaymentStatus.
• Use minor currency units.
• Never trust browser redirects alone.
• Never log raw credentials, card data, or full webhook secrets.
• Throw clear exceptions for setup/configuration errors.
• Keep external API payloads in payload for debugging after sanitization.

Backward Compatibility

Existing applications may already depend on:

• Config keys in config/rich-payments.php.
• Route names beginning with rich-payments.*.
• View namespace rich-payments::.
• Database table names beginning with rich_payment_.
• Driver contracts in src/Contracts.
• Paymob method codes: cards, wallets, kiosk, bnpl.

Do not rename these without a major version release and migration guide.

Safe additions:

• New gateway config entries.
• New optional contract methods through extra interfaces.
• New nullable database columns.
• New views that do not replace existing names.
• New events.

Risky changes:

• Changing route names.
• Changing enum values.
• Changing amount units.
• Changing webhook verification behavior.
• Changing credential key names.
• Removing or renaming model columns.

Security Checklist

Before enabling a gateway in production:

• Use HTTPS for checkout, callback, and webhook URLs.
• Configure gateway webhooks to the exact production endpoint.
• Verify HMAC/signature for every webhook/callback type you accept.
• Keep API keys encrypted and out of source control.
• Use strong APP_KEY; rotating it requires a credential rotation plan.
• Restrict admin routes with authentication and payment permissions.
• Validate amounts server-side from orders/carts, not from public forms.
• Make webhook/order listeners idempotent.
• Store only sanitized payload snapshots.
• Use gateway inquiry for ambiguous or pending states.
• Test success, failure, pending, duplicate webhook, refund, void, and capture flows.

Testing

Run the package test suite:

Or:

Recommended integration tests in consuming apps:

• Start checkout with each enabled method.
• Receive valid webhook and mark order paid.
• Reject invalid webhook signature.
• Handle duplicate webhook idempotently.
• Redirect success only after verified callback/webhook.
• Show pending page for unverified browser callback.
• Refund partial and full amounts.
• Rotate credentials and confirm old values are not shown.

Production Release Workflow

This package is distributed through GitHub and Composer/Packagist:

For stable public usage, tag semantic versions:

Consuming apps should prefer stable constraints such as:

Use dev-main only for active internal development.

License

MIT License. Created by Richness Agency.