README

پیرو۲۴

该包是为 Laravel 创建的，用于通过 Payro 支付网关进行在线支付。

安装

使用 Composer 安装

$ composer require payro/payment

配置

然后运行 php artisan vendor:publish 命令以在 config/payment.php 目录下创建配置文件。

如果您使用的是 Laravel 5.5 或更高版本，则不需要进行 providers 和 alias 的配置。

在 config/app.php 文件中添加以下指令：

# In your providers array.
'providers' => [
    ...
    Payro\Payment\Provider\PaymentServiceProvider::class,
],

# In your aliases array.
'aliases' => [
    ...
    'Payment' => Payro\Payment\Facade\Payment::class,
],

然后进行 Payro 支付网关的配置。

'drivers' => [
        'payro24' => [
            'apiPurchaseUrl' => 'https://api.payro24.ir/v1.0/payment',
            'apiPaymentUrl' => 'https://payro24.ir/',
            'apiVerificationUrl' => 'https://api.payro24.ir/v1.0/payment/verify',
            'merchantId' => '',
            'callbackUrl' => 'http://yoursite.com/path/to',
            'description' => 'payment in '.config('app.name'),
            'sandbox' => false, // set it to true for test environments
        ]
]

使用方法

在所有支付中，您的账单信息将保存在您的账单中。要使用此包，我们首先将说明如何使用 Invoice 类来处理账单。

处理账单

在开始之前，您需要创建一个账单。您可以使用 Invoice 类来创建账单。

在您的代码中执行以下操作：

# On the top of the file.
use Payro\Payment\Invoice;
...

# create new invoice
$invoice = new Invoice;

# set invoice amount
$invoice->amount(1000);
$invoice->detail(['name1' => 'detail1','name2' => 'detail2']);

用于处理账单的方法

• uuid : 为账单设置一个唯一的 ID
• getUuid : 返回账单的唯一 ID
• detail : 向账单添加描述或相关项目
• getDetails : 返回添加到账单的所有相关项目
• amount : 指定应支付的费用金额
• getAmount : 返回账单的费用
• transactionId : 指定账单的转账 ID
• getTransactionId : 返回账单的转账 ID
• getDriver : 返回选择的驱动程序

请求支付账单

为了支付所有账单，我们需要一个转账银行账号或 transactionId。通过提交支付请求，我们可以获取转账银行账号。

# On the top of the file.
use Payro\Payment\Invoice;
use Payro\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
	}
);

支付账单

使用转账 ID 或 transactionId，我们可以将用户引导到银行的支付页面。

# On the top of the file.
use Payro\Payment\Invoice;
use Payro\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's page.
return Payment::purchase($invoice, function($driver, $transactionId) {
    // store transactionId in database, we need it to verify payment in future.
})->pay();

# do all things together a single line
return Payment::purchase(
    (new Invoice)->amount(1000), 
    function($driver, $transactionId) {
    	// store transactionId in database.
        // we need the transactionId to verify payment in future
	}
)->pay();

支付验证

用户支付账单后，银行会将用户返回到我们网站的某个页面，我们通过验证可以确定用户是否已成功支付！

# On the top of the file.
use Payro\Payment\Facade\Payment;
use Payro\Payment\Exceptions\InvalidPaymentException;
...

# you need to verify the payment to insure the invoice has been paid successfully
// we use transaction's id to verify payments
// its a good practice to add invoice's amount.
try {
	$receipt = Payment::amount(1000)->transactionId($transaction_id)->verify();

    // you can show payment's referenceId to user
    echo $receipt->getReferenceId();    

    ...
} catch (InvalidPaymentException $exception) {
    /**
    	when payment is not verified , it throw an exception.
    	we can catch the excetion to handle invalid payments.
    	getMessage method, returns a suitable message that can be used in user interface.
    **/
    echo $exception->getMessage();
}

如果用户支付不正确，将抛出一个类型为 InvalidPaymentException 的异常，其中包含有关已支付支付的适当消息。

有用的方法

• callbackUrl : 使用此方法可以动态指定用户在线支付后将被重定向的页面地址

  # On the top of the file.
  use Payro\Payment\Invoice;
  use Payro\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 : 使用此方法可以直接指定账单的费用

  # On the top of the file.
  use Payro\Payment\Invoice;
  use Payro\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
  	}
  );

事件

您可以在程序中注册和记录两个事件

• InvoicePurchasedEvent : 当支付成功记录时发生此事件
• InvoiceVerifiedEvent : 当支付成功验证时发生此事件