SEP driver (#168)

* update en/fa README files for SEP driver and custom fields * add SEP (saman electronic payment) driver for Saderat & Keshavarzi
shetabit · Nov 23, 2022 · 6a71379 · 6a71379
1 parent efe50c0
commit 6a71379
Show file tree

Hide file tree

Showing 4 changed files with 348 additions and 48 deletions.
diff --git a/README-FA.md b/README-FA.md
@@ -69,6 +69,7 @@
 - [پولام](https://poolam.ir/) :heavy_check_mark:
 - [سداد (بانک ملی)](https://sadadpsp.ir/) :heavy_check_mark:
 - [سامان](https://www.sep.ir) :heavy_check_mark:
+- [پرداخت الکترونیک سامان (کشاورزی و صادرات)](https://www.sep.ir) :heavy_check_mark:
 - [سپهر (بانک صادرات)](https://www.sepehrpay.com/) :heavy_check_mark:
 - [والتا (پرداخت اقساطی)](https://walleta.ir/) :heavy_check_mark:
 - [یک پی](https://yekpay.com/) :heavy_check_mark:
@@ -555,6 +556,35 @@ class MyDriver extends Driver
 
 <div dir="rtl">
 
+- ###### `فیلدهای اضافی (دلخواه)`: در نظر داشته باشید که تمامی درگاه‌ها از این امکان پشتیبانی نمیکنند.
+درگاه **پرداخت الکترونیک سامان** تا ۴ فیلد اضافه را پشتبانی میکند و هرکدام از فیلدها تا ۵۰ کاراکتر اطلاعات را میتوانند در خود نگهداری کنند.
+
+اطلاعات این فیلدها در هنگام گزارش گیری در پنل پذیرنده نمایش داده میشوند. 
+
+شما میتوانید اطلاعاتی را که منجر به تسریع عملیات گزارش گیری و مغایرت گیری کمک میکند را در این فیلدها ذخیره و هنگام پرداخت به بانک ارسال نمایید.
+
+</div>
+
+  ```php
+// At the top of the file.
+use Shetabit\Multipay\Invoice;
+...
+
+
+// Create new invoice.
+$invoice = (new Invoice)->amount(1000);
+
+// Use invoice bag to store custom field values.
+$invoice->detail([
+            'ResNum1' => $order->orderId,
+            'ResNum2' => $customer->verifiedCode,
+            'ResNum3' => $someValue,
+            'ResNum4' => $someOtherValue,
+            ]);
+```
+
+<div dir="rtl">
+
 #### رویدادها:
 
 **نکته اول:** تمامی listener ها به صورت global تنظیم خواهند شد و برای تمامی پرداخت ها اعمال میشوند.

diff --git a/README.md b/README.md
@@ -1,11 +1,7 @@
 <p align="center"><img src="resources/images/payment.png?raw=true"></p>
 
-
-
 # PHP Payment Gateway
 
-
-
 [![Software License][ico-license]](LICENSE.md)
 [![Latest Version on Packagist][ico-version]][link-packagist]
 [![Total Downloads on Packagist][ico-download]][link-packagist]
@@ -33,13 +29,13 @@ For **Laravel** integration you can use [shetabit/payment](https://github.com/sh
   - [Install](#install)
   - [Configure](#configure)
   - [How to use](#how-to-use)
-      - [Working with invoices](#working-with-invoices)
-      - [Purchase invoice](#purchase-invoice)
-      - [Pay invoice](#pay-invoice)
-      - [Verify payment](#verify-payment)
-      - [Useful methods](#useful-methods)
-      - [Create custom drivers:](#create-custom-drivers)
-      - [Events](#events)
+    - [Working with invoices](#working-with-invoices)
+    - [Purchase invoice](#purchase-invoice)
+    - [Pay invoice](#pay-invoice)
+    - [Verify payment](#verify-payment)
+    - [Useful methods](#useful-methods)
+    - [Create custom drivers:](#create-custom-drivers)
+    - [Events](#events)
   - [Local driver (for development)](#local-driver)
   - [Change log](#change-log)
   - [Contributing](#contributing)
@@ -48,6 +44,7 @@ For **Laravel** integration you can use [shetabit/payment](https://github.com/sh
   - [License](#license)
 
 # List of available drivers
+
 - [asanpardakht](https://asanpardakht.ir/) :heavy_check_mark:
 - [aqayepardakht](https://aqayepardakht.ir/) :heavy_check_mark:
 - [atipay](https://www.atipay.net/) :heavy_check_mark:
@@ -67,6 +64,7 @@ For **Laravel** integration you can use [shetabit/payment](https://github.com/sh
 - [poolam](https://poolam.ir/) :heavy_check_mark:
 - [sadad (melli)](https://sadadpsp.ir/) :heavy_check_mark:
 - [saman](https://www.sep.ir) :heavy_check_mark:
+- [sep (saman electronic payment) Keshavarzi & Saderat](https://www.sep.ir) ✔️
 - [sepehr (saderat)](https://www.sepehrpay.com/) :heavy_check_mark:
 - [walleta (Installment payment)](https://walleta.ir/) :heavy_check_mark:
 - [yekpay](https://yekpay.com/) :heavy_check_mark:
@@ -98,7 +96,7 @@ For **Laravel** integration you can use [shetabit/payment](https://github.com/sh
 
 Via Composer
 
-``` bash
+```bash
 $ composer require shetabit/multipay
 ```
 
@@ -145,13 +143,12 @@ c. Instantiate the `Payment` class and **pass configs to it** like the below:
 
 ## How to use
 
-your `Invoice` holds your payment details, so initially we'll talk about `Invoice` class. 
+your `Invoice` holds your payment details, so initially we'll talk about `Invoice` class.
 
 #### Working with invoices
 
 before doing any thing you need to use `Invoice` class to create an invoice.
 
-
 In your code, use it like the below:
 
 ```php
@@ -182,7 +179,7 @@ Available methods:
 - `uuid`: set the invoice unique id
 - `getUuid`: retrieve the invoice current unique id
 - `detail`: attach some custom details into invoice
-- `getDetails`: retrieve all custom details 
+- `getDetails`: retrieve all custom details
 - `amount`: set the invoice amount
 - `getAmount`: retrieve invoice amount
 - `transactionId`: set invoice payment transaction id
@@ -191,6 +188,7 @@ Available methods:
 - `getDriver`: retrieve the driver
 
 #### Purchase invoice
+
 In order to pay the invoice, we need the payment transactionId.
 We purchase the invoice to retrieve transaction id:
 
@@ -312,21 +310,22 @@ try {
 
 - ###### `callbackUrl`: can be used to change callbackUrl on the runtime.
 
+
   ```php
   // At the top of the file.
   use Shetabit\Multipay\Invoice;
   use Shetabit\Multipay\Payment;
   ...
-  
+
   // load the config file from your project
   $paymentConfig = require('path/to/payment.php');
-  
+
   $payment = new Payment($paymentConfig);
-  
-  
+
+
   // Create new invoice.
   $invoice = (new Invoice)->amount(1000);
-    
+
   // Purchase the given invoice.
   $payment->callbackUrl($url)->purchase(
       $invoice, 
@@ -335,21 +334,21 @@ try {
   	}
   );
   ```
-
 - ###### `amount`: you can set the invoice amount directly
 
+
   ```php
   // At the top of the file.
   use Shetabit\Multipay\Invoice;
   use Shetabit\Multipay\Payment;
   ...
-  
+
   // load the config file from your project
   $paymentConfig = require('path/to/payment.php');
-  
+
   $payment = new Payment($paymentConfig);
-  
-  
+
+
   // Purchase (we set invoice to null).
   $payment->callbackUrl($url)->amount(1000)->purchase(
       null,
@@ -358,24 +357,24 @@ try {
   	}
   );
   ```
-
 - ###### `via`: change driver on the fly
 
+
   ```php
   // At the top of the file.
   use Shetabit\Multipay\Invoice;
   use Shetabit\Multipay\Payment;
   ...
-  
+
   // load the config file from your project
   $paymentConfig = require('path/to/payment.php');
-  
+
   $payment = new Payment($paymentConfig);
-  
-  
+
+
   // Create new invoice.
   $invoice = (new Invoice)->amount(1000);
-  
+
   // Purchase the given invoice.
   $payment->via('driverName')->purchase(
       $invoice, 
@@ -384,9 +383,9 @@ try {
   	}
   );
   ```
-
 - ###### `config`: set driver configs on the fly
 
+
   ```php
   // At the top of the file.
   use Shetabit\Multipay\Invoice;
@@ -418,6 +417,27 @@ try {
   	}
   );
   ```
+- `custom fileds`: Use custom fields of gateway (Not all gateways support this feature)
+  SEP gateway support up to 4 custom fields and you can set the value to a string up to 50 characters.
+  These custom fields are shown only when viewing reports in the user's panel.
+
+  ```php
+  // At the top of the file.
+  use Shetabit\Multipay\Invoice;
+  ...
+
+
+  // Create new invoice.
+  $invoice = (new Invoice)->amount(1000);
+
+  // Use invoice bag to store custom field values.
+  $invoice->detail([
+              'ResNum1' => $order->orderId,
+              'ResNum2' => $customer->verifiedCode,
+              'ResNum3' => $someValue,
+              'ResNum4' => $someOtherValue,
+              ]);
+  ```
 
 #### Create custom drivers:
 
@@ -481,20 +501,20 @@ class MyDriver extends Driver
 
         return $this->redirectWithForm($url, $inputs, $method);
     }
-    
+
     // Verify the payment (we must verify to ensure that user has paid the invoice).
     public function verify(): ReceiptInterface {
         $verifyPayment = $this->settings->verifyApiUrl;
-        
+
         $verifyUrl = $verifyPayment.$this->invoice->getTransactionId();
-        
+
         ...
-        
+
         /**
 			Then we send a request to $verifyUrl and if payment is not valid we throw an InvalidPaymentException with a suitable message.
         **/
         throw new InvalidPaymentException('a suitable message');
-        
+
         /**
         	We create a receipt for this payment if everything goes normally.
         **/
@@ -524,7 +544,7 @@ Once you create that class you have to specify it in the `payment.php` config fi
 
 ---
 
-You can listen for 3 events: 
+You can listen for 3 events:
 
 1. **purchase**
 2. **pay**
@@ -578,7 +598,8 @@ Payment::removeVerifyListener(); // remove all verify listeners :D
 ```
 
 ## Local driver
-`Local` driver can simulate payment flow of a real gateway for development purpose. 
+
+`Local` driver can simulate payment flow of a real gateway for development purpose.
 
 Payment can be initiated like any other driver
 
@@ -588,9 +609,10 @@ $payment->via('local')->purchase($invoice, function($driver, $transactionId) {
     // a fake transaction ID is generated and returned.
 })->pay()->render();
 ```
+
 <p align="center"><img src="resources/images/local-form.png?raw=true"></p>
 
-Calling `render()` method will render a `HTML` form with **Accept** and  **Cancel** buttons, which simulate corresponding action of real payment gateway. and redirects to the specified callback url. 
+Calling `render()` method will render a `HTML` form with **Accept** and  **Cancel** buttons, which simulate corresponding action of real payment gateway. and redirects to the specified callback url.
 `transactionId` parameter will allways be available in the returned query url.
 
 Payment can be verified after receiving the callback request.
@@ -600,6 +622,7 @@ $receipt = $payment->via('local')->verify();
 ```
 
 In case of succesful payment, `$receipt` will contains the following parameters
+
 ```php
 [
 'orderId' => // fake order number 
@@ -637,26 +660,24 @@ Appearance of payment form can be customized via config parameter of `local` dri
 
     // main title of the form
     'title' => 'Test gateway',
-    
+
     // a description to show under the title for more clarification
     'description' => 'This gateway is for using in development environments only.',
-    
+
     // custom label to show as order No.
     'orderLabel' => 'Order No.',
-    
+
     // custom label to show as payable amount
     'amountLabel' => 'Payable amount',
-    
+
     // custom label of successful payment button
     'payButton' => 'Successful Payment',
-    
+
     // custom label of cancel payment button
     'cancelButton' => 'Cancel Payment',
 ],
 ```
 
-
-
 ## Change log
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has been changed recently.
@@ -682,7 +703,6 @@ The MIT License (MIT). Please see [License File](LICENSE.md) for more informatio
 [ico-download]: https://img.shields.io/packagist/dt/shetabit/multipay.svg?color=%23F18&style=flat-square
 [ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
 [ico-code-quality]: https://img.shields.io/scrutinizer/g/shetabit/multipay.svg?label=Code%20Quality&style=flat-square
-
 [link-fa]: README-FA.md
 [link-en]: README.md
 [link-zh]: README-ZH.md

diff --git a/config/payment.php b/config/payment.php
@@ -210,6 +210,14 @@
             'callbackUrl' => '',
             'description' => 'payment using saman',
         ],
+        'sep' => [
+            'apiGetToken' => 'https://sep.shaparak.ir/onlinepg/onlinepg',
+            'apiPaymentUrl' => 'https://sep.shaparak.ir/OnlinePG/OnlinePG',
+            'apiVerificationUrl' => 'https://sep.shaparak.ir/verifyTxnRandomSessionkey/ipg/VerifyTransaction',
+            'terminalId' => '',
+            'callbackUrl' => '',
+            'description' => 'Saman Electronic Payment for Saderat & Keshavarzi',
+        ],
         'sepehr' => [
             'apiGetToken' => 'https://mabna.shaparak.ir:8081/V1/PeymentApi/GetToken',
             'apiPaymentUrl' => 'https://mabna.shaparak.ir:8080/pay',
@@ -364,6 +372,7 @@
         'poolam' => \Shetabit\Multipay\Drivers\Poolam\Poolam::class,
         'sadad' => \Shetabit\Multipay\Drivers\Sadad\Sadad::class,
         'saman' => \Shetabit\Multipay\Drivers\Saman\Saman::class,
+        'sep' => \Shetabit\Multipay\Drivers\SEP\SEP::class,
         'sepehr' => \Shetabit\Multipay\Drivers\Sepehr\Sepehr::class,
         'walleta' => \Shetabit\Multipay\Drivers\Walleta\Walleta::class,
         'yekpay' => \Shetabit\Multipay\Drivers\Yekpay\Yekpay::class,