README

Payvision PHP SDK 代码库

这是Payvision支付平台的官方PHP SDK（https://www.payvision.com）。它可以用来利用Payvision API的以下功能

支付
- 创建支付请求
- 创建捕获请求
- 创建取消请求
- 创建退款请求
- 获取交易状态更新
支付链接
- 创建新的支付链接
- 获取现有支付链接的状态
- 取消现有支付链接
结账
- 初始化新的结账
- 获取结账状态
Webhooks
- 将原始Webhooks数据转换为适当的对象

安装

此软件包可以使用Composer安装

composer require payvision/payvision-sdk-php

用法

初始化API

要初始化API连接，请参考以下代码片段

use Payvision\SDK\Infrastructure\ApiConnection;

$apiConnection = new ApiConnection(
    'username',
    'password',
    ApiConnection::URI_TEST,    // =URL to connect to, optional
    false                       // debug mode, see debugging
);

API调试

API使用Guzzle HTTP客户端。debug属性被传递给Guzzle客户端。有关调试的更多信息，请参阅http://docs.guzzlephp.org/en/stable/request-options.html#debug。

创建请求

PHP SDK是Payvision API请求和响应JSON结构构建的直接反映。

例如，对Payvision API的典型支付请求需要一个如下的JSON正文

{
  "header" : {
    "businessId" : "{businessId}"
  },
  "action" : "authorize",
  "body" : {
    "card" : {
      "holderName" : "John Doe",
      "number" : "4111111111111111",
      "expiryMonth" : "03",
      "expiryYear" : "2020"
    },
    "transaction" : {
      "amount" : "1.00",
      "brandId" : "1010",
      "trackingCode" : "7F4BFD5D-55E4-4775-81F7-0784188876C7",
      "currencyCode" : "EUR"
    }
  }
}

要使用PHP SDK创建此相同的请求，您可以使用复合构建器之一

use Payvision\SDK\Domain\Payments\Service\Builder\Composite\Payment\Request as PaymentRequestBuilder;
use Payvision\SDK\Domain\Payments\ValueObject\Payment\Request as PaymentRequest;

/** @var $paymentRequestBuilder PaymentRequestBuilder */
$paymentRequestBuilder->header()->setBusinessId('{businessId}');
$paymentRequestBuilder->body()->card()
    ->setHolderName('John Doe')
    ->setNumber('4111111111111111')
    ->setExpiryMonth(3)
    ->setExpiryYear(2020)
$paymentRequestBuilder->body()->transaction()
    ->setAmount(1.00)
    ->setBrandId(1010)
    ->setTrackingCode('7F4BFD5D-55E4-4775-81F7-0784188876C7')
    ->setCurrencyCode('EUR');
$paymentRequestBuilder->setAction(PaymentRequest::ACTION_AUTHORIZE);
$requestObject = $paymentRequestBuilder->build();

到目前为止，您已经有了将要发送到API的JSON对象的PHP表示，但它还不是实际请求。例如：我们仍然需要知道它需要发送到的URL以及从API可以期待什么样的响应。

为此，我们需要将我们的支付请求转换为API请求

use Payvision\SDK\Application\Payments\Service\RequestBuilder;    
$apiRequest = RequestBuilder::newPayment($requestObject);

现在我们有一个API请求，我们可以使用我们的API连接来执行

$requestHeaders = []; // Optional request headers
$apiResponse = $apiConnection->execute($apiRequest, $requestHeaders);

关于构建器

**强烈建议**您始终使用SDK提供的构建器来创建对象，而不要直接实例化它们。原因在于值对象构造函数调用的方法签名可能会随着API规范的扩展而频繁更改。这可能导致您的代码中出现向后兼容性破坏性更改。构建器通过抽象值对象的创建来克服这个问题。而且它们也更加易于使用。

作为响应处理数组

某些API端点不会返回单个对象，而是一个对象数组。例如，获取支付端点是这种情况。

