README

这是 The Pay SDK 的官方高度兼容公共包，与 The Pay 的 REST API 交互。要开始，请参考下面的示例。

需求

所有必要的需求都在 composer.json 的 require 属性中定义。我们强烈建议使用 Composer 安装 SDK！

安装

composer require thepay/api-client

使用推荐的 PSR http 客户端进行安装。

composer require thepay/api-client guzzlehttp/guzzle

本项目遵循 语义版本控制。

支持 & 贡献

如果您发现任何错误，请在 Github 上提交 问题。

请通过 Github 问题 和 pull requests 自由地贡献。我们将尽快回复。请记住向后兼容性，并且在没有之前管理员同意的情况下不要更改要求。

先决条件

请确保您拥有所有必要的凭证，并且已经在 管理 中设置了 API 访问。

• 商户 ID
• 项目 ID
• API 访问密码
• 在项目设置中启用了您的 IP 地址（您必须添加服务器 IP 地址或 IP 地址范围）

为了测试集成，您可以在我们的 DEMO 环境 中创建简化的“即用”DEMO 账户。

您可以在商户资料下的“实施”部分找到所有必要的凭证。

用法

当使用此 SDK 时，您将只与两个类一起工作。

• TheConfig - 用于设置库
• TheClient - 用于主要功能（调用 API，渲染助手）

配置

所有构造函数参数在 php doc 中描述。

$merchantId = '86a3eed0-95a4-11ea-ac9f-371f3488e0fa';
$projectId = 3;
$apiPassword = 'secret';
$apiUrl = 'https://demo.api.thepay.cz/'; // production: 'https://api.thepay.cz/'
$gateUrl = 'https://demo.gate.thepay.cz/'; // production: 'https://gate.thepay.cz/'
$language = 'cs';

$theConfig = new \ThePay\ApiClient\TheConfig(
    $merchantId,
    $projectId,
    $apiPassword,
    $apiUrl,
    $gateUrl
);

$theConfig->setLanguage($language);

TheClient 实例

在创建 \ThePay\ApiClient\TheClient 实例之前，必须准备一些依赖项。

如果您使用某些 DI 容器自动化，则除了 TheConfig 之外的所有依赖项都应该自动注入，即使是 PSR 接口，如果您已经在应用程序中安装了一些实现。

/** @var \ThePay\ApiClient\TheConfig $theConfig */

// TheClient instance dependencies
$signatureService = new \ThePay\ApiClient\Service\SignatureService($theConfig);
/** @var \Psr\Http\Client\ClientInterface $httpClient some PSR-18 implementation */
/** @var \Psr\Http\Message\RequestFactoryInterface $requestFactory some PSR-17 implementation */
/** @var \Psr\Http\Message\StreamFactoryInterface $streamFactory some PSR-17 implementation */
// if you install suggested guzzle implementation you can use this:
// $httpClient = new \GuzzleHttp\Client();
// $requestFactory = $streamFactory = new \GuzzleHttp\Psr7\HttpFactory();
$apiService = new \ThePay\ApiClient\Service\ApiService(
    $theConfig,
    $signatureService,
    $httpClient,
    $requestFactory,
    $streamFactory
);

$thePayClient = new \ThePay\ApiClient\TheClient(
    $theConfig,
    $apiService
);

常规工作流程

创建付款时有三步

• 创建一个客户将通过它进行付款的链接
• 处理客户返回到您的网站
• 处理来自我们的服务器到服务器的通知，这些通知在付款状态每次改变时都会发送

所有这些步骤都需要您自己实现，但请放心，我们已经准备了示例，可以帮助您在我们的 SDK 中进行旅行。

1. 付款创建

付款（链接）可以通过两种方法创建

• REST API
• 重定向

无论您选择哪种方法，您还有另外两个基于预选支付方式的选择

• 在电子商务中预选的支付方式
• 未预选的支付方式 - 客户将在 ThePay 网关中选择支付方式

