README

您可以在 https://sierratecnologia.com.br 签署 SierraTecnologia 账户。

需求

PHP 5.4.0 及更高版本。

Composer

您可以通过 Composer 安装绑定。运行以下命令

composer require sierratecnologia/sierratecnologia-php

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

require_once('vendor/autoload.php');

手动安装

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

require_once('/path/to/sierratecnologia-php/init.php');

依赖项

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

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

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

入门指南

简单用法如下

\SierraTecnologia\SierraTecnologia::setApiKey('sk_test_BQokikJOvBiI2HlWgH4olfQ2');
$charge = \SierraTecnologia\Charge::create(['amount' => 2000, 'currency' => 'usd', 'source' => 'tok_189fqt2eZvKYlo2CTGBeg6Uq']);
echo $charge;

文档

请参阅 https://sierratecnologia.com.br/docs/api 以获取最新的文档。

旧版本支持

PHP 5.3

如果您正在使用 PHP 5.3，可以从我们的发行页面下载 v5.9.2（zip，tar.gz）。此版本将仍然与新版本的 SierraTecnologia API 一起使用，适用于所有常用功能。

PHP 5.2

如果您正在使用 PHP 5.2，可以从我们的发行页面下载 v1.18.0（zip，tar.gz）。此版本将仍然与新版本的 SierraTecnologia API 一起使用，适用于所有常用功能。

此旧版本可以通过 require_once("/path/to/sierratecnologia-php/lib/SierraTecnologia.php"); 包含，并像下面这样使用

SierraTecnologia::setApiKey('d8e8fca2dc0f896fd7cb4cb0031ba249');
$charge = SierraTecnologia_Charge::create(array('source' => 'tok_XXXXXXXX', 'amount' => 2000, 'currency' => 'usd'));
echo $charge;

自定义请求超时

注意：我们不推荐降低非只读调用（例如，创建费用）的超时时间，因为即使您本地超时，SierraTecnologia 端的请求仍然可以完成。如果您正在降低这些调用的超时时间，请确保使用幂等令牌以避免超时重试逻辑导致重复执行同一交易。

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

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

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

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

// use the SierraTecnologia API client as you normally would

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

需要为您的请求设置代理吗？在CurlClient构造函数中传递必要的CURLOPT_*数组，使用与curl_stopt_array()相同的语法。这将设置SDK执行的每个HTTP请求的默认cURL选项，尽管许多更常见的选项（例如超时；参见上方如何设置这些选项）将被客户端覆盖，即使在此处设置。

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

或者，可以向CurlClient构造函数传递一个可调用的函数，该函数根据请求输入返回上述数组。请参阅tests/CurlClientTest.php中的testDefaultOptions()示例。请注意，在发送请求之前，在每次API请求的开始时调用该可调用函数。

配置日志记录器

该库执行最小的日志记录，但它可以使用与PSR-3兼容的日志记录器进行配置，以便消息最终会出现在那里而不是error_log

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

访问响应数据

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

$charge = \SierraTecnologia\Charge::create(['amount' => 2000, 'currency' => 'usd', 'source' => 'tok_visa']);
echo $charge->getLastResponse()->headers['Request-Id'];

SSL / TLS兼容性问题

SierraTecnologia的API现在要求所有连接使用TLS 1.2。所有连接必须使用TLS 1.2。一些系统（特别是某些较旧的CentOS和RHEL版本）可以使用TLS 1.2，但默认使用TLS 1.0或1.1。在这种情况下，您将收到一个包含以下错误消息的invalid_request_error：“SierraTecnologia不再支持使用TLS 1.0制作的API请求。请使用TLS 1.2或更高版本的HTTPS连接。您可以在https://sierratecnologia.com.br/blog/upgrading-tls上了解更多信息。”。

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

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

按请求配置

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

\SierraTecnologia\Charge::all([], [
    'api_key' => 'sk_test_...',
    'sitecpayment_account' => 'acct_...'
]);

\SierraTecnologia\Charge::retrieve("ch_18atAXCdGbJFKhCuBAa4532Z", [
    'api_key' => 'sk_test_...',
    'sitecpayment_account' => 'acct_...'
]);

配置CA包

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

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

配置自动重试

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

\SierraTecnologia\SierraTecnologia::setMaxNetworkRetries(2);

为请求添加幂等性密钥，以保证重试是安全的。

开发

获取Composer。例如，在Mac OS上

brew install composer

安装依赖项

composer install

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

go get -u github.com/sierratecnologia/sierratecnologia-mock
sierratecnologia-mock

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

./vendor/bin/phpunit

或运行单个测试文件

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

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

./update_certs.php

注意插件开发者

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

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

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

SSL / TLS配置选项

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

sierratecnologia / payment-php

维护者

详细信息