README

A developer-friendly Laravel extension / package that provides an automated testing lab and official UAT certification evidence generator for Faspay SNAP (QRIS, Virtual Account, Direct Debit).

Install it into any existing Laravel project with a single composer require command—no need to clone a boilerplate or juggle complicated Postman workspaces.

🎯 Features & Scope

Zero Project Overlap:
- Isolated route prefix: /faspay-test-lab (configurable).
- Unique route names: faspay-test-lab.*.
- Dedicated view namespace: faspay-test-lab::*.
- Isolated database tables: faspay_test_lab_merchants and faspay_test_lab_runs.
- Environment guard: auto-disabled in production unless explicitly turned on.
Automated UAT Certification Scenarios:
- Runs Faspay SNAP QRIS scenarios (18.1 – 18.25) with live progress and single-case rerun capability.
- Generates valid SNAP SHA256withRSA signatures on the fly.
- Multi-request evidence capture for conflict and query flows.
Bundled Official Faspay Excel Templates:
- FASPAY QRIS - Skenario Functional Test_V.3.2.xlsx
- Faspay VA - Skenario Functional Test_V.3.0 static.xlsx
- FASPAY Direct Debit - Skenario Functional Test_V.3.2.xlsx
- Directly loads bundled templates via PhpSpreadsheet and outputs official certification evidence in one click.
Interactive Payment Flow (Case 18.12):
- Reuses QR generated in case 18.6 with built-in auto-polling for payment confirmation via Faspay Payment Simulator.
QRIS Payment Notification Evidence (Case 18.25):
- Receives the official SNAP QRIS callback at /faspay/sandbox/v1.0/qr/qr-mpm-notify.
- Verifies Faspay's SHA256withRSA signature, matches references generated by case 18.6, and records the callback request and merchant response in the test run.
- Never settles or modifies application payments; the endpoint only updates isolated Test Lab evidence.
Security-First:
- Private keys are encrypted at rest using Laravel's application key (APP_KEY).
- Private keys are hidden from UI, API responses, logs, and exported spreadsheets.

📦 Installation

Install the package via Composer into your Laravel application:

composer require vonsofh/laravel-faspay-test-lab --dev

Run the install command to publish the config and run migrations:

php artisan faspay-test-lab:install

(Or run php artisan migrate directly—package auto-discovery takes care of everything).

For automated production deployment, install the package as a regular dependency (not require-dev) because Faspay must reach the notification endpoint in production:

composer require vonsofh/laravel-faspay-test-lab
php artisan migrate --force

🚀 Usage

Open your browser and navigate to:
```
http://localhost:8000/faspay-test-lab
```
Add a Merchant Profile: Enter your Faspay Merchant ID, Base URL (https://debit-sandbox.faspay.co.id), Channel ID, QRIS Channel Code, and RSA Private Key PEM.
Run Automated Tests: Click "Run All Automated Tests" or execute individual cases.
Test Payment Verification (18.12): Scan or copy the QR from case 18.6, pay via the Faspay Sandbox Simulator, and click "Check Payment Status" or "Start Auto Check".
Download Official Excel Report: Click "Export XLSX" on the result page to download the populated official Faspay certification spreadsheet.

QRIS Payment Notification (Case 18.25)

Configure Faspay's sandbox notification URL as:

https://your-domain.example/faspay/sandbox/v1.0/qr/qr-mpm-notify

Enable the receiver and configure the public key supplied by Faspay in the host application's .env:

FASPAY_TEST_LAB_QRIS_NOTIFICATION_ENABLED=true
FASPAY_TEST_LAB_FASPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

The public key can alternatively be read from a server-side file:

FASPAY_TEST_LAB_FASPAY_PUBLIC_KEY_PATH=/absolute/path/to/faspay-public-key.pem

If the host already defines FASPAY_SANDBOX_PUBLIC_KEY_PATH, the package uses that file automatically.

The legacy Debit Transaction endpoint /faspay/sandbox/payment-notification is a different protocol and must not be used for SNAP QRIS notification.

⚙️ Configuration (Optional)

Publish the configuration file:

php artisan vendor:publish --tag=faspay-test-lab-config

In config/faspay-test-lab.php:

return [
    // null = enabled only in 'local' and 'testing' environments
    'enabled' => env('FASPAY_TEST_LAB_ENABLED', null),

    // Dashboard route prefix
    'route_prefix' => env('FASPAY_TEST_LAB_PREFIX', 'faspay-test-lab'),

    // Route middleware
    'middleware' => ['web'],

    // Table names
    'tables' => [
        'merchants' => 'faspay_test_lab_merchants',
        'runs' => 'faspay_test_lab_runs',
    ],
];

🎨 Customizing Views or Templates

If you wish to customize the Blade views or templates:

# Publish views to resources/views/vendor/faspay-test-lab
php artisan vendor:publish --tag=faspay-test-lab-views

# Publish Excel templates to storage/app/templates/faspay
php artisan vendor:publish --tag=faspay-test-lab-templates

🔒 Security

The package includes EnsureTestLabEnabled middleware that automatically returns HTTP 404 in non-local environments unless FASPAY_TEST_LAB_ENABLED=true is explicitly set in .env.
Merchant private keys are stored encrypted via Laravel's native encrypted model cast and are never exposed in JSON responses or exported files.

📄 License

The MIT License (MIT). Please see License File for more information.

vonsofh / laravel-faspay-test-lab

Package info

Security

Statistics