README

您可以使用此客户端来消费支付服务。

使用此客户端，您可以使用两种传输方式发送请求

• 由BeanstalkProxyTransport实现的异步传输
• 由BasicTransport实现的同步传输

BeanstalkProxyTransport通过将支付实体发送到Beanstalkd队列将API消费委托给工作进程。

BasicTransport使用经典的HTTP层来同步发送支付。

您可以在示例文件夹中找到如何使用支付客户端方法的示例。

安装

付款客户端至少需要PHP 5.5才能正常工作。

将此要求添加到您的composer.json: "fei/payment-client": ": "^1.0"

或在终端中执行composer.phar require fei/payment-client。

如果您想使用付款客户端的异步功能（我们知道您想），则需要一个运行良好的Beanstalkd实例以及一个实例api-client-worker.php，该实例将消费Beanstalk的管道并将消息有效负载转发到支付API

Payer Client -> Beanstalkd -> api-client-worker.php -> Payment API server

Beanstalkd配置

运行Beanstalkd非常简单。然而，您必须注意z选项，该选项设置最大作业（或消息）大小（以字节为单位）。

运行api-client-worker.php

以下是如何运行api-client-worker.php的示例。

php /path/to/payment-client/vendor/bin/api-client-worker.php --host 127.0.0.1 --port 11300 --delay 3

您可以使用Supervisor来控制api-client-worker.php进程。

实体和类

支付实体

除了传统的id和createdAt字段外，支付实体还有十一个重要属性

