README

此包允许您轻松地在 Laravel 项目中添加支付网关，使用 Moamalat ligthbox。

注意这不是 Moamalat 的官方库，它只是一个开源库。

安装

您可以通过 composer 安装此包

composer require alifaraun/laravel-moamalat-pay

Laravel 版本兼容性

如果您想自定义配置

php artisan vendor:publish --provider="moamalat-pay"

配置文件

配置文件 moamalat-pay.php 位于 config 文件夹中。以下是其发布后的内容

return [
	/*
	|--------------------------------------------------------------------------
	| Moamalat Payment Gateway Config
	|--------------------------------------------------------------------------
	|
	| These options to set your configurations of muamalat
	|
	*/

	// MID => merchant_id or outlet_number
	'merchant_id' => env('MOAMALATPAY_MID'),

	// TID => terminal_id
	'terminal_id' => env('MOAMALATPAY_TID'),

	// Secure key
	'key' => env('MOAMALATPAY_KEY'),


	/*
	|--------------------------------------------------------------------------
	| Production
	|--------------------------------------------------------------------------
	|
	| If the production is set to "true", you will work on production environment
	| otherwise it will use testing environment
	|
	*/
	'production' => env('MOAMALATPAY_PRODUCTION', false),

	/*
	|--------------------------------------------------------------------------
	| Show
	|--------------------------------------------------------------------------
	|
	| If the show_logs is set to "true", you will see configurations
	| and response of requests in browser console
	|
	*/
	'show_logs' => false,

    /*
    |--------------------------------------------------------------------------
    | Enable Cancel Event On Success
    |--------------------------------------------------------------------------
    |
    | If the enable_cancel_event_on_success is set to "true", the cancel event will be triggered even if the payment is successful
    |
    */
    'enable_cancel_event_on_success' => true,

	/*
	|--------------------------------------------------------------------------
	| Generate Secure Hash api
	|--------------------------------------------------------------------------
	|
	| This is service (api) to generate secureHash to be used in pay in Lightbox.
	|
	| url is route of api of generate secureHash
	|
	| route_name is name of route of api of generate secureHash
	|
	*/
	'generate-securekey' => [
	'url' =>  'moamalat-pay/securekey',
	'route_name' =>  'moamalat_pay.generate_securekey',
	],


	/*
	|--------------------------------------------------------------------------
	| Notification (Webhook) api
	|--------------------------------------------------------------------------
	|
	| This is service from moamalat on any transaction you will receive notification
	| on api (webhook)
	|
	| key is your private notification key to use it in validate transaction requests
	|
	| url is route to receive notification
	|
	| table is name of table that will be used to save notifications
	|
	| allowed_ips are ips that will receive notification from them
	| ['*'] means receive from any ip but it is not secure to receive notifcations from anyone
	| you should ask moamalat on ips of their servers and use them
	|
	*/
	'notification' => [
	'key' => env('MOAMALATPAY_NOTIFICATION_KEY'),
	'url' =>  'moamalat-pay/notify',
	'route_name' =>  'moamalat_pay.notification',
	'table' => 'moamalat_pay_notifications',
	'allowed_ips' => ['*'],
    	]
];

在 .env 文件中设置您的配置

MOAMALATPAY_MID=
MOAMALATPAY_TID=
MOAMALATPAY_KEY=
MOAMALATPAY_NOTIFICATION_KEY=
MOAMALATPAY_PRODUCTION=

测试目的的配置

商家

Merchant id	: 10081014649
Terminal Id	: 99179395
Secure key	: 39636630633731362D663963322D346362642D386531662D633963303432353936373431

卡

Card : 6394993077260781
EXP  : 12/24
OTP  : 111111

用法

Laravel 组件

// Initialize pay
<x-moamalat-pay />

// when pass amount property, it will show pay form directly
<x-moamalat-pay amount="1000" />

Laravel 方法

使用方法调用它

// Initialize pay
app('moamalat-pay')->init();

// call pay
// $amount int libyan dirham not dinar
//$reference is optional
app('moamalat-pay')->pay(int $amount,string $reference = '');

前端 JavaScript

使用 JavaScript 调用支付

_moamalatPay.pay(int amount,string reference = '')

检查处理状态

可用的用于检查操作是否成功或失败的可用事件

addEventListener("moamalatCompleted", function (e) {
  e.detail; // response data
  /* e.detail
	{
	    "TxnDate": "220822141359",
	    "SystemReference": "1233114",
	    "NetworkReference": "223414600869",
	    "MerchantReference": "1641729671",
	    "Amount": "10",
	    "Currency": "434",
	    "PaidThrough": "Card",
	    "PayerAccount": "639499XXXXXX0781",
	    "PayerName": "SS",
	    "ProviderSchemeName": "",
	    "SecureHash": "EB085D519BCC0887EA1031939F15DE230991E8C1E8731CD11A6916A5B7FC29D8",
	    "DisplayData": "",
	    "TokenCustomerId": "",
	    "TokenCard": ""
	}
    */
});

