devinweb/laravel-paytabs

Laravel支付网关Paytabs的包

维护者

详细信息

github.com/devinweb/laravel-paytabs

主页

源代码

问题

安装: 158

依赖: 0

建议者: 0

安全: 0

星星: 10

关注者: 1

分支: 0

开放问题: 0

v1.0.3 2022-10-21 11:39 UTC

Requires

Requires (Dev)

MIT 00c116b9b2aa39f151638129219bc19137992e92

  • Imane Acherrat <imane.woop@devinweb.com>

devinweblaravel-paytabs

This package is auto-updated.

Last update: 2024-09-21 15:43:13 UTC

README

Laravel Paytabs

Laravel Paytabs

Latest Version on Packagist Total Downloads StyleCI Shield codecov GitHub Actions

Laravel Paytabs简化了Laravel开发者与PayTabs支付网关的集成，它通过提供一系列功能来调用paytabs交易API。

要求

此包需要php 7.4或更高版本。

安装

您可以通过composer安装此包

composer require devinweb/laravel-paytabs

数据库迁移

此包提供了一个迁移来处理交易。您需要在安装后发布迁移文件。

php artisan vendor:publish --tag="paytabs-migrations"

然后，您需要迁移交易表。

php artisan migrate

设置和配置

您还可以使用以下命令发布配置文件

php artisan vendor:publish --tag="paytabs-config"

之后，您可以在app/paytabs.php中看到该文件并进行更新。您可能需要更改model变量以使用您自定义的用户模型。

Paytabs密钥

在能够使用此包之前，您应该在应用程序的.env文件中配置Paytabs环境。

PAYTABS_SERVER_KEY=your-server-key
PAYTABS_PROFILE_ID=your-profile-id
# default SAR
CURRENCY=
# default SAU
PAYTABS_REGION=
# default https://secure.paytabs.sa/
PAYTABS_API=
PAYTABS_REDIRECT_URL=your-redirect-url

用法

交易类型枚举

Paytabs支持的交易类型由这个抽象类描述。有五种不同类型的交易：sale、auth、refund、void和capture。这个类使得查找和使用这些值变得简单。

use Devinweb\LaravelPaytabs\Enums\TransactionType;

$saleType = TransactionType::SALE;

它也可以用来验证给定的类型是后续类型还是初始化类型。

use Devinweb\LaravelPaytabs\Enums\TransactionType;

$type = TransactionType::SALE;
$isFollowUp = TransactionType::isFollowUpType($type); // will return false
$isInitiate = TransactionType::isInitiateType($type); // will return true

交易类枚举

TansactionClass描述了交易类可能采取的值，就像TransactionType一样。值可能是recurring、ecom或moto。此包目前仅支持ecom类型。

use Devinweb\LaravelPaytabs\Enums\TransactionClass;

$type = TransactionClass::ECOM;

您可以使用此静态函数来获取支持值。

use Devinweb\LaravelPaytabs\Enums\TransactionClass;

$types = TransactionClass::values;

初始化支付（生成托管支付页面）

要使用此包创建paytabs交易，您需要首先初始化支付以生成表单链接。然后您可以访问生成的页面或在您的应用中嵌入它以完成支付。这个过程和可用选项将在以下部分中描述。

设置客户详情

要初始化支付，您需要使用setCustomer方法指定用户模型。$user应该是Illuminate\Database\Eloquent\Model的实例，并使用以下字段：姓名、电子邮件和电话。电话是可选的。将返回一个类型为LaravelPaytabsFacade的值。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;
$paytabs = LaravelPaytabsFacade::setCustomer($user);

设置购物车详情

您还需要使用setCart函数设置购物车详情。一个包含键id、amount和description的三个键数组应形成$cart。将返回一个类型为LaravelPaytabsFacade的值。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;

$cart = [
    'id' => "123",
    'amount' => 10,
    'description' => 'cart description'
];

$paytabs = LaravelPaytabsFacade::setCart($cart);

设置重定向URL

重定向URL必须包含在您的请求中。支付处理完毕后，用户将被发送回此URL。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;
$paytabs = LaravelPaytabsFacade::setRedirectUrl($url);

⚠️如果您在项目中的所有支付都使用一个重定向URL，您可以将其添加到.env中，如上文中所述。

框架托管支付页面

要在一个嵌入的框架中显示商户网站的托管支付页面，您可以调用framedPage。将返回一个类型为LaravelPaytabsFacade的值。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;

$paytabs = LaravelPaytabsFacade::framedPage($user);

账单

如果您想在支付页面上预先填充账单部分，您可以通过创建账单类来设置账单详情。您可以在app/Billing文件夹中找到所有账单文件。

php artisan make:billing PaytabsBilling

然后使用

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;
use App\Billing\PaytabsBilling;

LaravelPaytabsFacade::addBilling(new PaytabsBilling);

创建的类的getData方法应返回一个包含以下键的数组：street1、city、state、country、zip和ip。如果您添加了所有这些值，可以使用hideBilling函数隐藏托管支付页面上的账单部分。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;
use App\Billing\PaytabsBilling;

LaravelPaytabsFacade::addBilling(new PaytabsBilling)->hideBilling();

配送

与账单相同，您可以在支付页面上显示预先填充的配送部分。创建配送类，然后添加配送详情。

php artisan make:billing PaytabsShipping
use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;
use App\Billing\PaytabsShipping;

LaravelPaytabsFacade::addShipping(new PaytabsShipping);

