README

文档：https://kassa.com/help/

要求

PHP 5.5 及以上版本。

依赖项

为了正常工作，绑定需要以下扩展

• curl，尽管你可以选择使用自己的非cURL客户端。
• json
• mbstring（多字节字符串）
• php-fig/log
• guzzlehttp/psr7

可选

• guzzlehttp/guzzle，用于使用guzzle代替cURL。

Composer

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

composer require kassacom/php-sdk

要使用绑定，请使用Composer的 autoload

require_once('vendor/autoload.php');

如果您使用Composer，这些依赖项应该会自动处理。

入门

我们建议使用GuzzleHttp客户端

初始化客户端

$guzzleClient = new GuzzleHttp\Client();
$transport = new KassaCom\SDK\Transport\GuzzleApiTransport($guzzleClient);
$client = new KassaCom\SDK\Client($transport);
$client->setAuth('login', 'secret'); // or for basic authorization $client->setAuth('login', 'password', KassaCom\SDK\Transport\Authorization\BasicAuthorization::class);

所有请求都按照类似的步骤处理

1. 创建 KassaCom\SDK\Model\Request\AbstractRequest 的请求实例
2. 请求序列化
3. 向服务器发送请求
4. 您将获得一个 KassaCom\SDK\Model\Response\AbstractResponse 响应对象实例，或者在请求失败时抛出异常

所有请求都可以通过合适的对象创建，或者基于数组、整数和字符串创建

创建支付

使用对象创建请求

// Create a request object
$createPaymentRequest = new KassaCom\SDK\Model\Request\Payment\CreatePaymentRequest();

// Set up $createPaymentRequest with required params

try {
    /** @var KassaCom\SDK\Model\Response\Payment\CreatePaymentResponse $createPaymentResponse */
    $createPaymentResponse = $client->createPayment($createPaymentRequest);
} catch (\Exception $e) {
    // ...
}

或者您可以使用数组创建请求

$requestArray = [
    'order' => [/*...*/],
    'settings' => [/*...*/],
    'custom_parameters' => [/*...*/],
    'receipt' => [/*...*/],
];

try {
    /** @var KassaCom\SDK\Model\Response\Payment\CreatePaymentResponse $createPaymentResponse */
    $createPaymentResponse = $client->createPayment($requestArray);
} catch (\Exception $e) {
    // ...
}

处理支付

使用对象创建请求

// Create a request object
$processPayment = new KassaCom\SDK\Model\Request\Payment\ProcessPaymentRequest();

// Set up $processPayment with required params

try {
    /** @var KassaCom\SDK\Model\Response\Payment\ProcessPaymentResponse $processPaymentResponse */
    $processPaymentResponse = $client->processPayment($processPayment);
} catch (\Exception $e) {
    // ...
}

或者您可以使用数组创建请求

$requestArray = [
    'token' => 'token',
    'ip' => '127.0.0.1',
    'payment_method_data' => [/*...*/],
];

try {
    /** @var KassaCom\SDK\Model\Response\Payment\ProcessPaymentResponse $processPaymentResponse */
    $processPaymentResponse = $client->processPayment($requestArray);
} catch (\Exception $e) {
    // ...
}

捕获支付

使用对象创建请求

// Create a request object
$capturePaymentRequest = new KassaCom\SDK\Model\Request\Payment\CapturePaymentRequest('token-string-from-create-payment-step');

try {
    /** @var KassaCom\SDK\Model\Response\Payment\CapturePaymentResponse $capturePaymentResponse */
    $capturePaymentResponse = $client->capturePayment($capturePaymentRequest);
} catch (\Exception $e) {
    // ...
}

或者您可以使用token创建请求

try {
    /** @var KassaCom\SDK\Model\Response\Payment\CapturePaymentResponse $capturePaymentResponse */
    $processPaymentResponse = $client->processPayment('token-string-from-create-payment-step');
} catch (\Exception $e) {
    // ...
}

获取支付信息

使用对象创建请求

// Create a request object
$getPaymentRequest = new KassaCom\SDK\Model\Request\Payment\GetPaymentRequest('token-string-from-create-payment-step');

try {
    /** @var KassaCom\SDK\Model\Response\Payment\GetPaymentResponse $getPaymentResponse */
    $getPaymentResponse = $client->getPayment($getPaymentRequest);
} catch (\Exception $e) {
    // ...
}

或者您可以使用token创建请求

try {
    /** @var KassaCom\SDK\Model\Response\Payment\GetPaymentResponse $getPaymentResponse */
    $getPaymentResponse = $client->getPayment('token-string-from-create-payment-step');
} catch (\Exception $e) {
    // ...
}

取消支付

使用对象创建请求

// Create a request object
$cancelPaymentRequest = new KassaCom\SDK\Model\Request\Payment\CancelPaymentRequest('token-string-from-create-payment-step');