addEventListener("moamalatError", function (e) {
  e.detail; // response data
  /* e.detail
	{
	    "error": "CUBEEX5212216:Authentication Failed",
	    "Amount": "200.031",
	    "MerchantReferenece": "",
	    "DateTimeLocalTrxn": "220818232732",
	    "SecureHash": "1C8B1301AD4C00BE66EC25FD45A81D0C4030C79EF53CA903FA5009ECCAD08D46"
	}
    */
});

addEventListener("moamalatCancel", function () {});

在后台获取交易

use MoamalatPay\Transaction;

// get transaction from NPG(moamalat)
$transaction = new Transaction($networkReference, $merchantReference);
// Throws an exception if there is a problem in loading the transaction

/** available methods to interact with transaction **/

/**
 * Get all properties of transaction
 * @return Array
 */
$transaction->getAll();

/**
 * Get property of transaction
 * @param $property key
 * @return mixed
 */
$transaction->get($property);


/**
 * Get property of reponse , if property not exists return default value
 *
 * @param $property
 * @param $default
 * @return mixed
 */
$transaction->getWithDefault($property, $default = null);

/**
 * Get all properties of reponse
 * @return Array
 */
$transaction->getResponse();

/**
 * Check status of transaction is Approved
 *
 * @param $amount
 * @param $card
 * @return boolean
 */
$transaction->checkApproved($amount = null, $card = null);

示例

use MoamalatPay\Transaction;

// get transaction from NPG(moamalat)
$transaction = new Transaction("223414600869","1641729671");


$transaction->getAll();
/* return
        [
          "Amnt" => "10",
          "AmountTrxn" => "10",
          "AuthCode" => null,
          "CardNo" => "639499XXXXXX0781",
          "CardType" => "",
          "Currency" => "LYD",
          "ExternalTxnId" => null,
          "FeeAmnt" => "0",
          "HasToken" => true,
          "ISForceSendCVCForRefund" => true,
          "IsMustVoidTotalAmount" => true,
          "IsPointTrasnaction" => false,
          "IsRefund" => false,
          "IsRefundEnabled" => true,
          "IsSend" => false,
          "MerchantReference" => "1641729671",
          "MobileNumber" => null,
          "OriginalTxnId" => "",
          "RRN" => "223414600869",
          "ReceiptNo" => "223414600869",
          "RefundButton" => 1,
          "RefundReason" => "",
          "RefundSource" => "",
          "RefundUserCreator" => "",
          "RelatedTxnTotalAmount" => null,
          "RemainingRefundAmount" => "10",
          "ResCodeDesc" => "Approved",
          "STAN" => "600869",
          "SenderName" => "SS",
          "Status" => "Approved",
          "TipAmnt" => "0",
          "TransType" => "Sale",
          "TransactionChannel" => "Card",
          "TransactionId" => "1233114",
          "TxnDateTime" => "22/08/22  14:13",
          "TxnIcon" => 2
        ]
*/

$transaction->get('CardNo');
// return 639499XXXXXX0781

$transaction->getWithDefault('Card','card-not-found');
// return card-not-found

$transaction->checkApproved();
// if transaction status is Approved it will return true

$transaction->checkApproved(10000,'639499XXXXXX0781');
// if transaction is status is Approved , amount=10000 and CardNo=639499XXXXXX0781 it will return true

通知服务（Webhook）

通知服务允许商家在他们的账户生成交易时接收通知

我们将所有通知保存在数据库中，并基于交易类型和状态触发事件

/*
MoamalatPay\Models\MoamalatPayNotification \\ Eloquent Model
\\ properites
id
MerchantId
TerminalId
DateTimeLocalTrxn
TxnType
Message
PaidThrough
SystemReference
NetworkReference
MerchantReference
Amount
Currency
PayerAccount
PayerName
ActionCode
request
ip
verified
created_at
*/

可用作用域

// filter to get approved transactions (ActionCode = 00)
MoamalatPay\Models\MoamalatPayNotification::approved()

// filter to get verified transactions (verified = 1)
MoamalatPay\Models\MoamalatPayNotification::verified()

// filter to get transactions for currency terminal_id and merchant_id in config
MoamalatPay\Models\MoamalatPayNotification::currentCredential()

事件

添加监听器的示例，请参阅 laravel 文档了解更多信息

// event will be fired when receive request from ip not exists in allowed_ips in config of moamalat-pay
Event::listen(function (MoamalatPay\Events\DisallowedRequestEvent $event) {
});

