README

描述

《laravel-clickpaysa》包提供了一种简单的方法，将 Clickpaysa 支付网关集成到您的 Laravel 应用程序中。此包遵循 SOLID 原则并使用现代 PHP 实践，确保您的代码易于维护、测试和扩展。

安装

您可以通过 composer 安装此包

composer require granada-pride/clickpaysa

配置

安装完成后，使用以下命令发布配置文件

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

这将创建一个 config/clickpay.php 文件。以下是一个配置文件的示例

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'),

];

环境变量

请确保在您的 .env 文件中设置了所需的变量

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

使用

创建支付页面

以下是使用此包创建支付页面的方法

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: '+123456789',
    email: 'ahmad_mohamed@example.com',
    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);

查询交易

您也可以使用交易引用来查询交易

use GranadaPride\Clickpay\Contracts\PaymentGatewayInterface;

$clickpay = app(PaymentGatewayInterface::class);

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

dd($response);

捕获支付

capturePayment 方法允许您捕获之前已授权的交易。这通常用于在订单创建时授权支付，但您仅在货物发货时才希望捕获资金。

示例

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);

退款支付

refundPayment 方法用于退款之前完成交易。当客户请求退订单时，这可能很有用。

示例

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);

取消支付

voidPayment 方法允许您取消之前已授权或捕获的交易。这通常用于在订单履行之前取消订单。

示例

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);

故障排除

常见问题

无效凭证：请确保配置文件中的 profile_id 和 server_key 是正确的。
不支持的地区：请再次检查配置文件中的 base_url 是否有效并由 Clickpay 支持。
交易失败：请验证交易数据（例如，购物车金额、客户详细信息）以确保它符合 Clickpay 的要求。

如果您遇到其他问题，请参阅 Clickpay API 文档获取更多详细信息。

测试

即将推出...

贡献

欢迎贡献！如果您想为此包做出贡献，请按照以下步骤操作

分支仓库。
为您的功能或错误修复创建一个新的分支。
编写您的代码，并确保它有良好的文档。
提交一个带有对您的更改的清晰描述的 pull 请求。

许可

此包是开源软件，许可协议为 MIT 许可。请参阅 License 文件获取更多信息。

granada-pride / clickpaysa

维护者

详细信息