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.
• Inbound Notification Lab:
  • Receives VA Static at /faspay/sandbox/notification/v1.0/transfer-va/payment.
  • Receives QRIS at /faspay/sandbox/notification/v1.0/qr/qr-mpm-notify.
  • Receives Direct Debit at /faspay/sandbox/notification/v1.0/debit/notify.
  • Includes an isolated VA sandbox account generator and SNAP Inquiry receiver at /faspay/sandbox/notification/v1.0/transfer-va/inquiry.
  • Receives the official SNAP QRIS callback for case 18.25.
  • 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

1. Open your browser and navigate to:

   http://localhost:8000/faspay-test-lab
   

2. 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.
3. Run Automated Tests: Click "Run All Automated Tests" or execute individual cases.
4. 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".
5. 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/notification/v1.0/qr/qr-mpm-notify

The receiver is enabled by default. 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.

VA Static and Direct Debit Notifications

Configure the confirmed sandbox callback URLs as:

VA Static:    https://your-domain.example/faspay/sandbox/notification/v1.0/transfer-va/payment
QRIS:         https://your-domain.example/faspay/sandbox/notification/v1.0/qr/qr-mpm-notify
Direct Debit: https://your-domain.example/faspay/sandbox/notification/v1.0/debit/notify

The isolated VA callback lab is enabled by default. The VA and QRIS receivers share FASPAY_TEST_LAB_FASPAY_PUBLIC_KEY unless VA-specific key settings are supplied. Any receiver can be explicitly disabled by setting its *_ENABLED variable to false.

Direct Debit uses its legacy signature and response format at the confirmed URL:

FASPAY_TEST_LAB_DIRECT_DEBIT_NOTIFICATION_ENABLED=true
FASPAY_TEST_LAB_DIRECT_DEBIT_USER_ID=...
FASPAY_TEST_LAB_DIRECT_DEBIT_PASSWORD=...
FASPAY_TEST_LAB_DIRECT_DEBIT_MERCHANT_ID=37073

Callback history

The package includes its own callback inbox at /faspay-test-lab/callbacks; no third-party log viewer is required. Every request reaching a package callback route is recorded before validation, including invalid bodies, missing headers, bad signatures, unmatched transactions, throttled requests, and processing exceptions.

The list can be filtered by service and outcome. Each detail page shows request metadata, sanitized headers and body, merchant response, signature status, and any processing error. Individual records or the complete history can be deleted from the UI. Signature values are never persisted.

If no record appears after a payment, the request did not reach Laravel. Check the URL configured by Faspay, DNS/proxy access logs, firewall or WAF rules, and cached Laravel routes.

⚙️ 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.