add laravel 13 support
This commit is contained in:
525
README-ZH.md
Normal file
525
README-ZH.md
Normal file
@@ -0,0 +1,525 @@
|
||||
<p align="center"><img src="resources/images/payment.png?raw=true"></p>
|
||||
|
||||
|
||||
|
||||
# Laravel 支付网关
|
||||
|
||||
|
||||
|
||||
[![Software License][ico-license]](LICENSE.md)
|
||||
[![Latest Version on Packagist][ico-version]][link-packagist]
|
||||
[![Total Downloads on Packagist][ico-download]][link-packagist]
|
||||
[](https://github.styleci.io/repos/169948762)
|
||||
[](https://codeclimate.com/github/shetabit/payment/maintainability)
|
||||
[![Quality Score][ico-code-quality]][link-code-quality]
|
||||
|
||||
这是一个用于整合支付网关的Laravel包。这个包依赖 `Laravel 5.8+`.
|
||||
|
||||
[捐赠我](https://yekpay.me/mahdikhanzadi) 如果你喜欢这个包:sunglasses: :bowtie:
|
||||
|
||||
For PHP integration you can use [shetabit/multipay](https://github.com/shetabit/multipay) package.
|
||||
|
||||
> 此软件包可用于多个驱动程序，如果在[当前驱动程序列表](#list-of-available-drivers)中找不到驱动程序，则可以创建它们
|
||||
|
||||
- [داکیومنت فارسی][link-fa]
|
||||
- [English documents][link-en]
|
||||
- [中文文档][link-zh]
|
||||
|
||||
# 目录
|
||||
|
||||
- [Laravel 支付网关](#laravel-%e6%94%af%e4%bb%98%e7%bd%91%e5%85%b3)
|
||||
- [目录](#%e7%9b%ae%e5%bd%95)
|
||||
- [可用驱动列表](#%e5%8f%af%e7%94%a8%e9%a9%b1%e5%8a%a8%e5%88%97%e8%a1%a8)
|
||||
- [安装](#%e5%ae%89%e8%a3%85)
|
||||
- [配置](#%e9%85%8d%e7%bd%ae)
|
||||
- [如何使用](#%e5%a6%82%e4%bd%95%e4%bd%bf%e7%94%a8)
|
||||
- [使用费用清单进行工作](#%e4%bd%bf%e7%94%a8%e8%b4%b9%e7%94%a8%e6%b8%85%e5%8d%95%e8%bf%9b%e8%a1%8c%e5%b7%a5%e4%bd%9c)
|
||||
- [获取支付清单](#%e8%8e%b7%e5%8f%96%e6%94%af%e4%bb%98%e6%b8%85%e5%8d%95)
|
||||
- [支付](#%e6%94%af%e4%bb%98)
|
||||
- [验证付款](#%e9%aa%8c%e8%af%81%e4%bb%98%e6%ac%be)
|
||||
- [有用的方法](#%e6%9c%89%e7%94%a8%e7%9a%84%e6%96%b9%e6%b3%95)
|
||||
- [创建自定义驱动:](#%e5%88%9b%e5%bb%ba%e8%87%aa%e5%ae%9a%e4%b9%89%e9%a9%b1%e5%8a%a8)
|
||||
- [事件](#%e4%ba%8b%e4%bb%b6)
|
||||
- [Change log](#change-log)
|
||||
- [贡献](#%e8%b4%a1%e7%8c%ae)
|
||||
- [安全](#%e5%ae%89%e5%85%a8)
|
||||
- [信誉](#%e4%bf%a1%e8%aa%89)
|
||||
- [License](#license)
|
||||
|
||||
# 可用驱动列表
|
||||
|
||||
- [asanpardakht](https://asanpardakht.ir/) :heavy_check_mark:
|
||||
- [aqayepardakht](https://aqayepardakht.ir/) :heavy_check_mark:
|
||||
- [atipay](https://www.atipay.net/) :heavy_check_mark:
|
||||
- [azkiVam (Installment payment)](https://www.azkivam.com/) :heavy_check_mark:
|
||||
- [behpardakht (mellat)](http://www.behpardakht.com/) :heavy_check_mark:
|
||||
- [bitpay](https://bitpay.ir/) :heavy_check_mark:
|
||||
- [digipay](https://www.mydigipay.com/) :heavy_check_mark:
|
||||
- [etebarino (Installment payment)](https://etebarino.com/) :heavy_check_mark:
|
||||
- [fanavacard](https://www.fanava.com/) :heavy_check_mark:
|
||||
- [idpay](https://idpay.ir/) :heavy_check_mark:
|
||||
- [irankish](http://irankish.com/) :heavy_check_mark:
|
||||
- [local](#local-driver) :heavy_check_mark:
|
||||
- [jibit](https://jibit.ir/) :heavy_check_mark:
|
||||
- [nextpay](https://nextpay.ir/) :heavy_check_mark:
|
||||
- [omidpay](https://omidpayment.ir/) :heavy_check_mark:
|
||||
- [parsian](https://www.pec.ir/) :heavy_check_mark:
|
||||
- [pasargad](https://bpi.ir/) :heavy_check_mark:
|
||||
- [payir](https://pay.ir/) :heavy_check_mark:
|
||||
- [payfa](https://payfa.com/) :heavy_check_mark:
|
||||
- [paypal](http://www.paypal.com/) (在下一个版本中很快就支持了)
|
||||
- [payping](https://www.payping.ir/) :heavy_check_mark:
|
||||
- [paystar](http://paystar.ir/) :heavy_check_mark:
|
||||
- [poolam](https://poolam.ir/) :heavy_check_mark:
|
||||
- [rayanpay](https://rayanpay.com/) :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) :heavy_check_mark:
|
||||
- [sepehr (saderat)](https://www.sepehrpay.com/) :heavy_check_mark:
|
||||
- [sepordeh](https://sepordeh.com/) :heavy_check_mark:
|
||||
- [sizpay](https://www.sizpay.ir/) :heavy_check_mark:
|
||||
- [toman](https://tomanpay.net/) :heavy_check_mark:
|
||||
- [vandar](https://vandar.io/) :heavy_check_mark:
|
||||
- [walleta (Installment payment)](https://walleta.ir/) :heavy_check_mark:
|
||||
- [yekpay](https://yekpay.com/) :heavy_check_mark:
|
||||
- [zarinpal](https://www.zarinpal.com/) :heavy_check_mark:
|
||||
- [zibal](https://www.zibal.ir/) :heavy_check_mark:
|
||||
- 其他正在进行中
|
||||
|
||||
**您可以通过`pull requests` 帮助我创建更多的网关**
|
||||
|
||||
- stripe
|
||||
- authorize
|
||||
- 2checkout
|
||||
- braintree
|
||||
- skrill
|
||||
- payU
|
||||
- amazon payments
|
||||
- wepay
|
||||
- payoneer
|
||||
- paysimple
|
||||
|
||||
> 如果找不到你需要的，您可以创建你自己的驱动，阅读`创建自定义驱动`部分，可以了解更多
|
||||
|
||||
## 安装
|
||||
|
||||
通过 Composer
|
||||
|
||||
``` bash
|
||||
composer require shetabit/payment
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
如果你使用`Laravel 5.5`或更高版本，你不需要手动设置 `provider` 和 `alias`,可以直接看b步骤
|
||||
|
||||
a. 在你的 `config/app.php` 文件中，添加如下两行
|
||||
|
||||
```php
|
||||
// In your providers array.
|
||||
'providers' => [
|
||||
...
|
||||
Shetabit\Payment\Provider\PaymentServiceProvider::class,
|
||||
],
|
||||
|
||||
// In your aliases array.
|
||||
'aliases' => [
|
||||
...
|
||||
'Payment' => Shetabit\Payment\Facade\Payment::class,
|
||||
],
|
||||
```
|
||||
|
||||
b. 然后运行 `php artisan vendor:publish` 来发布 `config/payment.php` 文件到你的项目中
|
||||
|
||||
在配置文件中，您可以将 `default`设置项设置为你希望的付款方式。但也可以在运行时更改驱动。
|
||||
|
||||
选择要在应用程序中使用的网关。然后将其设为默认驱动程序，这样就不必在任何地方都指定它。但是，您也可以在一个项目中使用多个网关。
|
||||
|
||||
|
||||
```php
|
||||
// Eg. if you want to use zarinpal.
|
||||
'default' => 'zarinpal',
|
||||
```
|
||||
|
||||
然后在驱动数组中填充该网关的凭据。
|
||||
|
||||
```php
|
||||
'drivers' => [
|
||||
'zarinpal' => [
|
||||
// Fill in the credentials here.
|
||||
'apiPurchaseUrl' => 'https://www.zarinpal.com/pg/rest/WebGate/PaymentRequest.json',
|
||||
'apiPaymentUrl' => 'https://www.zarinpal.com/pg/StartPay/',
|
||||
'apiVerificationUrl' => 'https://www.zarinpal.com/pg/rest/WebGate/PaymentVerification.json',
|
||||
'merchantId' => '',
|
||||
'callbackUrl' => 'http://yoursite.com/path/to',
|
||||
'description' => 'payment in '.config('app.name'),
|
||||
],
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
## 如何使用
|
||||
|
||||
您的 `Invoice` 包含您的付款详细信息，因此我们首先将讨论 `Invoice` 类。
|
||||
|
||||
|
||||
#### 使用费用清单进行工作
|
||||
|
||||
在做任何事情之前，您需要使用 `Invoice` 类来创建费用清单。
|
||||
|
||||
像下面这样，在你的代码中使用费用清单:
|
||||
|
||||
```php
|
||||
// At the top of the file.
|
||||
use Shetabit\Multipay\Invoice;
|
||||
...
|
||||
|
||||
// Create new invoice.
|
||||
$invoice = new Invoice;
|
||||
|
||||
// 设置清单金额.
|
||||
$invoice->amount(1000);
|
||||
|
||||
// 给清单添加详情: 这里展示了四种语法.
|
||||
// 1
|
||||
$invoice->detail(['detailName' => 'your detail goes here']);
|
||||
// 2
|
||||
$invoice->detail('detailName','your detail goes here');
|
||||
// 3
|
||||
$invoice->detail(['name1' => 'detail1','name2' => 'detail2']);
|
||||
// 4
|
||||
$invoice->detail('detailName1','your detail1 goes here')
|
||||
->detail('detailName2','your detail2 goes here');
|
||||
|
||||
```
|
||||
可用方法:
|
||||
|
||||
- `uuid`: 设置一个清单的唯一id
|
||||
- `getUuid`: 获取清单的当前唯一id
|
||||
- `detail`: 给清单添加自定义信息
|
||||
- `getDetails`: 获取所有的详细信息
|
||||
- `amount`: 设置一个清单金额
|
||||
- `getAmount`: 获取清单金额
|
||||
- `transactionId`: 设置支付交易单号
|
||||
- `getTransactionId`: 获取支付交易单号
|
||||
- `via`: 设置我们用来支付清单的驱动
|
||||
- `getDriver`: 获取驱动
|
||||
|
||||
#### 获取支付清单
|
||||
|
||||
为了支付清单，我们需要付款交易ID:
|
||||
|
||||
```php
|
||||
// At the top of the file.
|
||||
use Shetabit\Multipay\Invoice;
|
||||
use Shetabit\Payment\Facade\Payment;
|
||||
...
|
||||
|
||||
// Create new invoice.
|
||||
$invoice = (new Invoice)->amount(1000);
|
||||
|
||||
// Purchase the given invoice.
|
||||
Payment::purchase($invoice,function($driver, $transactionId) {
|
||||
// We can store $transactionId in database.
|
||||
});
|
||||
|
||||
// Purchase method accepts a callback function.
|
||||
Payment::purchase($invoice, function($driver, $transactionId) {
|
||||
// We can store $transactionId in database.
|
||||
});
|
||||
|
||||
// You can specify callbackUrl
|
||||
Payment::callbackUrl('http://yoursite.com/verify')->purchase(
|
||||
$invoice,
|
||||
function($driver, $transactionId) {
|
||||
// We can store $transactionId in database.
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
#### 支付
|
||||
|
||||
在获取支付单后，我们可以跳转到第三方支付机构的页面
|
||||
|
||||
```php
|
||||
// At the top of the file.
|
||||
use Shetabit\Multipay\Invoice;
|
||||
use Shetabit\Payment\Facade\Payment;
|
||||
...
|
||||
|
||||
// Create new invoice.
|
||||
$invoice = (new Invoice)->amount(1000);
|
||||
// Purchase and pay the given invoice.
|
||||
// You should use return statement to redirect user to the bank page.
|
||||
return Payment::purchase($invoice, function($driver, $transactionId) {
|
||||
// Store transactionId in database as we need it to verify payment in the future.
|
||||
})->pay()->render();
|
||||
|
||||
// Do all things together in a single line.
|
||||
return Payment::purchase(
|
||||
(new Invoice)->amount(1000),
|
||||
function($driver, $transactionId) {
|
||||
// 把交易ID保存到数据库.
|
||||
// 在接下来的付款中，我们需要验证交易ID
|
||||
}
|
||||
)->pay()->render();
|
||||
|
||||
// Retrieve json format of Redirection (in this case you can handle redirection to bank gateway)
|
||||
return Payment::purchase(
|
||||
(new Invoice)->amount(1000),
|
||||
function($driver, $transactionId) {
|
||||
// 把交易ID保存到数据库.
|
||||
// 在接下来的付款中，我们需要验证交易ID
|
||||
}
|
||||
)->pay()->toJson();
|
||||
```
|
||||
|
||||
#### 验证付款
|
||||
|
||||
当用户完成付款后，支付机构会将其重定向到您的网站，然后您需要**验证您的付款**，以确保**清单**已**支付**。
|
||||
|
||||
```php
|
||||
// At the top of the file.
|
||||
use Shetabit\Payment\Facade\Payment;
|
||||
use Shetabit\Multipay\Exceptions\InvalidPaymentException;
|
||||
...
|
||||
|
||||
// 您需要验证支付机构的回传数据，以确保付款成功
|
||||
// 我们需要使用交易ID来验证
|
||||
// 使用交易金额来验证，也是一个很好的方法
|
||||
try {
|
||||
$receipt = Payment::amount(1000)->transactionId($transaction_id)->verify();
|
||||
|
||||
// You can show payment referenceId to the user.
|
||||
echo $receipt->getReferenceId();
|
||||
|
||||
...
|
||||
} catch (InvalidPaymentException $exception) {
|
||||
/**
|
||||
如果未验证付款，则会引发异常。
|
||||
|
||||
我们可以抓住异常处理无效付款。
|
||||
|
||||
getMessage方法，返回可在用户界面中使用的适当消息。
|
||||
**/
|
||||
echo $exception->getMessage();
|
||||
}
|
||||
```
|
||||
|
||||
#### 有用的方法
|
||||
|
||||
- ###### `callbackUrl`: 使用它可以在运行时改变回调地址.
|
||||
|
||||
```php
|
||||
// At the top of the file.
|
||||
use Shetabit\Multipay\Invoice;
|
||||
use Shetabit\Payment\Facade\Payment;
|
||||
...
|
||||
|
||||
// Create new invoice.
|
||||
$invoice = (new Invoice)->amount(1000);
|
||||
|
||||
// Purchase the given invoice.
|
||||
Payment::callbackUrl($url)->purchase(
|
||||
$invoice,
|
||||
function($driver, $transactionId) {
|
||||
// We can store $transactionId in database.
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
- ###### `amount`: 你可以设置一个清单的金额
|
||||
|
||||
```php
|
||||
// At the top of the file.
|
||||
use Shetabit\Multipay\Invoice;
|
||||
use Shetabit\Payment\Facade\Payment;
|
||||
...
|
||||
|
||||
// Purchase (we set invoice to null).
|
||||
Payment::callbackUrl($url)->amount(1000)->purchase(
|
||||
null,
|
||||
function($driver, $transactionId) {
|
||||
// We can store $transactionId in database.
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
- ###### `via`: 在运行中更改支付方式
|
||||
|
||||
```php
|
||||
// At the top of the file.
|
||||
use Shetabit\Multipay\Invoice;
|
||||
use Shetabit\Payment\Facade\Payment;
|
||||
...
|
||||
|
||||
// Create new invoice.
|
||||
$invoice = (new Invoice)->amount(1000);
|
||||
|
||||
// Purchase the given invoice.
|
||||
Payment::via('driverName')->purchase(
|
||||
$invoice,
|
||||
function($driver, $transactionId) {
|
||||
// We can store $transactionId in database.
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
- ###### `config`: 在运行中更改驱动的配置信息
|
||||
|
||||
```php
|
||||
// At the top of the file.
|
||||
use Shetabit\Multipay\Invoice;
|
||||
use Shetabit\Payment\Facade\Payment;
|
||||
...
|
||||
|
||||
// Create new invoice.
|
||||
$invoice = (new Invoice)->amount(1000);
|
||||
|
||||
// Purchase the given invoice with custom driver configs.
|
||||
Payment::config('mechandId', 'your mechand id')->purchase(
|
||||
$invoice,
|
||||
function($driver, $transactionId) {
|
||||
// We can store $transactionId in database.
|
||||
}
|
||||
);
|
||||
|
||||
// Also we can change multiple configs at the same time.
|
||||
Payment::config(['key1' => 'value1', 'key2' => 'value2'])->purchase(
|
||||
$invoice,
|
||||
function($driver, $transactionId) {
|
||||
// We can store $transactionId in database.
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
#### 创建自定义驱动:
|
||||
|
||||
首先必须在`drivers`数组中添加驱动程序的名称，还可以指定所需的任何配置参数。
|
||||
|
||||
```php
|
||||
'drivers' => [
|
||||
'zarinpal' => [...],
|
||||
'my_driver' => [
|
||||
... // Your Config Params here.
|
||||
]
|
||||
]
|
||||
```
|
||||
|
||||
现在您必须创建一个将用于支付清单的驱动程序映射类。
|
||||
在你的驱动中，你必须继承 `Shetabit\Payment\Abstracts\Driver`.这个类
|
||||
|
||||
例如，你创建了这样一个类: `App\Packages\PaymentDriver\MyDriver`。
|
||||
|
||||
```php
|
||||
namespace App\Packages\PaymentDriver;
|
||||
|
||||
use Shetabit\Multipay\Abstracts\Driver;
|
||||
use Shetabit\Multipay\Exceptions\InvalidPaymentException;
|
||||
use Shetabit\Multipay\{Contracts\ReceiptInterface, Invoice, Receipt};
|
||||
|
||||
class MyDriver extends Driver
|
||||
{
|
||||
protected $invoice; // Invoice.
|
||||
|
||||
protected $settings; // Driver settings.
|
||||
|
||||
public function __construct(Invoice $invoice, $settings)
|
||||
{
|
||||
$this->invoice($invoice); // Set the invoice.
|
||||
$this->settings = (object) $settings; // Set settings.
|
||||
}
|
||||
|
||||
// Purchase the invoice, save its transactionId and finaly return it.
|
||||
public function purchase() {
|
||||
// Request for a payment transaction id.
|
||||
...
|
||||
|
||||
$this->invoice->transactionId($transId);
|
||||
|
||||
return $transId;
|
||||
}
|
||||
|
||||
// Redirect into bank using transactionId, to complete the payment.
|
||||
public function pay() {
|
||||
// It is better to set bankApiUrl in config/payment.php and retrieve it here:
|
||||
$bankUrl = $this->settings->bankApiUrl; // bankApiUrl is the config name.
|
||||
|
||||
// Prepare payment url.
|
||||
$payUrl = $bankUrl.$this->invoice->getTransactionId();
|
||||
|
||||
// Redirect to the bank.
|
||||
return redirect()->to($payUrl);
|
||||
}
|
||||
|
||||
// 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.
|
||||
**/
|
||||
return new Receipt('driverName', 'payment_receipt_number');
|
||||
}
|
||||
}
|
||||
```
|
||||
创建该类后，必须在 `payment.php` 配置文件的 `map` 部分中指定它。
|
||||
|
||||
```php
|
||||
'map' => [
|
||||
...
|
||||
'my_driver' => App\Packages\PaymentDriver\MyDriver::class,
|
||||
]
|
||||
```
|
||||
|
||||
**Note:-** 必须确保 `map` 数组的键与 `drivers` 数组的键相同。
|
||||
|
||||
#### 事件
|
||||
|
||||
你可以监听两个事件
|
||||
|
||||
- **InvoicePurchasedEvent**: 在获取清单后执行
|
||||
- **InvoiceVerifiedEvent**: 在验证交易成功后执行
|
||||
|
||||
## Change log
|
||||
|
||||
请查看 [CHANGELOG](CHANGELOG.md) 来获取更多关于版本更新的信息
|
||||
|
||||
## 贡献
|
||||
|
||||
请查看 [CONTRIBUTING](CONTRIBUTING.md) 和 [CONDUCT](CONDUCT.md) 获取更多详细信息
|
||||
|
||||
## 安全
|
||||
|
||||
如果您发现任何与安全相关的问题，请发送电子邮件至`khanzadimahdi@gmail.com`，而不要使用issue。
|
||||
|
||||
## 信誉
|
||||
|
||||
- [Mahdi khanzadi][link-author]
|
||||
- [All Contributors][link-contributors]
|
||||
|
||||
## License
|
||||
|
||||
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
|
||||
|
||||
[ico-version]: https://img.shields.io/packagist/v/shetabit/payment.svg?style=flat-square
|
||||
[ico-download]: https://img.shields.io/packagist/dt/shetabit/payment.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/payment.svg?label=Code%20Quality&style=flat-square
|
||||
|
||||
[link-fa]: README-FA.md
|
||||
[link-en]: README.md
|
||||
[link-zh]: README-ZH.md
|
||||
[link-packagist]: https://packagist.org/packages/shetabit/payment
|
||||
[link-code-quality]: https://scrutinizer-ci.com/g/shetabit/payment
|
||||
[link-author]: https://github.com/khanzadimahdi
|
||||
[link-contributors]: ../../contributors
|
||||
Reference in New Issue
Block a user