README

GOV.UK Pay API 的 PHP 客户端

截至 2021 年 9 月，此存储库不再由 GOV.UK Pay 团队积极维护。

PSR-7 HTTP

Pay PHP 客户端基于 PSR-7 HTTP 模型。因此，您需要选择您首选的 HTTP 客户端库来使用。

我们将在此处使用 Guzzle v6 适配器来展示示例。

安装

可以使用 Composer 安装 Pay PHP 客户端。运行以下命令

composer require php-http/guzzle6-adapter alphagov/pay-integration-php

使用方法

假设您已通过 Composer 安装了该包，Pay PHP 客户端将通过自动加载器提供。

使用以下方法创建一个（基于 Guzzle v6 的）Client 实例：

$client = new \Alphagov\Pay\Client([
    'apiKey'        => '{your api key}',
    'httpClient'    => new \Http\Adapter\Guzzle6\Client
]);

然后您可以使用 $client 访问 Pay API。

如果需要访问非生产环境，可以在构造函数中通过 baseUrl 键传递基本 URL。

'baseUrl' => '{api base url}'

创建支付

方法签名如下：

createPayment( $amount, $reference, $description, UriInterface $returnUrl )

其中

• $amount 必需的 int，表示支付金额，以便士为单位，英镑（GBP）。
• $reference 必需的 string，表示应用程序端的支付参考。
• $description 必需的 string，表示支付描述。
• $returnUrl 必需的 Psr\Http\Message\UriInterface，表示用户将被重定向到的 URL。

一个示例请求如下：

try {

    $response = $client->createPayment(
        10 * 100, // £10
        'id-123',
        'Payment for x, y and z.',
        new \GuzzleHttp\Psr7\Uri('https://www.example.service.gov.uk/pay/response')
    );

} catch (PayException $e){}

$response 将是一个 Alphagov\Pay\Response\Payment 实例，该实例在此处有文档说明；或 如果支付未找到，则为 null。

如果发生 Pay 错误，将抛出一个 Alphagov\Pay\Exception\PayException 实例（或其子类）。

查找支付

方法签名如下：

getPayment( $payment )

其中

• $payment 是必需的 string，包含（Pay 生成的）支付 ID。

一个示例请求如下：

try {

    $response = $client->getPayment( 'hu20sqlact5260q2nanm0q8u93' );

} catch (PayException $e){}

$response 将是一个 Alphagov\Pay\Response\Payment 实例，该实例在此处有文档说明；或 如果支付未找到，则为 null。

如果发生 Pay 错误，将抛出一个 Alphagov\Pay\Exception\PayException 实例（或其子类）。

取消支付

方法签名如下：

cancelPayment( $payment )

• $payment 是必需的 string，包含（Pay 生成的）支付 ID。

一个示例请求如下：

try {

    $response = $client->cancelPayment( 'hu20sqlact5260q2nanm0q8u93' );

} catch (PayException $e){}

$response 将是布尔值 true，如果支付被取消。否则，如果发生 Pay 错误，将抛出一个 Alphagov\Pay\Exception\PayException 实例（或其子类）。

退款支付

方法签名如下：

refundPayment( $payment, $amount, $refundAmountAvailable = null )

• $payment 是必需的 string，包含（Pay 生成的）支付 ID。
• $amount 必需的 int，包含要退款的金额，以便士为单位，英镑（GBP）。
• $refundAmountAvailable 可选的 int，包含预期的退款金额，以便士为单位，英镑（GBP）。

一个示例请求如下：

try {

    $response = $client->refundPayment( 
    	'hu20sqlact5260q2nanm0q8u93', 
        10 * 100, // £10
        50 * 100  // £50
    );

} catch (PayException $e){}

$response 将是一个 Alphagov\Pay\Response\Refund 实例，该实例在此处有文档说明 [文档]。

如果发生 Pay 错误，将抛出一个 Alphagov\Pay\Exception\PayException 实例（或其子类）。

查找付款的所有退款

方法签名如下：

getPaymentRefunds( $payment )

其中

• $payment 是必需的 string，包含（Pay 生成的）支付 ID。

一个示例请求如下：

try {

    $response = $client->getPaymentRefunds( 'hu20sqlact5260q2nanm0q8u93' );

} catch (PayException $e){}

$response 将是一个 Alphagov\Pay\Response\Refunds 实例，它将包含每个处理的退款的一个 Alphagov\Pay\Response\Refund 实例（[文档]）。

如果发生 Pay 错误，将抛出一个 Alphagov\Pay\Exception\PayException 实例（或其子类）。

查找付款的单个退款

方法签名如下：

getPaymentRefund( $payment, $refund )

其中

