README

Payyo PHP SDK 包含一个 API 客户端库

安装

composer require payyo/php-sdk

配置

创建客户端

此库使用 PSR-18 (psr/http-client), PSR-17 (psr/http-factory) 和 PSR-7 (psr/http-message)。

要创建客户端，您需要提供一个请求工厂 (\Psr\Http\Message\RequestFactoryInterface) 和一个 HTTP 客户端 (\Psr\Http\Client\ClientInterface) 实例。

为了使这部分更容易，SDK 使用 php-http/discovery 自动查找可用的 PSR-* 实现。

<?php
use Payyo\Sdk\ApiClient\Client;
use Payyo\Sdk\ApiClient\Credentials;

$credentials = new Credentials(
    getenv('API_PUBLIC_KEY'),
    getenv('API_SECRET_KEY')
);

$apiClient = new Client($credentials);

然而，如果您希望，也可以提供您自己的实例。

$httpClient = ...;      # \Psr\Http\Client\ClientInterface
$requestFactory = ...;  # \Psr\Http\Message\RequestFactoryInterface

$apiClient = new Client(
    $credentials,
    $httpClient,
    $requestFactory
);

API 版本

此 SDK 的当前版本针对 Payyo API 版本 3。版本可以通过 withVersion() 配置。

$apiClient = $apiClient->withVersion('2');

缓存客户端

对于缓存，您需要提供一个 PSR-16 (psr/simple-cache) 实例。

$cache = ...;  # \Psr\SimpleCache\CacheInterface
$ttl = 60;     # 1 minute

$apiClient = $apiClient->withCache($ttl, $cache);

// creating a new instance that caches for 2 minutes
$apiClient = $apiClient->withCache(180);

// creating a new instance that has caching disabled
$apiClient = $apiClient->withCache(false);

日志客户端

对于日志记录，您需要提供一个 PSR-3 (psr/log) 实例。

$logger = ...;  # \Psr\LoggerInterface    
$apiClient = $apiClient->withLogger($logger);

使用方法

启动交易

$response = $apiClient->transaction()->initiate([
    'merchant_id'        => 123456, // use your merchant ID
    'merchant_reference' => 'test_order',
    'description'        => 'City Sightseeing',
    'currency'           => 'USD',
    'amount'             => 3000,   // => $30
    'return_urls' => [
        'success' => 'https://example.org/success',
        'fail'    => 'https://example.org/fail',
        'abort'   => 'https://example.org/abort',
    ],
    'funding_instrument' => [
        'type'    => 'credit_card',
        'number'  => '4242 4242 4242 4200',
        'expires' => '2024-04',
        'cvc'     => '123',
        'holder'  => 'John Doe',
    ]
]);

handleResponse($response);

// ---

function handleResponse(Response $response): void {
    $transactionId = $response->getValue('result.transaction_id');
    
    switch ($response->getValue('result.next_action')) {
        case 'redirect':
            $redirectUrl = $response->getValue('result.redirect_url');
            // redirect to $redirectUrl for payment authentication ...
            break;
        case 'capture':
            $captureResponse = $apiClient->transaction()->capture($transactionId);
            handleResponse($captureResponse);
            break;
        case 'wait_for_webhook':
            // -> finish order, payment pending
            break;
        case 'none':
            // -> finish order, payment complete
            break;
    }
}

检索交易的下一步行动

$response = $apiClient->transaction()->getNextAction($transactionId);
$transaction = $response->getValue('result');

var_dump(
    $transaction['status'],
    $response->getValue('result.status')
);

检索交易详情

$response = $apiClient->transaction()->getDetails($transactionId);

$nextAction = $response->getValue('result.next_action');
// See example above with "handleResponse()"

缓存请求

$apiClientThatCachesForOneMinute = $apiClient->withCache(60);
$response = $apiClientThatCachesForOneMinute->transaction()->getDetails($transactionId);

内置 RPC 方法

以下方法目前受支持

$this->client->transaction()->getDccQuote(array $params);
$this->client->transaction()->initiate(array $params);
$this->client->transaction()->getNextAction(string $transactionId);
$this->client->transaction()->void(string $transactionId);
$this->client->transaction()->capture(string $transactionId, array $params);
$this->client->transaction()->reverse(string $transactionId, array $params);
$this->client->transaction()->abort(string $transactionId);
$this->client->transaction()->getDetails(string $transactionId, array $params);

$this->client->transactions()->search(int|int[] $merchantIds, array $params);
$this->client->transactions()->getStats(int|int[] $merchantIds, array $params);

$this->client->paymentPage()->initialize(array $params);
$this->client->paymentPage()->getDetails(string $paymentPageId, array $params);
$this->client->paymentPage()->search(int|int[] $merchantIds, array $params);

您也可以使用 request() 方法调用其他 RPC 方法。

$this->client->request(string $method, array $params);

贡献

所有贡献都欢迎通过拉取请求。

请在提交之前运行测试 (vendor/bin/phpunit) 和编码风格修复器 (composer run-cs-fixer)。

许可证

MIT。请参阅 LICENSE 文件。