README

ExpressPayments PHP 库提供从 PHP 编写的应用程序访问 ExpressPayments API 的便捷方式。它包含一组预定义的类，这些类可以从 API 响应动态初始化，使其与 ExpressPayments API 的多种版本兼容。

需求

PHP 5.6.0 及以上版本。

Composer

您可以通过以下命令使用 Composer 安装绑定

composer require expresspayments/expresspayments-php

要使用绑定，请使用 Composer 的自动加载

require_once 'vendor/autoload.php';

手动安装

如果您不想使用 Composer，您可以下载最新的版本。然后，要使用绑定，请包含 init.php 文件。

require_once '/path/to/expresspayments-php/init.php';

依赖

绑定需要以下扩展才能正常工作

curl，尽管您也可以选择使用您自己的非 cURL 客户端
json
mbstring（多字节字符串）

如果您使用 Composer，这些依赖项应自动处理。如果您手动安装，请确保这些扩展可用。

入门

简单用法如下

$expressPayments = new \ExpressPayments\ExpressPaymentsClient('sk_test_BQokikJOvBiI2HlWgH4olfQ2');
$customer = $expressPayments->customers->create([
    'description' => 'example customer',
    'email' => 'email@example.com',
    'payment_method' => 'pm_card_visa',
]);
echo $customer;

客户端/服务模式与旧模式

您可以继续使用在版本 7.33.0 之前使用的旧集成模式。请参阅迁移指南，了解向后兼容客户端/服务模式的变化。

文档

请参阅PHP API 文档。

请参阅视频演示，了解如何使用库。

旧版本支持

PHP 5.4 & 5.5

如果您正在使用 PHP 5.4 或 5.5，您应考虑升级您的环境，因为这些版本自 2015 年 9 月和 2016 年 7 月以来已经过了生命周期。否则，您仍然可以通过从我们的发布页面下载 expresspayments-php v6.43.1 (zip，tar.gz) 来使用 ExpressPayments。此版本将正常工作，但可能不支持自版本发布以来我们添加的某些新功能，升级 PHP 是最佳做法。

PHP 5.3

如果您正在使用 PHP 5.3，您应升级您的环境，因为这个版本自 2014 年 8 月以来已经过了生命周期。否则，您可以从我们的发布页面下载 v5.9.2 (zip，tar.gz)。此版本将继续与 ExpressPayments API 的新版本一起工作，适用于所有常见用途。

自定义请求超时

注意我们不建议降低非只读调用（例如创建充电）的超时时间，因为即使你本地超时，ExpressPayments方面的请求仍然可以完成。如果您正在降低这些调用的超时时间，请确保使用幂等令牌以避免超时重试逻辑导致执行相同的交易两次。

要修改请求超时（连接或总超时，以秒为单位），您需要告诉API客户端使用除默认以外的CurlClient。您将在该CurlClient中设置超时。

// set up your tweaked Curl client
$curl = new \ExpressPayments\HttpClient\CurlClient();
$curl->setTimeout(10); // default is \ExpressPayments\HttpClient\CurlClient::DEFAULT_TIMEOUT
$curl->setConnectTimeout(5); // default is \ExpressPayments\HttpClient\CurlClient::DEFAULT_CONNECT_TIMEOUT

echo $curl->getTimeout(); // 10
echo $curl->getConnectTimeout(); // 5

// tell ExpressPayments to use the tweaked client
\ExpressPayments\ApiRequestor::setHttpClient($curl);

// use the ExpressPayments API client as you normally would

自定义cURL选项（例如代理）

需要为请求设置代理吗？将必需的CURLOPT_*数组传递给CurlClient构造函数，使用与curl_stopt_array()相同的语法。这将设置SDK发出的每个HTTP请求的默认cURL选项，尽管即使在这里设置，客户端也会覆盖许多更常见的选项（例如超时；请参阅上面的说明以了解如何设置这些超时）。

// set up your tweaked Curl client
$curl = new \ExpressPayments\HttpClient\CurlClient([CURLOPT_PROXY => 'proxy.local:80']);
// tell ExpressPayments to use the tweaked client
\ExpressPayments\ApiRequestor::setHttpClient($curl);

或者，可以将一个可调用的函数传递给CurlClient构造函数，该函数基于请求输入返回上述数组。有关此行为的示例，请参阅tests/CurlClientTest.php中的testDefaultOptions()。请注意，该可调用的函数在每个API请求开始时被调用，在请求发送之前。

配置日志记录器

该库执行最少的日志记录，但可以通过配置PSR-3兼容的日志记录器，使消息最终出现在那里而不是error_log。

\ExpressPayments\ExpressPayments::setLogger($logger);

访问响应数据

您可以通过getLastResponse()在任何对象上访问最后API响应的数据。

$customer = $expressPayments->customers->create([
    'description' => 'example customer',
]);
echo $customer->getLastResponse()->headers['Request-Id'];

SSL / TLS兼容性问题

