Download the PHP package alsharie/jawali-payment without Composer

Laravel Jawali API Client

Jawali Payment is a Laravel package for interacting with the Jawali payment gateway. It provides a simple API to perform operations like ecommerce inquiry and cash out, with automatic token management and structured responses.

Installation

1. Require the package using Composer:

   (Replace alsharie/jawali-payment with your actual package name on Packagist if you publish it, or use a local path repository for development).

2. Publish the configuration file (optional, but recommended):

   This will create a config/jawali.php file.

3. Add the following environment variables to your .env file and configure them:

Configuration

The package uses Laravel's configuration system. After publishing the config file, you can find it at config/jawali.php. The configuration is structured as follows:

The disable_ssl_verification option is particularly useful when working with development environments or self-signed certificates.

Logging Configuration

The package includes built-in logging capabilities for debugging API requests and responses. To enable logging:

1. Enable logging in your .env file:

2. Ensure the logs directory is writable:

The package will log all API interactions using Laravel's default logging system. Log entries include:

• Request method, URL, and payload (with sensitive data redacted)
• Response status and data
• Error details with context

Note: Logging errors are silently ignored to prevent them from breaking the main application functionality.

Features

This package provides the following features:

1. Structured Response Classes: Each API response is wrapped in a dedicated response class that provides methods to access the data in a type-safe way.
2. Automatic Token Management: The package automatically manages authentication and wallet tokens, refreshing them when needed.
3. Retry Mechanism: Failed requests due to token expiration or certain HTTP status codes are automatically retried.
4. SSL Verification Control: Option to disable SSL verification for development or when working with self-signed certificates.
5. Simplified API: The API is simplified to focus on the essential parameters, with tokens managed automatically.
6. Enhanced Error Handling: Comprehensive error information with API response preservation and user-friendly error messages.
7. Optional Logging: Built-in request/response logging for debugging purposes.
8. Input Validation: Automatic validation of request parameters to prevent common errors.

Usage

You can use the Jawali facade or inject the Alsharie\Jawali\Services\JawaliService class.

Enhanced Error Handling

The package now provides comprehensive error handling with detailed API response information and standardized method names that match successful responses:

Standardized Method Names

Both successful responses and exceptions now use the same method names for consistency:

Example - Same methods work for both success and error:

Breaking Change: Old method names (getApiResponse(), getApiResponseBody(), getApiResponseHeaders()) have been removed. Use the standardized method names instead.

Debugging and Logging

Enable logging to debug API requests and responses:

The package automatically logs:

• API requests (with sensitive data redacted)
• API responses
• Error details and context
• Token refresh attempts

Explanation

• loginToSystem()
  This method authenticates with the Jawali system using the credentials from your configuration. The response is an instance of JawaliLoginResponse which provides access to the authentication token.

• walletAuthentication()
  After system login, this method authenticates your wallet. The response is an instance of JawaliWalletAuthResponse which provides access to the wallet token.

• ecommerceInquiry()
  This method contacts the gateway to verify payment details. The response is an instance of JawaliEcommerceInquiryResponse which provides methods like getAmount(), getCurrency(), and getState().

• ecommerceCashout()
  When the inquiry indicates a pending state with the correct amount and currency, this method is called to complete the cash-out. Its response is wrapped in the JawaliEcommerceCashoutResponse class.

• Response Handling
  All response classes extend the base JawaliResponse class (except JawaliLoginResponse). They provide methods like isSuccess(), getErrorMessage(), and getData() for consistent response handling.

License

This package is open-sourced software licensed under the MIT license.