// event will be fired after check secureHas is unverified
Event::listen(function (MoamalatPay\Events\UnverfiedTransaction $event) {
   $event->notification // Eloquent Model of transaction
});

// event will be fired after check secureHas is verified
Event::listen(function (MoamalatPay\Events\VerfiedTransaction $event) {
   $event->notification // Eloquent Model of transaction
});

// event will be fired after check secureHas is verified and transaction status is approved
Event::listen(function (MoamalatPay\Events\ApprovedTransaction $event) {
   $event->notification // Eloquent Model of transaction
});

// event will be fired after check secureHas is verified and transaction status is approved
// and type of transaction is : 1: Sale
Event::listen(function (MoamalatPay\Events\ApprovedSaleTransaction $event) {
   $event->notification // Eloquent Model of transaction
});

// event will be fired after check secureHas is verified and transaction status is approved
// and type of transaction is : 2: Refund
Event::listen(function (MoamalatPay\Events\ApprovedRefundTransaction $event) {
   $event->notification // Eloquent Model of transaction
});

// event will be fired after check secureHas is verified and transaction status is approved
// and type of transaction is : 3: Void Sale
Event::listen(function (MoamalatPay\Events\ApprovedVoidSaleTransaction $event) {
   $event->notification // Eloquent Model of transaction
});

// event will be fired after check secureHas is verified and transaction status is approved
// and type of transaction is : 4: Void Refund
Event::listen(function (MoamalatPay\Events\ApprovedVoidRefundTransaction $event) {
   $event->notification // Eloquent Model of transaction
});

退款和取消交易

如果在结算之前调用退款（通常在每天结束时结算），则将取消交易，否则将退款

/**
 * Refund transaction by system reference of transaction
 * @param string|integer $systemReference
 * @param string|integer $amount
 * @return array content response of moamalat
 */
app('moamalat-pay-refund')->refundBySystemReference($systemReference, $amount)->getAll()
// Throws an exception if there is a problem in refund the transaction


/**
 * Refund transaction by network reference of transaction
 * @param string|integer $networkReference
 * @param string|integer $amount
 * @return array content response of moamalat
 */
app('moamalat-pay-refund')->refundByNetworkReference($networkReference, $amount)->getAll()
// Throws an exception if there is a problem in refund the transaction

/* response : return of getAll() method
{
    "Message": "Approved",
    "Success": true,
    "ActionCode": null,
    "AuthCode": null,
    "DecimalFraction": 3,
    "ExternalTxnId": null,
    "IsEnableRefund": false,
    "MerchantReference": null,
    "NetworkReference": null,
    "ReceiptNumber": null,
    "ReceiverAccountNumber": null,
    "ReceiverName": null,
    "ReceiverScheme": null,
    "RefNumber": "1233678", // System reference for the new refund transaction
    "SystemReference": 0,
    "SystemTxnId": 0,
    "TxnDate": null
}
*/

示例

$r = app('moamalat-pay-refund')->refundBySystemReference("1233114", "10");
// or
$r = app('moamalat-pay-refund')->refundByNetworkReference("223414600869", "10");

// will return instance of MoamalatPay\Refund class

/**
 * Get all properties of reponse
 * @return array
 */
$r->getAll();
/* response
{
    "Message": "Approved",
    "Success": true,
    "ActionCode": null,
    "AuthCode": null,
    "DecimalFraction": 3,
    "ExternalTxnId": null,
    "IsEnableRefund": false,
    "MerchantReference": null,
    "NetworkReference": null,
    "ReceiptNumber": null,
    "ReceiverAccountNumber": null,
    "ReceiverName": null,
    "ReceiverScheme": null,
    "RefNumber": "1233678", // System reference for the new refund transaction
    "SystemReference": 0,
    "SystemTxnId": 0,
    "TxnDate": null
}
*/

/**
 * Get property of transaction
 * @param $property key
 * @return mixed
 */
$r->get($property);
$r->get('Message');
// return Approved


/**
 * Get property of reponse , if property not exists return default value
 *
 * @param $property
 * @param $default
 * @return mixed
 */
$r->getWithDefault($property, $default = null);
$r->getWithDefault('Card', 'No Card');
// return No Card


/**
 * Get SystemReference of new refund transaction
 * @return string|integer
 */
$r->getRefNumber();
// return 1233678

测试

使用以下命令运行测试

composer test
// or
./vendor/bin/phpunit

运行静态分析工具（PHPStan）

composer analyse
// or
./vendor/bin/phpstan analyse

安全

如果您发现任何与安全相关的问题，请通过电子邮件 ali1996426@hotmail.com 联系，而不是使用问题跟踪器。

信用

许可证

MIT 许可证（MIT）

alifaraun / laravel-moamalat-pay

维护者

详细信息