granada-pride/clickpaysa

Clickpaysa Payment Gateway Integration with Laravel Framework

v2.1.4 2024-09-01 12:20 UTC

MIT

• Hussein Gaber

README

Clickpaysa Payment Gateway Integration for Laravel

Table of Contents

1. Description
2. Installation
3. Configuration
4. Usage
   • Creating a PayPage
   • Querying Transactions
   • Capturing a Payment
   • Refunding a Payment
   • Voiding a Payment
5. Troubleshooting
6. Testing
7. Contribution
8. License

Description

The laravel-clickpaysa package provides an easy way to integrate the Clickpaysa payment gateway into your Laravel applications. This package adheres to SOLID principles and uses modern PHP practices, ensuring your code is maintainable, testable, and scalable.

Installation

You can install the package via composer:

composer require granada-pride/clickpaysa

Configuration

After installation, publish the configuration file using the following command:

php artisan vendor:publish --provider="GranadaPride\Clickpay\ClickpayServiceProvider"

This will create a config/clickpay.php file. Here is an example of what the configuration file might look like:

return [

    /*
    |--------------------------------------------------------------------------
    | Clickpay Profile ID
    |--------------------------------------------------------------------------
    |
    | This is your Clickpay profile ID, which is required for making API 
    | requests. Ensure that this value is provided in your environment 
    | configuration file (.env).
    |
    */

    'profile_id' => env('CLICKPAY_PROFILE_ID'),

    /*
    |--------------------------------------------------------------------------
    | Clickpay Server Key
    |--------------------------------------------------------------------------
    |
    | Your Clickpay server key is used to authenticate API requests. Make 
    | sure to keep this value secure and do not expose it in your version 
    | control system. It should be stored in the .env file.
    |
    */

    'server_key' => env('CLICKPAY_SERVER_KEY'),

    /*
    |--------------------------------------------------------------------------
    | Default Currency
    |--------------------------------------------------------------------------
    |
    | The currency in which payments will be processed by default. You can 
    | change this to any currency supported by Clickpay (e.g., USD, EUR).
    | This value can also be configured in your .env file.
    |
    */

    'currency' => env('CLICKPAY_CURRENCY', 'SAR'),

    /*
    |--------------------------------------------------------------------------
    | Clickpay API Base URL
    |--------------------------------------------------------------------------
    |
    | The base URL for the Clickpay API. This is typically the endpoint where 
    | API requests are sent. You can change this value if Clickpay provides 
    | a different URL for specific regions or environments (e.g., testing).
    |
    */

    'base_url' => env('CLICKPAY_BASE_URL', 'https://secure.clickpay.com.sa'),

];

Environment Variables

Make sure to set the required environment variables in your .env file:

CLICKPAY_PROFILE_ID=your_profile_id
CLICKPAY_SERVER_KEY=your_server_key
CLICKPAY_CURRENCY=SAR
CLICKPAY_BASE_URL=https://secure.clickpay.com.sa

Usage

Creating a PayPage

Here's how to create a payment page using this package:

use GranadaPride\Clickpay\ClickpayClient;
use GranadaPride\Clickpay\DTO\CustomerDTO;
use GranadaPride\Clickpay\DTO\PaymentDTO;
use GranadaPride\Clickpay\Contracts\PaymentGatewayInterface;

$clickpay = app(PaymentGatewayInterface::class);

// Set CustomerDTO Information using the CustomerDTO DTO
$customerDTO = new CustomerDTO(
    name: 'Ahmad Mohamed',
    phone: '[phone]',
    email: '[e-mail]',
    street: '123 Main St',
    city: 'Cityville',
    state: 'Stateland',
    country: 'KSA',
    zipCode: '12345'
);

// Use CustomerDTO Information for Shipping if it's the same
$shippingDTO = $customerDTO;

// Set PaymentDTO Details
$paymentDTO = new PaymentDTO(
    cartId: 'CART123',
    cartAmount: 150.00,
    cartDescription: 'Sample Cart Description',
    customerDTO: $customerDTO,
    shippingDTO: $shippingDTO,
    callbackUrl: 'https://yourdomain.com/callback',
    returnUrl: 'https://yourdomain.com/return',
    paypageLang: 'ar',
    hideShipping: false  // Set to true if you want to hide shipping details on the payment page
);

// Or you can simply send only required data
$paymentDTO = new PaymentDTO(
    cartId: 'CART123',
    cartAmount: 150.00,
    cartDescription: 'Sample Cart Description',
    callbackUrl: 'https://yourdomain.com/callback',
    returnUrl: 'https://yourdomain.com/return',
    paypageLang: 'ar',
    hideShipping: false  // Set to true if you want to hide shipping details on the payment page
);

// Generate PaymentDTO Page
$response = $clickpay->createPaymentPage($paymentDTO);

dd($response);

Querying Transactions

You can also query a transaction using its reference:

use GranadaPride\Clickpay\Contracts\PaymentGatewayInterface;

$clickpay = app(PaymentGatewayInterface::class);

$response = $clickpay->queryTransaction('TST2422201903602');

dd($response);

Capturing a Payment

The capturePayment method allows you to capture a previously authorized transaction. This is typically used when a payment is authorized at the time of order placement, but you only want to capture the funds when the goods are shipped.

Example:

use GranadaPride\Clickpay\Contracts\PaymentGatewayInterface;

$clickpay = app(PaymentGatewayInterface::class);

$response = $clickpay->capturePayment(
    transactionReference: 'TST2112600164150',
    amount: 1.3,
    currency: 'SAR',
    cartId: 'cart_66666',
    cartDescription: 'Capture reason'
);

dd($response);

Refunding a Payment

The refundPayment method is used to refund a previously completed transaction. This can be useful when a customer requests a refund for their order.

Example:

use GranadaPride\Clickpay\Contracts\PaymentGatewayInterface;

$clickpay = app(PaymentGatewayInterface::class);

$response = $clickpay->refundPayment(
    transactionReference: 'TST2016700000692',
    amount: 1.3,
    currency: 'SAR',
    cartId: 'cart_66666',
    cartDescription: 'Refund reason'
);

dd($response);

Voiding a Payment

The voidPayment method allows you to void a previously authorized or captured transaction. This is typically used when an order is canceled before it is fulfilled.

Example:

use GranadaPride\Clickpay\ClickpayClient;
use GranadaPride\Clickpay\Contracts\PaymentGatewayInterface;

$clickpay = app(PaymentGatewayInterface::class);

$response = $clickpay->voidPayment(
    transactionReference: 'TST2016700000692',
    amount: 1.3,
    currency: 'SAR',
    cartId: 'cart_66666',
    cartDescription: 'Void reason'
);

dd($response);

Troubleshooting

Common Issues

• Invalid Credentials: Ensure that your profile_id and server_key in the configuration file are correct.
• Unsupported Region: Double-check that the base_url in your configuration file is valid and supported by Clickpay.
• Transaction Failure: Verify the transaction data (e.g., cart amount, customer details) to ensure it meets Clickpay's requirements.

If you encounter other issues, refer to the Clickpay API Documentation for more details.

Testing

Soon...

Contribution

Contributions are welcome! If you’d like to contribute to this package, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Write your code and ensure it is well-documented.
4. Submit a pull request with a clear description of your changes.

License

This package is open-source software licensed under the MIT License. Please see the License File for more information.