Download the PHP package hansajith18/laravel-paycorp without Composer

laravel-paycorp

Laravel integration for the Paycorp (Bancstac) payment gateway.

Supports the Paycorp Paycenter Web 4.0 API — Hosted Page flow, Real-Time tokenised card payments, and Refund/Void operations — with full database audit logging and PCI DSS safe-handling baked in.

Features

• Hosted Page flow — redirect payer to Paycorp-hosted card entry, receive callback
• Card tokenization — save a card during a hosted-page flow; verification charge is auto-voided
• Real-Time flow — charge previously saved cards instantly, without any redirect
• Refund & Void — session-authenticated back-office API with AES-256 encryption
• HMAC-SHA256 request signing — every outgoing request is signed
• Customisable payment purposes — swap in your own enum via PaymentPurposeContract
• Auto-registered log channel — paycorp-YYYY-MM-DD.log with zero config required
• Sandbox mode — automatic amount normalisation for the Paycorp test environment
• Full gateway audit log — all requests/responses written to payment_gateway_logs table
• PCI DSS safe — never stores raw card numbers or CVVs; only masked card data persisted
• Laravel 10, 11, 12, and 13 support

Requirements

• PHP ^8.2
• Laravel ^10.0, ^11.0, ^12.0, or ^13.0
• ext-openssl

Installation

The service provider is auto-discovered. No manual registration required.

Publish config and migrations

Or publish individually:

Then run migrations:

Configuration

Add the following to your .env file:

The package auto-registers a paycorp daily log channel — no changes to config/logging.php are needed. To redirect logs to an existing channel (e.g. stack), set PAYCORP_LOG_CHANNEL=stack.

Payment Flows Overview

The package supports three distinct payment flows:

Use PaycenterPaymentService for fully persisted, audited, event-dispatching workflows (recommended). Use PaycorpClient directly when you need raw gateway access without database involvement.

Usage

Flow A — Normal Purchase (Hosted Page)

The payer is redirected to the Paycorp-hosted card entry page. After they complete payment, Paycorp redirects them back to your PAYCORP_RETURN_URL with a reqid parameter. You call completePayment in that callback to finalise the transaction.

Step 1 — Initialise the payment

Step 2 — Complete the payment (your callback route)

Paycorp sends the payer back to PAYCORP_RETURN_URL?reqid=.... Handle it here:

completePayment is idempotent — a database lock prevents the gateway from being called more than once per reqid, even under concurrent callbacks.

Flow B — Save a Card (Card Registration / Tokenization)

Card registration uses the same two-step hosted-page flow as a normal purchase. The only differences are the purpose and tokenize: true flag. Paycorp charges a small verification amount, but the package automatically voids (reverses) that charge after the card token is saved — the customer is never charged.

Step 1 — Initialise card registration

Step 2 — Complete card registration (same callback route as Flow A)

What happens automatically after completion:

• The card token is stored in saved_payments and linked to the user.
• The VoidTokenizationCharge queued job fires, sending a void request to Paycorp to reverse the verification charge. The job retries up to 5 times with exponential backoff.
• The Payment status transitions from completed → voided after a successful void.

Flow C — Charge a Saved Card (Real-Time, No Redirect)

Once a card has been saved via Flow B, you can charge it directly without any hosted-page redirect. The charge result is synchronous and immediately available.

No redirect is involved — chargeWithSavedPayment returns the final Payment model synchronously after the gateway responds.

Refund

Refund credentials (PAYCORP_REFUND_*) must be configured. The refund gateway is not available by default.

Direct Gateway Access (Advanced)

For scenarios where you don't need database persistence or events, use PaycorpClient directly:

Events

Both PaycenterPaymentService flows dispatch events after a gateway response. Listen to them in your AppServiceProvider or a dedicated listener:

Custom Payment Purposes

The package ships with a built-in PaymentPurposeEnum containing generic cases:

You can replace this entirely with your own string-backed enum by implementing PaymentPurposeContract:

Register it in config/paycorp.php:

Your enum is now used for $payment->purpose casting, client-reference prefix generation, and the gateway comment label — no other changes needed.

Payable Model Integration (Optional)

Linking a payment to a model

Pass payableType (fully-qualified class name) and payableId to initializePayment or chargeWithSavedPayment:

Note: Passing a class name that does not exist throws a ValidationException immediately, before any DB insert, to prevent a confusing "Class not found" error from Eloquent at query time.

Auto-updating a status column on the payable

When a payment completes or fails, the service can automatically update a column on the related payable model. Configure this in config/paycorp.php:

Leave payable_status_classes empty (the default) and handle status updates in your own event listeners instead — this gives full control and keeps your domain logic in one place.

Database Tables

Payment Status Transitions

Sandbox Mode

Set PAYCORP_SANDBOX=true when using the Paycorp test environment. The package automatically:

• Strips sub-unit cents (e.g. 5389.20 LKR → 5389.00 LKR)
• Enforces a minimum amount of 200 cents (2.00 LKR)

No code changes are needed between sandbox and production.

Testing

Or directly:

Quality Tooling

Security

• All API requests are signed with HMAC-SHA256
• TLS verification enforced (verify: true) — HTTP connections always use TLS
• Card numbers and CVVs are never stored — only masked card data persisted
• toSafeArray() explicitly excludes cardholder name, raw expiry, and internal comments
• Refund credentials are AES-256-CBC encrypted before transmission
• Gateway audit logs sanitise all sensitive fields before writing to the database
• Missing client IDs, refund credentials, or endpoint config throw clear RuntimeException messages at startup rather than sending malformed requests to the gateway

Please see SECURITY.md for how to report a security vulnerability.

Changelog

See CHANGELOG.md for release history.

For maintainers: see docs/releases.md for the full release workflow guide.

License

The MIT License (MIT). See LICENSE for details.

Credits

• Navod Hansajith