try {
    /** @var KassaCom\SDK\Model\Response\Payment\CancelPaymentResponse $cancelPaymentResponse */
    $cancelPaymentResponse = $client->cancelPayment($cancelPaymentRequest);
} catch (\Exception $e) {
    // ...
}

或者您可以使用token创建请求

try {
    /** @var KassaCom\SDK\Model\Response\Payment\CancelPaymentResponse $cancelPaymentResponse */
    $cancelPaymentResponse = $client->cancelPayment('token-string-from-create-payment-step');
} catch (\Exception $e) {
    // ...
}

创建退款

使用对象创建请求

// Create a request object
$createPayoutRequest = new KassaCom\SDK\Model\Request\Payout\CreatePayoutRequest();

// Set up $createPayoutRequest with required params

try {
    /** @var KassaCom\SDK\Model\Response\Payout\CreatePayoutResponse $createPayoutResponse */
    $createPayoutResponse = $client->createPayout($createPayoutRequest);
} catch (\Exception $e) {
    // ...
}

或者您可以使用数组创建请求

$requestArray = [
    'transaction_id' => 'transaction_id',
    'wallet_id' => 123,
    'fee_type' => 'fee_type',
    'payout_method_data' => [/*...*/],
    'order' => [/*...*/],
];

try {
    /** @var KassaCom\SDK\Model\Response\Payout\CreatePayoutResponse $createPayoutResponse */
    $createPayoutResponse = $client->createPayout($requestArray);
} catch (\Exception $e) {
    // ...
}

获取退款信息

使用对象创建请求

// Create a request object
$getPayoutRequest = new KassaCom\SDK\Model\Request\Payout\GetPayoutRequest();

// Set up $getPayoutRequest with required params

try {
    /** @var KassaCom\SDK\Model\Response\Payout\GetPayoutResponse $getPayoutResponse */
    $getPayoutResponse = $client->getPayout($getPayoutRequest);
} catch (\Exception $e) {
    // ...
}

或者您可以使用数组创建请求

$requestArray = [
    'transaction_id' => 'transaction_id',
    'wallet_id' => 123,
];

try {
    /** @var KassaCom\SDK\Model\Response\Payout\GetPayoutResponse $getPayoutResponse */
    $getPayoutResponse = $client->getPayout($requestArray);
} catch (\Exception $e) {
    // ...
}

或者通过ID创建

try {
    /** @var KassaCom\SDK\Model\Response\Payout\GetPayoutResponse $getPayoutResponse */
    $getPayoutResponse = $client->getPayout(123);
} catch (\Exception $e) {
    // ...
}

支付报告

下载报告文件

$paymentsReport = new KassaCom\SDK\Model\Request\Reports\PaymentsReportRequest();
$paymentsReport->setDatetimeFrom(new \DateTime('2 weeks ago'))
            ->setDatetimeTo(new \DateTime());

$response = $client->getPaymentsReport($paymentsReport);

http_response_code($response->getStatusCode());
$stream = $response->getBody();

foreach ($response->getHeaders() as $key => $header) {
    header($key . ': ' . join(',', $header));
}

echo $stream->getContents();

退款报告

下载报告文件

$payoutsReportRequest = new KassaCom\SDK\Model\Request\Reports\PayoutsReportRequest();
$payoutsReportRequest->setDatetimeFrom(new \DateTime('2 weeks ago'))
            ->setDatetimeTo(new \DateTime());

$response = $client->getPayoutsReport($payoutsReportRequest);

http_response_code($response->getStatusCode());
$stream = $response->getBody();

foreach ($response->getHeaders() as $key => $header) {
    header($key . ': ' . join(',', $header));
}

echo $stream->getContents();

异常

• KassaCom\SDK\Exception\TransportException - 在API传输错误的情况下抛出。例如，当未提供授权数据时。
• KassaCom\SDK\Exception\JsonParseException - 服务器响应不包含有效的JSON。
• KassaCom\SDK\Exception\ServerResponse\ResponseException - 4xx和5xx服务器错误。
• KassaCom\SDK\Exception\Response\ResponseParseException - 创建响应错误。
• KassaCom\SDK\Exception\Request\RequestParseException - 创建请求错误。

处理来自服务器的通知

此代码负责处理支付结果。您需要创建处理器，使其在您的应用程序的URL上可用，并在 kassa.com 中的项目设置中指定URL。此处理器将在用户在kassa.com表单上完成支付后调用

$notification = new Notification();
$notification->setApiKey('api-key');
$notification->process();

您可以使用手动响应向服务器发送响应

$notification->process(false);

// if success
$notification->successResponse();
// if error
$notification->errorResponse('Error message');

如果您使用代理服务器，您可以跳过IP检查

$notification->setSkipIpCheck();

自定义Api传输

您可以通过扩展 KassaCom\SDK\Transport\AbstractApiTransport 创建自己的API传输

class MyApiTransport extends AbstractApiTransport {
    protected function sendRequest(Psr7\Request $request) {
        // Implementing the sendRequest() method
    }
}