PHPackages                             decodeblock/laravel-ercaspay - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. decodeblock/laravel-ercaspay

ActiveLibrary[API Development](/categories/api)

decodeblock/laravel-ercaspay
============================

A Laravel Package for working with Ercaspay API seamlessly

v1.0.0(1y ago)01[5 PRs](https://github.com/decodeblock/laravel-ercaspay/pulls)MITPHPPHP ^8.4||^8.3CI passing

Since Dec 17Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/decodeblock/laravel-ercaspay)[ Packagist](https://packagist.org/packages/decodeblock/laravel-ercaspay)[ Docs](https://github.com/decodeblock/laravel-ercaspay)[ GitHub Sponsors](https://github.com/Decodeblock)[ RSS](/packages/decodeblock-laravel-ercaspay/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (13)Versions (8)Used By (0)

Laravel Ercaspay
================

[](#laravel-ercaspay)

A Laravel package for seamless integration with the Ercaspay payment gateway API.

[![License](https://camo.githubusercontent.com/9341485488a82f21afc2591570961e2e5852968524b4ec3bd8a10de4b3bb1850/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6465636f6465626c6f636b2f6c61726176656c2d65726361737061792e7376673f7374796c653d666c61742d737175617265)](https://opensource.org/licenses/MIT)[![Latest Version on Packagist](https://camo.githubusercontent.com/35eece8090a673e98c720bc5b88b8a8bef595bb0eab88e86a853414ece2a7653/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6465636f6465626c6f636b2f6c61726176656c2d65726361737061792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/decodeblock/laravel-ercaspay)[![Tests Status](https://camo.githubusercontent.com/68804740dcd1be4a5f3d96309578b248e65c077faf4693acf5ad70fef698c117/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6465636f6465626c6f636b2f6c61726176656c2d65726361737061792f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/decodeblock/laravel-ercaspay/actions?query=workflow%3Arun-tests+branch%3Amain)[![Code Style Status](https://camo.githubusercontent.com/e9dd3547a5603ef135885ef1d1485807e976a6c18fe47d4b3193511c2e9b2db2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6465636f6465626c6f636b2f6c61726176656c2d65726361737061792f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/decodeblock/laravel-ercaspay/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/c6186347ed9b8ccce990eafb7c0e3ae0882f04163a4e9857c5d4da1e61138522/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6465636f6465626c6f636b2f6c61726176656c2d65726361737061792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/decodeblock/laravel-ercaspay)[![Contributors](https://camo.githubusercontent.com/978544fb6b7db4bfa29a816952c81c098e5ed30b7594878ba5389dd2debef966/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6e7472696275746f72732f6465636f6465626c6f636b2f6c61726176656c2d65726361737061792e7376673f7374796c653d666c61742d737175617265)](https://github.com/decodeblock/laravel-ercaspay/graphs/contributors)[![PHP Version Support](https://camo.githubusercontent.com/64c11def96ae40b342322e4bb1923bc6465260c09f9ffafc308659a9818f5788/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6465636f6465626c6f636b2f6c61726176656c2d65726361737061792e7376673f7374796c653d666c61742d737175617265)](https://www.php.net/)

Features
--------

[](#features)

- Easy integration with Ercaspay payment gateway API
- Support for multiple payment methods
- Payment verification
- Comprehensive error handling

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Laravel 9.0 or higher
- You need to reference the Ercaspay API documentation. [Click here for the documentation](https://docs.ercaspay.com/#2f601f17-0bde-44ba-971a-f8458cadb213)

Installation
------------

[](#installation)

Install the package via composer:

```
composer require decodeblock/laravel-ercaspay
```

Configuration
-------------

[](#configuration)

1. Publish the config file:

    ```
    php artisan vendor:publish --tag="ercaspay-config"
    ```
2. Add your Ercaspay credentials to your .env file:

    ```
    ERCASPAY_PUBLIC_KEY=your_public_key
    ERCASPAY_SECRET_KEY=your_secret_key

    ```

Usage Example
-------------

[](#usage-example)

Here are some examples of how to use this package:

### Generate Payment Reference UUID

[](#generate-payment-reference-uuid)

```
use Decodeblock\Ercaspay;

$ercaspay = new Ercaspay();
$referenceUuid = $ercaspay->generatePaymentReferenceUuid();
echo "Generated Reference UUID: " . $referenceUuid;
```

### Initiate a Transaction

[](#initiate-a-transaction)

```
use Decodeblock\Ercaspay;

$ercaspay = new Ercaspay();
$referenceUuid = $ercaspay->generatePaymentReferenceUuid();
$response = $ercaspay->initiateTransaction([
    'paymentReference' => $referenceUuid,
    'amount' => 2000,
    'currency' => 'NGN',
    'description' => 'Payment for services',
    'paymentMethods' => 'card, bank-transfer',
    'customerName' => 'John Doe',
    'customerEmail' => 'john@example.com',
]);

print_r($response);

echo "Request status is: " . $response['responseMessage']
```

### Verify a Transaction

[](#verify-a-transaction)

```
$response = $ercaspay->verifyTransaction('transaction_reference');

print_r($response);
```

### Initiate a Bank Transfer

[](#initiate-a-bank-transfer)

```
$response = $ercaspay->initiateBankTransfer('transaction_reference');

print_r($response);
```

### Initiate a Card Transaction

[](#initiate-a-card-transaction)

```
$transactionRef = 'TEST-REF-'.time();
$cardNumber = '4111111111111111';
$cardExpiryMonth = '12';
$cardExpiryYear = '25';
$cardCvv = '123';
$pin = '1234';

$response = $this->ercaspay->initiateCardTransaction(
    $request,
    $transactionRef,
    $cardNumber,
    $cardExpiryMonth,
    $cardExpiryYear,
    $cardCvv,
    $pin
);

print_r($response);
```

Available Methods
-----------------

[](#available-methods)

Below are all the methods available in the package:

```
/**
 * Initiates a new payment transaction
 *
 * @param array $data Transaction details including amount, reference etc
 * @return array Ercaspay API Response
 */
public function initiateTransaction(array $data): array
```

```
/**
 * Verifies the status of a transaction
 *
 * @param string $transactionRef Transaction reference to verify
 * @return array Ercaspay API Response
 */
public function verifyTransaction(string $transactionRef): array
```

```
/**
 * Initiates a bank transfer payment
 *
 * @param string $transactionRef Transaction reference
 * @return array Ercaspay API Response
 */
public function initiateBankTransfer(string $transactionRef): array
```

```
/**
 * Initiates a USSD payment transaction
 *
 * @param string $transactionRef Transaction reference
 * @param string $bankName Name of bank for USSD
 * @return array Ercaspay API Response
 */
public function initiateUssdTransaction(string $transactionRef, string $bankName): array
```

```
/**
     * Initiates a card payment transaction
     *
     * @param  Request  $request  HTTP request object
     * @param  string  $transactionRef  Transaction reference
     * @param  string  $cardNumber  Card number
     * @param  string  $cardExpiryMonth  Card expiry month
     * @param  string  $cardExpiryYear  Card expiry year
     * @param  string  $cardCvv  Card CVV code
     * @param  string  $pin  Card PIN
     * @return array Ercaspay API Response
     */
    public function initiateCardTransaction(Request $request, string $transactionRef, string $cardNumber, string $cardExpiryMonth, string $cardExpiryYear, string $cardCvv, string $pin): array
```

```
/**
 * Gets list of banks that support USSD payments
 *
 * @return array Ercaspay API Response
 */
public function getBankListForUssd(): array
```

```
/**
 * Generates a unique payment reference ID
 *
 * @return string UUID for payment reference
 */
public function generatePaymentReferenceUuid(): string
```

```
/**
 * Fetches details for a transaction
 *
 * @param string $transactionRef Transaction reference
 * @return array Ercaspay API Response
 */
public function fetchTransactionDetails(string $transactionRef): array
```

```
/**
 * Checks the current status of a transaction
 *
 * @param string $transactionRef Transaction reference
 * @param string $paymentReference Payment reference
 * @param string $paymentMethod Payment method used
 * @return array Ercaspay API Response
 */
public function fetchTransactionStatus(string $transactionRef, string $paymentReference, string $paymentMethod): array
```

```
/**
 * Cancels a transaction
 *
 * @param string $transactionRef Transaction reference to cancel
 * @return array Ercaspay API Response
 */
public function cancelTransaction(string $transactionRef): array
```

To provide clear and helpful information about the exceptions in your README, you can include a dedicated section about error handling and exception types. This section should describe the different exceptions that developers may encounter while using your package, their causes, and how to handle them.

Here's a sample section you can include in your `README.md`:

---

Error Handling and Exceptions
-----------------------------

[](#error-handling-and-exceptions)

Your package may throw different types of exceptions based on the outcomes of HTTP requests made to the Ercaspay API. Below is a list of the key exceptions you should be aware of when integrating and working with this package:

### 1. `ErcaspayRequestException`

[](#1-ercaspayrequestexception)

**Thrown when:**

- There is an issue with the request, such as a failure in communication or missing parameters.
- The error message is user-defined and includes detailed context from the API.

**Usage Example:**

```
use YourPackage\Exceptions\ErcaspayRequestException;

try {
    // API call
} catch (ErcaspayRequestException $e) {
    // Access the error message
    echo $e->getMessage();

    // Access additional error data
    print_r($e->getResponse());
}
```

**What You Can Expect:**

- `getMessage()` – Returns a description of the error (e.g., "Request failed").
- `getCode()` – Provides the error code (could be an HTTP status code or `0` for network-related errors).
- `getResponse()` – Returns additional data provided by the API or error context.

---

### 2. `ErcaspayClientErrorException`

[](#2-ercaspayclienterrorexception)

**Thrown when:**

- The API responds with a client-side error (HTTP status code 4xx).
- This exception is thrown when a request is malformed or contains invalid parameters.

**Usage Example:**

```
use YourPackage\Exceptions\ErcaspayClientErrorException;

try {
    // API call
} catch (ErcaspayClientErrorException $e) {
    // Log or handle the 4xx error appropriately
    echo $e->getMessage();

    // Access additional error data
    print_r($e->getResponse());
}
```

**What You Can Expect:**

- Contains the same methods as `ErcaspayRequestException`.
- Additional information about client-side issues, such as invalid parameters or incorrect input.

---

### 3. `ErcaspayServerErrorException`

[](#3-ercaspayservererrorexception)

**Thrown when:**

- The API responds with a server-side error (HTTP status code 5xx).
- This exception is used when something goes wrong on the server, such as a server crash or unavailable service.

**Usage Example:**

```
use YourPackage\Exceptions\ErcaspayServerErrorException;

try {
    // API call
} catch (ErcaspayServerErrorException $e) {
    // Handle server-side issues, possibly by retrying or reporting to the support team
    echo $e->getMessage();

    // Access additional error data
    print_r($e->getResponse());
}
```

**What You Can Expect:**

- Same structure as the other exceptions but specifically for server-related issues.
- Contains error data related to server failures.

Logging
-------

[](#logging)

This package provides logging capabilities to help you monitor and troubleshoot API interactions and errors. By default, important information about API requests, responses, and exceptions is logged, which can be useful for debugging and keeping track of system behavior.

### What is Logged?

[](#what-is-logged)

The package logs the following information:

#### 1. API Request Details:

[](#1-api-request-details)

- URL of the API endpoint
- HTTP method (GET, POST, etc.)

#### 2. API Response Details:

[](#2-api-response-details)

- HTTP status code of the response
- Response body (if available)
- Error messages (for failed requests)

#### 3. Exceptions:

[](#3-exceptions)

- Details of exceptions, including client and server errors
- Stack trace and error context for easier debugging

Changelog
---------

[](#changelog)

Detailed changes for each release are documented in the [CHANGELOG](CHANGELOG.md).

Contributing
------------

[](#contributing)

We welcome contributions! Please see the [CONTRIBUTING](CONTRIBUTING.md) guide for details.

Credits
-------

[](#credits)

- **[Gabriel Ibenye](https://github.com/gabbyti)**
- [All Contributors](../../contributors)

License
-------

[](#license)

This package is licensed under the [MIT License](LICENSE.md).

###  Health Score

38

—

LowBetter than 84% of packages

Maintenance74

Regular maintenance activity

Popularity1

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 76.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

508d ago

Major Versions

v0.1.0 → v1.0.02024-12-17

### Community

Maintainers

![](https://www.gravatar.com/avatar/4341becacf17391bee4cb4334e44546b3056aec0d4ad36a0e216102618d7d9a8?d=identicon)[gabbyti](/maintainers/gabbyti)

---

Top Contributors

[![gabbyTI](https://avatars.githubusercontent.com/u/34938103?v=4)](https://github.com/gabbyTI "gabbyTI (36 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (6 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (5 commits)")

---

Tags

laravelDecodeblocklaravel-ercaspay

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/decodeblock-laravel-ercaspay/health.svg)

```
[![Health](https://phpackages.com/badges/decodeblock-laravel-ercaspay/health.svg)](https://phpackages.com/packages/decodeblock-laravel-ercaspay)
```

###  Alternatives

[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[scalar/laravel

Render your OpenAPI-based API reference

6183.9k2](/packages/scalar-laravel)[ryangjchandler/bearer

Minimalistic token-based authentication for Laravel API endpoints.

8129.8k](/packages/ryangjchandler-bearer)[codebar-ag/laravel-docuware

DocuWare integration with Laravel

1221.1k](/packages/codebar-ag-laravel-docuware)[combindma/laravel-facebook-pixel

Meta pixel integration for Laravel

4956.9k](/packages/combindma-laravel-facebook-pixel)[stechstudio/laravel-hubspot

A Laravel SDK for the HubSpot CRM Api

2971.0k](/packages/stechstudio-laravel-hubspot)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)