ExpressPayments的API现在要求所有连接使用TLS 1.2。一些系统（特别是某些较旧的CentOS和RHEL版本）能够使用TLS 1.2，但默认情况下会使用TLS 1.0或1.1。在这种情况下，您将收到以下错误信息的invalid_request_error：“ExpressPayments不再支持使用TLS 1.0发出的API请求。请使用TLS 1.2或更高版本的HTTPS连接。您可以在https://epayments.network/blog/upgrading-tls上了解更多信息。”

建议的做法是升级您的cURL和OpenSSL包，以便默认使用TLS 1.2，但如果无法这样做，您可能可以通过将CURLOPT_SSLVERSION选项设置为CURL_SSLVERSION_TLSv1或CURL_SSLVERSION_TLSv1_2来解决此问题。

$curl = new \ExpressPayments\HttpClient\CurlClient([CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1]);
\ExpressPayments\ApiRequestor::setHttpClient($curl);

按请求配置

对于在整个进程生命周期中需要使用多个密钥的应用程序，例如使用ExpressPayments Connect的应用程序，还可以设置每个请求的密钥和/或账户。

$customers = $expressPayments->customers->all([],[
    'api_key' => 'sk_test_...',
    'ep_account' => 'acct_...'
]);

$expressPayments->customers->retrieve('cus_123456789', [], [
    'api_key' => 'sk_test_...',
    'ep_account' => 'acct_...'
]);

配置CA包

默认情况下，库将使用自己的已知CA证书的内部包，但可以配置您自己的。

\ExpressPayments\ExpressPayments::setCABundlePath("path/to/ca/bundle");

配置自动重试

库可以配置为自动重试由于间歇性网络问题而失败的请求。

\ExpressPayments\ExpressPayments::setMaxNetworkRetries(2);

在请求中添加幂等键，以保证重试是安全的。

请求延迟遥测

默认情况下，库会将请求延迟遥测发送到ExpressPayments。这些数字有助于ExpressPayments提高其API对所有用户的整体延迟。

如果您愿意，可以禁用此行为。

\ExpressPayments\ExpressPayments::setEnableTelemetry(false);

测试版SDK

ExpressPayments在测试阶段具有可通过本包的测试版访问的功能。我们非常希望您尝试这些功能，并在这些功能进入稳定阶段之前与我们分享反馈。使用composer require命令并指定精确的版本来安装expresspayments-php包的测试版。

composer require expresspayments/expresspayments-php:v9.2.0-beta.1

注意测试版之间可能会有破坏性更改。因此，我们建议在composer.json文件中将包版本锁定到特定的测试版。这样，您可以每次都安装相同版本的软件包，除非您故意寻找最新的测试版。

我们强烈建议您密切关注您感兴趣的功能从测试版到稳定版的过渡，以便您可以从使用SDK的测试版切换到稳定版。

如果您的测试版功能需要发送EP-Version头部，请使用config对象的apiVersion属性来设置它

ExpressPayments::setApiVersion(ExpressPayments::getApiVersion() . '; feature_beta=v3');

支持

新功能和错误修复发布在ExpressPayments PHP库的最新主要版本上。如果您使用的是较旧的主要版本，我们建议您升级到最新版本，以使用新功能和错误修复，包括安全漏洞修复。该软件包的较旧主要版本将继续可用，但将不会收到任何更新。

开发

获取Composer。例如，在Mac OS上

brew install composer

安装依赖项

composer install

测试套件依赖于expresspayments-mock，因此请确保从后台终端获取并运行它（expresspayments-mock的README也包含通过Homebrew和其他方法安装的说明）

go install github.com/expresspayments/expresspayments-mock@latest
expresspayments-mock

按照上述说明安装依赖项（这将解决PHPUnit），然后您可以运行测试套件

./vendor/bin/phpunit

或者运行单个测试文件

./vendor/bin/phpunit tests/ExpressPayments/UtilTest.php

从Mozilla cURL发布更新捆绑的CA证书

./update_certs.php

该库使用PHP CS Fixer进行代码格式化。在提交PR之前，代码必须格式化，否则CI将失败。使用以下命令运行格式化工具

./vendor/bin/php-cs-fixer fix -v .

注意插件开发者

您正在编写一个集成ExpressPayments并嵌入我们库的插件吗？那么，请使用setAppInfo函数来识别您的插件。例如

\ExpressPayments\ExpressPayments::setAppInfo("MyAwesomePlugin", "1.2.34", "https://myawesomeplugin.info");

该方法应在发送任何请求到API之前调用一次。第二个和第三个参数是可选的。

SSL / TLS配置选项

请参阅上述“SSL / TLS兼容性问题”段落以获取完整上下文。如果您想确保您的插件可以在所有系统上使用，您应该添加一个配置选项，让用户可以选择CURLOPT_SSLVERSION的不同值：无（默认），CURL_SSLVERSION_TLSv1和CURL_SSLVERSION_TLSv1_2。

expresspayments / expresspayments-php

维护者

详细信息