README

Compayer 是一个统计数据预处理和网页分析服务，它跟踪支付表单中的客户事件，用于金融和营销报告。

Compayer PHP SDK 库设计用于将统计消息从基于 PHP 的项目中推送到 Compayer 分析。

特性

• 创建并发送开始、成功、失败或退款支付的 Events 到 Compare 分析。
• 帮助将 Yandex.Money、Xsolla 和 PaySuper 等支付系统的响应消息转换为 Event 消息。

目录

• 要求
• 入门
• 安装
• 使用方法

要求

• PHP >= 5.5
• 所需的 PHP 扩展：json

入门

在 Compayer 分析中注册您的账户以获取

• 客户端 ID（您的客户端的唯一标识符）
• 密钥（您的客户端的秘密 API 密钥）

安装

我们建议使用 Composer 安装 Compayer PHP SDK。

$ cd /path/to/your/project
$ composer require compayer/compayer-lib-php

安装后，您需要引入 Composer 的自动加载器

require '/path/to/vendor/autoload.php';

使用方法

要使用分析，您需要发送 2 个事件

• 当用户开始支付时，发送 start 事件。 start 事件是可选的，但我们强烈建议使用它来跟踪整个支付链。
• 在支付系统响应操作结果（成功、失败或退款）后，发送一个 success、fail 或 refund 事件。

事件将自动根据服务器请求的数据确定用户的 IP 地址和支付开始页面的地址。如果用户的请求对脚本不可用，您可以自行设置支付开始页面或用户 IP 地址（这对于地理位置过滤器正常工作是必要的）。

要发送 start 事件，请使用以下示例

use Compayer\SDK\Client;
use Compayer\SDK\Config;
use Compayer\SDK\Event;
use Compayer\SDK\Exceptions\SdkException;

const CLIENT_ID = 'client_id';
const SECRET_KEY = 'secret_key';

// Create and configure a configuration object (including debug mode).
$config = new Config(CLIENT_ID, SECRET_KEY);
$config->setDebugMode(true);

// Create an SDK client for sending events.
$client = new Client($config);

// Create an instance of the Event class and set the maximum possible properties about a user and payment.
// All fields are optional, but it's important to fill out one of the fields: "userEmails", "userPhones" or "userAccounts" 
// to identify the user made the payment.
$event = (new Event())
    ->setMerchantTransactionId('12345')
    ->setPaymentAmount(250.50)
    ->setPaymentCurrency('RUB')
    ->setUserLang('RUS')
    ->setUserEmails(['customer@compayer.com'])
    ->setUserAccounts(['54321'])
    ->setExtra(['my_property' => 'value']);

// You can also create an object with an event from an array, 
// where names of the keys of the array match names of the Event properties.
$event = Event::fromArray([
    'merchantTransactionId' => '12345',
    'paymentAmount' => 250.50,
    'paymentCurrency' => 'RUB',
    'userLang' => 'RUS',
    'userEmails' => ['customer@compayer.com'],
    'userAccounts' => ['54321'],
    'extra' => ['my_property' => 'value'],
]);

try {
    // Send the generated event and get the response message with a transaction identifier and log.
    $response = $client->pushStartEvent($event);
} catch (SdkException $e) {
    print_r($e->getMessage());
}

// Use it to send "success", "fail" or "refund" events and to chain events.
// The transaction identifier is UUID string like 3677eb06-1a9a-4b6c-9d6a-1799cae1b6bb.
$transactionId = $response->getTransactionId();

// Show logs with the debug mode configuration.
print_r($response->getLog());

在支付系统收到关于支付结果的响应（成功、失败或退款）后，您需要发送一个包含支付后接收到的数据的 Event。您可以按照 Event start 中描述的方式构建响应事件。如果您在开始步骤收到交易 ID，将其设置为链接整个支付链。

对于 success、failure 或 refund 事件，需要支付系统的原始响应。响应应以具有“response”键的字符串形式编写在 extra 属性中。

例如，如果收到的答案是 JSON 格式，则使用以下构造： setPaymentSystemResponse(json_encode($jsonPaymentSystemResponse))。

use Compayer\SDK\Client;
use Compayer\SDK\Config;
use Compayer\SDK\Event;
use Compayer\SDK\Exceptions\SdkException;

const CLIENT_ID = 'client_id';
const SECRET_KEY = 'secret_key';

// Create and configure a configuration object (e.g. with debug mode).
$config = new Config(CLIENT_ID, SECRET_KEY);
$config->setDebugMode(true);

// Create SDK client for sending events.
$client = new Client($config);

// Transaction ID received on start event
$transactionId = '3677eb06-1a9a-4b6c-9d6a-1799cae1b6bb';

// Create an instance of the Event class and set the maximum possible properties about the user and payment
// All fields are optional, but you must fill out one of the fields: "userEmails", "userPhones" or "userAccounts" 
// to identify the user who made the payment. If you have a transaction ID for the start event, specify it.
$event = (new Event())
    ->setTransactionId($transactionId)
    ->setMerchantTransactionId('12345')
    ->setPaymentAmount(250.50)
    ->setPaymentCurrency('RUB')
    ->setPayoutAmount(3.87)
    ->setPayoutCurrency('USD')
    ->setUserEmails(['customer@compayer.com'])
    ->setUserAccounts(['54321'])
    ->setExtra(['my_property' => 'value'])
    ->setPaymentSystemResponse('Payment system response as a string');

try {
    // Send the generated event
    // Or use $client->pushFailEvent($event) in case of payment failure
    // Or use $client->pushRefundEvent($event) in case of payment refund
    $client->pushSuccessEvent($event);
} catch (SdkException $e) {
    print_r($e->getMessage());
}

许可证

该项目在 MIT 许可证 的条款下作为开源软件提供。