在这种情况下，如果您作为开发者知道您可以期待一个数组作为结果，您需要使用ApiConnection::executeAndReturnArray()-方法而不是execute()-方法

$apiRequest = RequestBuilder::getPayments($businessId, $trackingCode);
$apiResponses = $apiConnection->executeAndReturnArray($apiRequest);
$apiResponse = $apiResponses[0]; // for example

处理响应

上面的例子中，$apiResponse是定义在请求中的类型的对象。要了解这是哪种类型，您可以使用$apiRequest->getResponseObjectByStatusCode(200)。

如果API返回非2XX状态，则会抛出类型为Payvision\SDK\Exception\Api\ErrorResponse的异常。此异常包含一个错误对象，其中包含有关发生错误的更多信息。

try {
    $apiResponse = $apiConnection->execute($apiRequest);
} catch (ErrorResponse $errorResponseException) {
    /** \Payvision\SDK\Domain\Payments\ValueObject\Payment\Response $apiResponse */
    $errorResponse = $errorResponseException->getErrorResponse();
}

Webhooks

SDK还可以处理Webhooks。为此，您需要以下输入数据：

事件签名（也称为JSON Web Token (JWT)。它包含在头信息中）
用于签名JWT的秘密
Webhook正文（作为字符串）。

您可以将这些数据传递给Webhook的EventBuilder服务。

use Payvision\SDK\Application\Reflection\JsonToObject;
use Payvision\SDK\Application\Webhook\Service\EventBuilder;
use Payvision\SDK\Domain\Webhook\Service\Validator;

$eventBuilderService = new EventBuilder(
    new Validator(),
    new JsonToObject()
);

$event = $eventBuilderService->generateEvent(
    'event signature',
    'secret',
    'json body'
);

由于Webhook事件的有效负载可以是各种对象，因此Event::getPayload()不能进行类型提示。因此，您可能需要对它进行一些额外的检查。

$payload = $event->getPayload();
if ($payload instanceof \Payvision\SDK\Domain\Payments\ValueObject\Response\Request) {
    ...
}

如果您不希望这样（因为这可能会因为此原因而在您的IDE中错过自动完成），您还可以使用EventBuilder::generateDecoratedEvent()来获取提供额外功能的EventDecorator，这样您就不必猜测有效负载是什么。

$decoratedEvent = $eventBuilderService->generateDecoratedEvent(
    'event signature',
    'secret',
    'json body'
);

if ($decoratedEvent->getPayloadType() === \Payvision\SDK\Domain\Webhook\Service\EventDecorator::TYPE_PAYMENT) {
    $payload = $decoratedEvent->getPaymentResponse();
}

装饰器还包含一些额外的检查，以确保有效负载已知。

开发者信息

如果您想分析或改进此SDK，建议阅读以下针对开发者的信息：

架构

SDK以领域驱动的方式设置。核心是值对象，它们是无状态的、不可变的构建块，用于API。值对象可以作为子属性拥有其他值对象。

顶级值对象（如支付请求）被转换为API请求对象，这些对象被发送到API，API反过来返回一个响应对象。逻辑从下到上，依赖关系从上到下。

+-------------------+
|   Value Object    |           Example: Transaction, Bank, Card, etc.
|                   |           These can be built manually, or by using the (composite) builders
+-------------------+
          ↓
   Request Builder              Builds request out of aggregate using reflection.
          ↓  
+-------------------+
|      Request      |           
+-------------------+
          ↓
      API Client                Does the request to the external API
          ↓
   Response Builder             Generates a response object out of the API response data using reflection.
          ↓  
+-------------------+
|      Response     |           Example: PaymentResponse
+-------------------+

故障排除

请参阅Troubleshooting.md

贡献

如果您有任何问题或功能请求，请随意创建问题。如果您想为此代码做出贡献，您可以发送一个pull request。

许可

请参阅LICENSE.txt

payvision / payvision-sdk-php

维护者

详情