Download the PHP package djlemmor/djpaykit-laravel without Composer

DJPayKit Laravel

Laravel 12 backend adapter for the DJPayKit QR payment widget.

It allows a website owner to configure payment methods such as GCash, Maya, and MariBank, upload private QR images, and expose controlled public endpoints for the DJPayKit widget.

Requirements

• PHP 8.2 or newer
• Laravel 12
• A Laravel filesystem disk
• Authentication middleware for administrator endpoints

Features

• GCash, Maya, and MariBank support
• Extensible provider configuration
• Private QR image storage
• Public payment-method API
• Controlled QR image responses
• Administrator CRUD endpoints
• Account-number privacy controls
• ULID payment-method identifiers
• Soft deletion
• Validated PNG, JPEG, and WebP uploads
• Safe QR replacement and cleanup
• Automated package tests

Installation

The package has not yet been published to Packagist. The standard installation command will become available after the first release:

Then run:

Local development installation

Add DJPayKit as a Composer path repository:

Run the installer:

Composer normally symlinks the package, so local DJPayKit changes become available without reinstalling it.

Configuration

The installation command publishes:

Important settings:

Environment variables:

Administrator authentication

Administrator endpoints use the middleware configured in:

Applications using Sanctum can change it to:

DJPayKit does not create administrator users or decide which users are authorized. The host Laravel application remains responsible for authentication and authorization.

Storage security

QR images use Laravel's configured private disk:

Laravel 12's local disk normally stores private files below:

DJPayKit serves QR images through a controlled route. It never returns the underlying filesystem or cloud-storage path.

Do not move DJPayKit QR images to the public disk unless your application intentionally wants to bypass these controls.

Supported providers

The default providers are:

A host application can add another provider:

Provider IDs may contain lowercase letters, numbers, hyphens, and underscores.

Public API

List enabled payment methods

Example response:

accountNumber is null unless the owner enables show_account_number for that payment method.

Disabled and soft-deleted methods are excluded.

Display a QR image

The endpoint:

• Only serves enabled payment methods
• Reads from the configured private disk
• Allows PNG, JPEG, and WebP
• Sends X-Content-Type-Options: nosniff
• Does not expose the private storage path
• Returns 404 for disabled, deleted, missing, or unsupported images

Administrator API

All administrator routes require the configured administrator middleware.

List payment methods

The administrator list includes enabled and disabled methods but excludes soft-deleted records and private QR paths.

Create a payment method

Example using cURL:

Required fields:

• provider
• display_name
• account_name
• qr_image

Optional fields:

• account_number
• instructions
• show_account_number
• is_enabled
• sort_order

QR requirements:

• PNG, JPEG, or WebP
• Maximum 5 MB by default
• Maximum 4096×4096 pixels by default
• SVG is not accepted

Update a payment method

All update fields are optional. The provider cannot be changed after creation.

Example replacing a QR:

If the database update fails, DJPayKit deletes the new upload and keeps the original QR.

Delete a payment method

Deletion:

• Soft-deletes the database record
• Removes the associated QR image
• Prevents the public API from returning the method
• Returns HTTP 204 No Content

Error responses

Common status codes:

Laravel returns validation errors in its normal JSON format:

Routes

List all package routes:

DJPayKit registers:

Frontend widget integration

Install the core widget after it is published:

For local development:

Register the custom element in the application's JavaScript entry:

Example Laravel Blade integration:

The first enabled method is selected automatically. Selecting another provider updates its account details and QR without reloading the page.

Widget events

The host checkout can observe provider selection:

The host checkout can also observe successful QR downloads:

For the simplest integration, serve the Laravel API and widget from the same origin. Cross-origin integrations require the host application's CORS configuration to allow the checkout website.

Package development

Install dependencies:

Run tests:

Run a specific test:

On Windows, if Git Bash cannot run the Unix vendor launcher, use:

Current verified result:

License

DJPayKit Laravel is open-source software licensed under the MIT License.