decodeblock / laravel-ercaspay
A Laravel Package for working with Ercaspay API seamlessly
Fund package maintenance!
Decodeblock
Requires
- php: ^8.4||^8.3
- guzzlehttp/guzzle: ^7.9
- illuminate/contracts: ^10.0||^11.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^2.9
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1||^7.10.0
- orchestra/testbench: ^9.0.0||^8.22.0
- pestphp/pest: ^3.0||^2.0
- pestphp/pest-plugin-arch: ^3.0||^2.0
- pestphp/pest-plugin-laravel: ^3.0||^2.0
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
This package is auto-updated.
Last update: 2025-05-12 23:41:20 UTC
README
A Laravel package for seamless integration with the Ercaspay payment gateway API.
Features
- Easy integration with Ercaspay payment gateway API
- Support for multiple payment methods
- Payment verification
- Comprehensive error handling
Requirements
- PHP 8.3 or higher
- Laravel 9.0 or higher
- You need to reference the Ercaspay API documentation. Click here for the documentation
Installation
Install the package via composer:
composer require decodeblock/laravel-ercaspay
Configuration
-
Publish the config file:
php artisan vendor:publish --tag="ercaspay-config"
-
Add your Ercaspay credentials to your .env file:
ERCASPAY_PUBLIC_KEY=your_public_key ERCASPAY_SECRET_KEY=your_secret_key
Usage Example
Here are some examples of how to use this package:
Generate Payment Reference UUID
use Decodeblock\Ercaspay; $ercaspay = new Ercaspay(); $referenceUuid = $ercaspay->generatePaymentReferenceUuid(); echo "Generated Reference UUID: " . $referenceUuid;
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
$response = $ercaspay->verifyTransaction('transaction_reference'); print_r($response);
Initiate a Bank Transfer
$response = $ercaspay->initiateBankTransfer('transaction_reference'); print_r($response);
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
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
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
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 or0
for network-related errors).getResponse()
– Returns additional data provided by the API or error context.
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
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
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?
The package logs the following information:
1. API Request Details:
- URL of the API endpoint
- HTTP method (GET, POST, etc.)
2. API Response Details:
- HTTP status code of the response
- Response body (if available)
- Error messages (for failed requests)
3. Exceptions:
- Details of exceptions, including client and server errors
- Stack trace and error context for easier debugging
Changelog
Detailed changes for each release are documented in the CHANGELOG.
Contributing
We welcome contributions! Please see the CONTRIBUTING guide for details.
Credits
License
This package is licensed under the MIT License.