• uuid是一个表示支付实体唯一标识符的字符串
• `createdAt'表示创建日期
• `payedAt'表示支付已完成的日期
• `expirationDate'表示支付到期日期
• status表示支付当前的状态
• orderId存储您的应用程序中的OrderId
• paymentMethod表示在平台上使用的支付方式（例如：在payzen中使用VISA）
• cancellationReason是一个表示支付取消原因的字符串
• requiredPrice是一个表示所需价格的浮点数
• capturedPrice是一个表示已捕获价格的浮点数
• authorizedPayment是一个表示授权支付的整数（用作二进制标志）
• selectedPayment是一个表示已选择的支付方式的整数
• contexts是一个包含实体所有上下文的ArrayCollection
• callbackUrl是一个回调URL数组，将在应用程序中的某些事件中使用（例如，当支付被保存时）。以下是回调URL的可能值和用途
  • succeeded：支付授权成功时将被调用的URL
  • failed：支付授权失败时将被调用的URL
  • cancelled：支付被取消时将被调用的URL

上下文实体

除了传统的id字段外，上下文实体还有三个重要属性

• key是一个表示上下文键的字符串
• value是一个表示附加到此上下文的值的字符串
• payment是一个表示与该上下文相关的支付实体的支付实体

基本用法

为了使用 Payer 方法，您必须定义一个新的 Payer 实例并设置正确的传输方式（异步或同步）。

<?php

use Fei\Service\Payment\Client\Payer;
use Fei\ApiClient\Transport\BasicTransport;
use Fei\ApiClient\Transport\BeanstalkProxyTransport;
use Pheanstalk\Pheanstalk;

$payer = new Payer([Payer::OPTION_BASEURL => 'https://payment.api']); // Put your payment API base URL here
$payer->setTransport(new BasicTransport());

$proxy = new BeanstalkProxyTransport();
$proxy->setPheanstalk(new Pheanstalk('127.0.0.1'));

$payer->setAsyncTransport($proxy);

// Use the payer client methods...

Payer 客户端实例首先会尝试使用 Beanstalkd 转发消息，如果过程失败，则客户端会直接尝试将支付负载发送到正确的 API 端点。

Payer 类中有几个方法，所有方法都列在下面的表中

客户端选项

只有一个选项可用，可以通过构造函数或通过调用 setOptions 方法 Payer::setOptions(array $options) 来传递

注意：以下所有示例都在 examples 目录中提供。

请求

您可以使用 Payer 客户端的 request() 方法创建新的支付。

示例

<?php
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Payment\Client\Payer;
use Fei\Service\Payment\Entity\Payment;

$payer = new Payer([Payer::OPTION_BASEURL => 'http://payment.dev']);
$payer->setTransport(new BasicTransport());

$payment = new Payment();
$payment->setExpirationDate(new \DateTime())
		->setStatus(Payment::STATUS_PENDING)
		->setOrderId('ORDERID')
		->setPaymentMethod('VISA')
		->setRequiredPrice(456)
		->setAuthorizedPayment(Payment::PAYMENT_PAYPAL)
		->setCallbackUrl([
				"succeeded" => 'http://url-succeeded.fr',
				"failed" => 'http://url-failed.fr',
				"saved" => 'http://url-saved.fr',
				"cancelled" => 'http://url-cancelled.fr',
		]);

$payment = $payer->request($payment);

更新

您可以使用 Payer 客户端的 update() 方法更新现有的支付。

示例

<?php
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Payment\Client\Payer;
use Fei\Service\Payment\Entity\Payment;

$payer = new Payer([Payer::OPTION_BASEURL => 'http://payment.dev']);
$payer->setTransport(new BasicTransport());

$payment = new Payment();
$payment->setExpirationDate(new \DateTime())
		->setStatus(Payment::STATUS_PENDING)
		->setRequiredPrice(456)
		->setAuthorizedPayment(Payment::PAYMENT_PAYPAL)
		->setCallbackUrl([
				"succeeded" => 'http://url-succeeded.fr',
				"failed" => 'http://url-failed.fr',
				"saved" => 'http://url-saved.fr',
				"cancelled" => 'http://url-cancelled.fr',
		]);

$paymentId = $payer->request($payment);

$payment->setRequiredPrice(327.4);
$payer->update($payment);

检索

您可以使用 Payer 客户端的 retrieve() 方法检索一个支付，该方法接受一个参数：支付实体的 id 或支付的 uuid。

示例

<?php
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Payment\Client\Payer;

$payer = new Payer([Payer::OPTION_BASEURL => 'http://payment.dev']);
$payer->setTransport(new BasicTransport());

$payment = $payer->retrieve(1); // retrieve by it's integer id
$payment = $payer->retrieve('81db1f4e-e938-440a-aae0-95b5994db015'); // retrieve by it's string uuid

搜索

您可以使用 Payer 客户端的 search() 方法搜索支付，该方法接受一个 SearchBuilder 实例。

示例

<?php
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Payment\Client\Payer;
use Fei\Service\Payment\Client\Utils\Builder\SearchBuilder;

$payer = new Payer([Payer::OPTION_BASEURL => 'http://payment.dev']);
$payer->setTransport(new BasicTransport());

$builder = new SearchBuilder();
$builder->uuid()->equal('81db1f4e-e938-440a-aae0-95b5994db012');
$payments = $payer->search($builder);

echo '<pre>';
print_r($payments);
echo '</pre>';

取消

您可以使用 Payer 客户端的 cancel() 方法取消一个支付，该方法接受一个 Payment 实例（或 id）和一个用于取消原因的 string。

示例

<?php
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Payment\Client\Payer;

$payer = new Payer([Payer::OPTION_BASEURL => 'http://payment.dev']);
$payer->setTransport(new BasicTransport());

$paymentId = $payer->cancel(1, 'Cancel by an administrator');

拒绝

您可以使用 Payer 客户端的 reject() 方法拒绝一个支付，该方法接受一个 Payment 实例（或 id）和一个用于取消原因的 string。

示例

<?php
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Payment\Client\Payer;

$payer = new Payer([Payer::OPTION_BASEURL => 'http://payment.dev']);
$payer->setTransport(new BasicTransport());

$paymentId = $payer->reject(1, 'Rejected by an administrator');

捕获

您可以使用 Payer 客户端的 capture() 方法捕获一个支付，该方法接受一个 Payment 实例（或 id）和一个用于捕获金额的 float。

示例

<?php
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Payment\Client\Payer;

$payer = new Payer([Payer::OPTION_BASEURL => 'http://payment.dev']);
$payer->setTransport(new BasicTransport());

$paymentId = $payer->capture(1, 10.36);

获取支付链接

您可以使用 Payer 客户端的 getPaymentLink() 方法获取公开的支付链接以处理支付，该方法接受一个 Payment 实例或 id 或 uuid。

示例

<?php
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Payment\Client\Payer;

$payer = new Payer([Payer::OPTION_BASEURL => 'http://payment.dev']);
$payer->setTransport(new BasicTransport());

try {
    echo $payer->getPaymentLink(23);
} catch (\Exception $e) {
    echo $e->getMessage() . PHP_EOL;
    $previous = $e->getPrevious();
    if ($previous instanceof Guzzle\Http\Exception\ServerErrorResponseException) {
        var_dump($previous->getRequest());
        var_dump($previous->getResponse()->getBody(true));
    }
}