即使您（或您的客户）预先选择了支付方式，在重定向后仍可以更改，除非明确禁止。

REST API

您可以通过REST API创建支付链接，并将用户重定向到该链接。支付本身是通过API调用创建的。这是自定义表单和您想在整个购物车流程完成后重定向用户的推荐方式。

您可以在您的平台上预先选择支付方式，并将其简单地作为支付参数添加到API中。否则，客户将通过生成的链接访问ThePay网关时，将看到支付方式选择。

在调用支付创建的API端点后，将返回给您支付链接。

客户重定向

第二种（更简单）的方法是将客户重定向到带有支付参数的支付网关。一旦客户被重定向，支付就会立即创建。此SDK将生成支付按钮，完成所有工作。

您可以在您的电子商务平台上预先选择支付方式，并将其简单地作为支付参数添加到正确的方法中。否则，客户将通过生成的链接访问ThePay网关时，将看到支付方式选择。

SDK会在生成支付按钮的方法中使用时生成支付链接。客户访问链接时，我们这边就会创建支付。

支付金额不可更改

如果您的订单金额发生变化，则需要创建新的支付。

支付流程和变更

您应该始终为您的电子商务平台上的每个订单只创建一个支付（带有其唯一的UID）。您永远不应该创建新的支付，除非需要更改支付金额。在这种情况下，请将其视为全新的支付。

TL;DR - 摘要

这些都是创建支付的常见方式

• API - 通过API调用创建支付（在电子商务平台或ThePay网关中选择支付方式）
• ThePay网关中选择支付方式的重定向
• 电子商务平台中选择支付方式的重定向

对于所有支付创建选项，始终为您的订单创建一个支付，除非您需要更改支付金额。在这种情况下，请将其视为全新的支付。

更多示例请参阅 create-payment.md

了解如何制作TheClient

/** @var \ThePay\ApiClient\TheClient $thePayClient */

// Render payment methods for payment (100,- Kč)
$paymentParams = new \ThePay\ApiClient\Model\CreatePaymentParams(10000, 'CZK', 'uid124');

// display button, user will choose payment method at the payment gate
echo $thePayClient->getPaymentButton($paymentParams);

// or buttons with available payment methods, payment method will be preselected
// echo $thePayClient->getPaymentButtons($paymentParams);

// or just get payment link and redirect customer whenever you want
// $payment = $thePayClient->createPayment($createPayment);
// $redirectLink = $payment->getPayUrl();

2. 客户返回

客户将从ThePay网关返回到返回URL地址。

返回URL在管理中设置，客户将带有两个查询参数被重定向到那里 - payment_uid和project_id（如果您有一个端点用于多个项目，则需要）。

必须在客户返回时检查支付状态，因为支付可能在此时不总是处于已支付状态。例如，客户可能只是返回到电子商务平台而没有支付。

处理客户返回的通用示例

了解如何制作TheClient

/** @var \ThePay\ApiClient\TheClient $thePayClient */

$payment = $thePayClient->getPayment($uid);

// check if the payment is paid
if ($payment->wasPaid()) {
    // Check if the order isn't labeled as paid yet. If not, do so.
    // ...
}

3. 服务器到服务器通知

这基本上与第二步（客户返回）相同，它在支付每次更改时触发，例如当支付状态更改时。

了解如何制作TheClient

/** @var \ThePay\ApiClient\TheClient $thePayClient */

$payment = $thePayClient->getPayment($uid);

// check if the payment is paid
if ($payment->wasPaid()) {
    // Check if the order isn't labeled as paid yet. If not, do so.
    // ...
}

更多和详细的使用示例

您可以在文件夹 /doc中找到更多使用示例。

货币计算

为了安全地进行货币计算，我们建议使用moneyphp/money包。请不要使用浮点数保存有关价格的信息，因为其不准确。

composer require moneyphp/money