• $payment 是必需的 string，包含（Pay 生成的）支付 ID。
• $refund 是一个必需的 字符串，包含（由 Pay 生成的）退款 ID。

一个示例请求如下：

try {

    $response = $client->getPaymentRefunds( 
      'hu20sqlact5260q2nanm0q8u93', 
      'j2cg5v7et0424d7shtrt7r0mj'
    );

} catch (PayException $e){}

$response 将是一个 Alphagov\Pay\Response\Refund 实例（[文档]），如果退款未找到，则为 NULL。

如果发生 Pay 错误，将抛出一个 Alphagov\Pay\Exception\PayException 实例（或其子类）。

查找付款的所有事件

方法签名如下：

getPaymentEvents( $payment )

其中

• $payment 是必需的 string，包含（Pay 生成的）支付 ID。

一个示例请求如下：

try {

    $response = $client->getPaymentEvents( 'hu20sqlact5260q2nanm0q8u93' );

} catch (PayException $e){}

$response 将是一个 Alphagov\Pay\Response\Events 实例，它将包含每个事件的一个 Alphagov\Pay\Response\Event 实例（[文档]）。

如果发生 Pay 错误，将抛出一个 Alphagov\Pay\Exception\PayException 实例（或其子类）。

搜索付款

方法签名如下：

searchPayments( array $filters = array() )

其中

• $filters 一个可选的 数组，它将过滤器应用于请求。可以使用零个或多个过滤器。支持的过滤器：
  • reference 字符串
  • state 字符串
  • page 字符串
  • display_size 字符串
  • from_date DateTime
  • to_date DateTime

完整的过滤详情可以在此处找到：https://gds-payments.gelato.io/docs/versions/1.0.0/resources/general/endpoints/search-payments

一个示例请求如下：

try {

    $response = $client->searchPayments([
    	'from_date' => new \DateTime('2015-08-14T12:35:00Z'),
        'page' => '2',
        'display_size' => '50'
    ]);

} catch (NotifyException $e){}

$response 将是一个 Alphagov\Pay\Response\Payments 实例，它将包含每个找到的付款的一个 Alphagov\Pay\Response\Payment 实例（[文档]）。

如果发生 Pay 错误，将抛出一个 Alphagov\Pay\Exception\PayException 实例（或其子类）。

响应

除了 Event 以外的所有 Response 对象都有一个 getResponse() 方法，它返回一个实现 Psr\Http\Message\ResponseInterface 的类，包含原始 API 响应。

付款

Alphagov\Pay\Response\Payment 的一个实例，它包含来自 Pay API 的解码 JSON 响应，代表一次付款。

返回的属性完整列表可以在此处找到：https://gds-payments.gelato.io/docs/versions/1.0.0/resources/payment-id/endpoints/find-payment-by-id

可以使用 -> 操作符直接访问属性。例如

$response->payment_id
$response->created_date
// etc...

如果可用，可以通过以下方式访问将用户直接引导到付款页面的 URL：

$response->getPaymentPageUrl();

这将返回

• 一个表示 URL 的 Psr\Http\Message\UriInterface 实例；或者
• null 如果 URL 不可用（例如，如果付款已完成）。

Payment 还包括用于检查付款状态的方法

付款是 完成的。即用户不能再与付款页面交互。

$response->isFinished()

付款是 成功的。

$response->isSuccess()

也可以通过以下方式检查所有其他标准的 Pay 状态

$response->isCreated()
$response->isStarted()
$response->isSubmitted()
$response->isFailed()
$response->isCancelled()
$response->isError()

退款

Alphagov\Pay\Response\Refund 的一个实例，它包含来自 Pay API 的解码 JSON 响应，代表一次退款。

返回属性的完整列表可以在此处找到：https://gds-payments.gelato.io/docs/versions/1.0.0/resources/payment-id/endpoints/find-payment-refund-by-id

可以使用 -> 操作符直接访问属性。例如

$response->refund_id
$response->status
$response->amount
// etc...

事件

是 Alphagov\Pay\Response\Event 的一个实例，它包含了来自 Pay API 解码后的 JSON 响应，代表一个单独的事件。

返回属性的完整列表可以在此处找到：https://gds-payments.gelato.io/docs/versions/1.0.0/resources/payment-id/endpoints/return-payment-events-by-id

可以使用 -> 操作符直接访问属性。例如

$response->state
$response->updated
// etc...

付款、退款和事件

这三个响应都代表各自响应类型的集合。它们都扩展了 PHP 的 ArrayObject，因此可以将其视为数组。

退款和事件还支持添加 $response->payment_id 属性，包含相关的付款 ID。

许可证

Pay PHP 客户端是在 MIT 许可证下发布的，许可证的副本可以在 LICENSE 中找到。