Download the PHP package gokulsingh/laravel-payhub without Composer

Laravel PayHub — Step-by-step Guide (Beginner Friendly)

A unified payment wrapper for Laravel supporting Razorpay and Cashfree. It provides a consistent API: create orders, charge, refund, verify webhooks, store optional logs, and attach custom metadata per order.

Table of contents

1. Getting started (Install)
2. Publish config & migrations
3. Configure .env
4. Quick examples (backend)

5. Checkout integration (frontend)

   • Razorpay (Checkout.js)
   • Cashfree (Hosted link or Drop-in)
6. Success callback (route + controller + verify)
7. Webhook integration (route + verify)
8. Metadata (custom data per order)
9. Optional DB logging (disable/enable)
10. Unit tests
11. Troubleshooting & FAQ
12. Extending with a new gateway
13. License

1 — Getting started (Install)

Option A — Install from Packagist (recommended when published)

Option B — Local development (path repository)

If you keep the package in your app under packages/gokulsingh/laravel-payhub, add to your app composer.json:

Then run:

Laravel supports package auto-discovery — no manual provider registration needed.

2 — Publish config & migrations

Publish config + migration files into your Laravel app:

If you want DB logging, run:

Note: If you don’t want the payment_transactions table, skip the migrations publish and migrate step — see "Optional DB logging" below.

3 — Configure .env

Add credentials and options to your .env:

Open config/payment.php (published) to confirm settings.

Important — Amount units

• When calling createOrder(...) on this package pass amount in the main currency unit (e.g., rupees — 500 = ₹500).

  • Razorpay internally converts ₹ to paise (multiplies by 100).
  • Cashfree uses the amount value directly as provided (e.g., 1200 = ₹1,200).
• Always check the gateway docs when you change behavior.

4 — Quick backend examples

Use the package via the Payment facade.

Create an order using the default gateway

Explicit gateway

Charge / verify a payment

Refund

5 — Checkout integration (frontend)

After you create an order in backend, integrate frontend to complete payment.

A — Razorpay (Checkout.js)

Backend: create order and return JSON.

Frontend:

Notes:

• order.data.id is Razorpay order_id — required to initialize Checkout and show payment modal.
• After success, response.razorpay_payment_id is provided to backend to verify.

B — Cashfree

Backend: create order

Option 1 — Redirect to hosted payment link If createOrder() returns a payment_link (or in raw), simply redirect:

Option 2 — Cashfree Drop-in

Notes:

• Cashfree response shape depends on their API and your account; check the raw response in order.data.raw.
• If using Drop-in, you must supply order_token (returned by Cashfree in the raw response).

6 — Success callback (server side verification)

Add a route:

Create controller:

This uses the package charge() method which calls the gateway API and returns normalized result.

7 — Webhook integration (automatic route + verification)

Publish routes with the package route macro:

The package WebhookController will:

• Collect the raw payload and headers,
• Call Payment::useGateway($gateway)->verifyWebhook($payload),
• Dispatch events on success/failure.

If you need custom behavior, extend WebhookController or listen to the package events:

Manual verification example (Razorpay):

8 — Custom metadata (attach any data you want)

When creating orders, pass metadata array — it will be:

• Sent to the gateway (Razorpay notes, Cashfree metadata) where supported.
• Stored with the normalized response (check data.metadata or data.raw).

Use metadata to store app-specific IDs, tracking info, coupons, etc.

9 — Optional DB logging

By default the package logs transactions into payment_transactions. You can disable this:

Disable:

If disabled:

• The LogsTransactions trait will skip DB writes.
• You can skip publishing the migration or skip running php artisan migrate.

If enabled later:

Migration fields typically include: gateway, type, status, amount, currency, transaction_id, payload (json), created_at.

10 — Unit tests

The package includes PHPUnit tests (feature tests). Run them from your application:

Suggested tests:

• Payment facade resolves
• createOrder returns normalized response
• charge() verifies payments
• refund() returns normalized refund

When testing, mock HTTP client responses to avoid hitting real APIs.

11 — Troubleshooting & FAQ

Q: Class not found after composer install? A: Run composer dump-autoload and ensure package composer.json psr-4 namespace matches your src/ namespaces.

Q: No publishable resources when vendor\:publish? A: Verify you used the correct tag --tag=config and --tag=migrations (plural). Check the package provider namespace matches installed package.

Q: Amount mismatches (Razorpay shows ×100)? A: Pass amount in main currency unit (₹). The package converts for Razorpay internally.

Q: Webhook signature verification failing? A: Make sure RAZORPAY_SECRET / CASHFREE_SECRET are correct, and that your webhook body is the exact raw JSON used to compute the HMAC. When testing locally, use ngrok to forward webhooks.

12 — Extending (Add a new gateway)

1. Implement Gokulsingh\LaravelPayhub\Contracts\GatewayInterface.
2. Use BaseGateway & BaseNormalizer for consistent behavior.
3. Register gateway in your Payment manager (or modify Payment::useGateway switch).
4. Add config values in config/payment.php.

13 — Contributing & License

• Pull requests welcome.
• Follow PSR-12 and write tests for new functionality.
• License: MIT