您可能会偶尔在您向客户提供的服务中包含数字产品，在这种情况下，您不需要他们的配送信息。您可以使用hideShipping选项隐藏从生成的托管支付页面中显示的配送详情部分。将返回类型为LaravelPaytabsFacade的值。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;

$paytabs = LaravelPaytabsFacade::hideShipping();

⚠️️ 如果账单详情已经添加，此函数也将隐藏账单部分。

生成托管支付页面

在设置所有支付页面详情和参数后，您需要使用initiate函数调用Paytabs交易API并启动您的支付。交易类型可以是销售或授权。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;
use Devinweb\LaravelPaytabs\Enums\TransactionClass;
use Devinweb\LaravelPaytabs\Enums\TransactionType;

LaravelPaytabsFacade::setCustomer($user)
            ->setCart($cart_data)
            ->setRedirectUrl($url)
            ->hideShipping()
            ->initiate(TransactionType::SALE, TransactionClass::ECOM);

如果支付页面创建成功，您将收到如下所示的响应，包括支付页面URL（redirect_url）。将在交易表中添加带有status=pending的行，并触发TransactionInitiated事件。

{
  "tran_ref": "TST2110300142699",
  "tran_type": "Sale",
  "cart_id": "cart_11111",
  "cart_description": "Description of the items/services",
  "cart_currency": "EGP",
  "cart_amount": "100.00",
  "return": "https://devinweb.com/4b3af623-085f-4b82-ab22-cb6cedeba218",
  "redirect_url": "https://secure.paytabs.sa/payment/page/3F76B62E82E417E6AB2104212437A16EA53E657E75232A6C4C544962",
   "customer_details": {
    "name": "first last",
    "email": "email@domain.com",
    "phone": "0522222222",
    "street1": "address street",
    "city": "dubai",
    "state": "du",
    "country": "AE",
    "zip": "12345",
    "ip": "1.1.1.1"
  },

}

访问生成的URL并完成您的支付后，交易状态将变为paid或failed，您将被重定向到您的返回URL。将触发TransactionSucceed或TransactionFail事件。支付结果详情将发布到重定向URL，如下例所示

// Successful transaction response example
acquirerMessage= 
&acquirerRRN= 
&cartId=cart_11111 
&customerEmail=imane%devinweb.com 
&respCode=G96376 
&respMessage=Authorised 
&respStatus=A 
&token= 
&tranRef=TST2110400143785 
&signature=db333934b8bd8d5f94d90ab28c72831d563dc10bb196ebd78a300af7df8fad7
Generic

您可以访问paytabs的官方文档以了解有关其他paytabs响应代码/状态的更多信息。

跟踪交易

在启动或完成您的支付后，您可能需要对它进行一些操作。

通过参考获取交易

您可以使用此函数检索交易的详细信息，例如其状态、类型等。`transactionRef`表示作为`tran_ref`返回的交易参考，并在交易表中作为`transaction_ref`存储。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;
$transactionRef = "TST2105900091468";
$transaction = LaravelPaytabsFacade::setTransactionRef($transactionRef)
            ->getTransaction();
  • 响应
{
  "tran_ref": "TST2105900091468",
  "tran_type": "Sale",
  "cart_id": "Sample Payment",
  "cart_description": "Sample Payment",
  "cart_currency": "EGP",
  "cart_amount": "1",
  "customer_details": {
    "name": "Imane Acherrat",
    "email": "imane@devinweb.com",
    "phone": "01005417901",
    "street1": "Alexandria",
    "city": "Alexandria",
    "state": "ALX",
    "country": "EG",
    "ip": "40.123.210.168"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G15046",
    "response_message": "Authorised",
    "transaction_time": "2021-02-28T12:24:06Z"
  },
  "payment_info": {
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111"
  }
}

⚠️ 您可以访问paytabs的官方文档以了解有关payment_result部分的更多信息。

退款、抓取或取消交易

退款请求适用于已授权销售交易或已授权抓取交易。

抓取请求适用于成功授权授权交易。

取消请求适用于未完全抓取的授权授权交易。

要使用LaravelPaytabs对交易执行退款、取消或抓取操作，您需要设置用户模型（setCustomer）、交易参考（setTransactionRef）和购物车详情（setCart），如下所示，并将动作类型和类传递给followUpTransaction。

use Devinweb\LaravelPaytabs\Facades\LaravelPaytabsFacade;
use Devinweb\LaravelPaytabs\Enums\TransactionClass;
use Devinweb\LaravelPaytabs\Enums\TransactionType;

LaravelPaytabsFacade::setCart($cart_data)
        ->setTransactionRef($payment->tran_ref)
        ->setCustomer(Auth::user())
        ->followUpTransaction(TransactionType::REFUND, TransactionClass::ECOM);

将触发TransactionSucceed或TransactionFail事件。

事件处理程序

此包在交易过程中触发三个事件：TransactionInitiated、TransactionSucceed和TransactionFail。

事件的内容是交易API返回的响应。

监听器示例

使用此laravel命令创建一个新监听器

php artisan make:listener TransactionInitiatedListener

然后在app/Providers/EventServiceProvider中将事件与您的监听器相关联。

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
         'Devinweb\LaravelPaytabs\Events\TransactionInitiated' => [
            'App\Listeners\TransactionInitiatedListener',
        ],
    ];

}

测试

composer test

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

请参阅贡献指南以获取详细信息。

安全

如果您发现任何与安全相关的问题，请发送电子邮件至imane@devinweb.com，而不是使用问题跟踪器。

鸣谢

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

Laravel Paytabs模板

您可以使用此存储库来检查laravel-paytabs-boilerplate包的集成。