Download the PHP package bayarcash/laravel without Composer

Bayarcash for Laravel

A Laravel integration for the Bayarcash payment gateway. It wraps the framework-agnostic bayarcash/php-sdk and adds a Laravel-idiomatic developer experience: config, a facade, a model trait, optional database persistence, automatic callback/return handling with checksum verification, scheduled reconciliation, and events.

Targets Bayarcash API v3.

It fits two setups:

• Single merchant — one set of credentials in .env. Everything in Usage works out of the box.
• Multi-tenant (SaaS) — each tenant has its own Bayarcash account with credentials stored in your database. See Multi-tenant.

Either way you choose whether to store payment records in your database with BAYARCASH_STORE_RECORDS.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12

Installation

Publish the config file:

Publish and run the migrations (skip if you want stateless mode):

Configuration

Add your credentials to .env:

In the Bayarcash portal, point your portal's URLs at the package routes:

• Callback URL → https://your-app.test/bayarcash/callback
• Return URL → https://your-app.test/bayarcash/return

Usage

1. Make a model payable

Add the HasBayarcashPayments trait to any Eloquent model (an Order, User, Invoice, ...):

This adds payments() and mandates() relations plus the charge() and enrollDirectDebit() helpers.

2. Create a payment

The checksum is generated for you. When record storage is enabled, a pending BayarcashTransaction is stored and linked to $order, and a PaymentCreated event fires.

3. Enrol a Direct Debit mandate

4. Handle results

The package registers two routes automatically — you do not write controllers:

Set BAYARCASH_RETURN_REDIRECT to a named route or URL to control where the customer lands after payment. When it is null, the return route responds with JSON.

5. Listen for events

Available events:

6. Query stored records

Reconciliation

Callbacks and return redirects can be missed (downtime, network issues). The package ships a bayarcash:reconcile command that re-queries pending payments and auto-cancels stale ones. It is scheduled automatically (every minute) when BAYARCASH_RECONCILE=true — you only need Laravel's scheduler running:

You can also run it manually:

Reconciliation requires stored records.

Store records (store data, or pass-through)

BAYARCASH_STORE_RECORDS decides whether the package keeps a local copy of every payment and mandate in your database.

BAYARCASH_STORE_RECORDS=true (default) — stateful

Transactions and mandates are recorded in the bayarcash_transactions and bayarcash_mandates tables. This is what you get:

Requires the migrations:

Use this mode when you want an authoritative local record of payments (reporting, reconciliation, linking payments to your models) — the typical SaaS setup.

BAYARCASH_STORE_RECORDS=false — stateless (pass-through)

The package becomes a thin SDK wrapper. charge() / enrollDirectDebit() create the intent and return it without touching the database, and the callback/return routes still verify checksums and fire events — they just skip persistence. No migrations are needed, and bayarcash:reconcile is disabled. Use this when you already store payment state yourself and only want checksum-safe request/callback handling.

Multi-tenant (credentials in the database)

In a SaaS app each tenant has its own Bayarcash account. Store each tenant's credentials in your own table and let the package resolve them per request. There is one shared webhook for every tenant — no tenant id in the URL.

1. Store per-tenant credentials

The package ships an encrypted bayarcash_accounts table for this. Publish and run it:

Then store each tenant's credentials — token and secret_key are encrypted at rest:

2. Turn multi-tenant on

Point the package at its built-in resolver and enable multi-tenant:

Credentials already elsewhere? If your tenants' Bayarcash credentials live on your own model/table, skip the migration and implement the resolver yourself instead — return token, secret_key, and sandbox for a tenant:

3. Create payments per tenant

Pass the tenant to charge() / enrollDirectDebit(). The package generates the checksum and calls the gateway with that tenant's credentials, and stamps the stored row with tenant_id:

With no tenant: argument the default .env credentials are used — so single- and multi-tenant code live side by side.

4. One shared webhook for every tenant

Point every tenant's portal Callback/Return URLs at the same package routes — https://your-app.test/bayarcash/callback and .../bayarcash/return. There is no per-tenant URL.

The package matches each callback to its local record, resolves that tenant's secret, and verifies the checksum — rejecting with 403 (fail closed) when no record matches. This lookup is why multi-tenant mode requires BAYARCASH_STORE_RECORDS=true.

The facade

For direct, lower-level access to the SDK:

The facade proxies to the underlying Bayarcash\Bayarcash client (pinned to API v3).

Error handling

SDK calls throw typed exceptions you can catch around charge() / enrollDirectDebit():

Testing

License

The MIT License (MIT).