README

官方PHP Covery客户端

如何开始
基本集成
内部结构
变更日志

如何开始

您需要获取一个访问令牌和一个密钥
使用composer安装客户端: composer require "covery/client=^1.0.0"

基本集成

首先，您需要用凭证和传输初始化Facade。为此，请将以下代码放置在应用程序初始化附近的位置

use Covery\Client\Facade;
use Covery\Client\Transport\Curl;

$connectTimeoutSeconds = 5.0;
$requestTimeoutSeconds = 2.0;
Facade::setTransport(new Curl($connectTimeoutSeconds, $requestTimeoutSeconds));
Facade::setCredentials('<token>', '<secret>');

可选（仅用于调试）

use Covery\Client\Loggers\FileLogger;

//directory must be writable!
$filePath = "path_to_file/error.log";

Facade::setLogger(new FileLogger($filePath));

这就完成了！

完成此过程后，您现在可以使用Facade::sendEvent、Facade::sendPostback、Facade::makeDecision来查询Covery。

登录事件示例

use Covery\Client\Envelopes\Builder;
use Covery\Client\Facade;
use Covery\Client\Identities\Stub;

$event = Builder::loginEvent(md5($userId), string($userId), time(), 'foo@bar.com', false) // Using builder
    ->addIdentity(new Stub())                                                             // stub identity
    ->build();                                                                            // building envelope

$result = Facade::makeDecision($event);
if ($result->isReject()) {
    // ...
}

Postback事件示例

use Covery\Client\Envelopes\Builder;
use Covery\Client\Facade;

$event = Builder::postbackEvent($requestId, null, 'code', 'reason')->build(); //postback for event with id $requestId
$postbackRequestId = Facade::sendPostback($event);

KycProof事件示例

use Covery\Client\Envelopes\Builder;
use Covery\Client\Facade;

$event = Builder::kycProofEvent($kycStartId)->build();
$kycProofData = Facade::sendKycProof($event);

卡ID事件示例

use Covery\Client\CardId\Builder;
use Covery\Client\Facade;

$event = Builder::cardIdEvent('curdNumber')->build();
$result = Facade::sendCardId($event);

文档存储事件示例

use Covery\Client\DocumentStorage\Builder;
use Covery\Client\Facade;

$event = Builder::documentStorageEvent(\Covery\Client\ContentType::JPEG, \Covery\Client\ContentDescription::GENERAL_DOCUMENT, null, false)->build();
$result = Facade::sendDocumentStorage($event);

附件文档连接事件示例

use Covery\Client\DocumentConnection\Builder;
use Covery\Client\Facade;

$event = Builder::documentConnectionEvent(1, [1])->build();
$result = Facade::attachDocumentConnection($event);

解除文档连接事件示例

use Covery\Client\DocumentConnection\Builder;
use Covery\Client\Facade;

$event = Builder::documentConnectionEvent(1, [1])->build();
$result = Facade::detachDocumentConnection($event);

文档文件上传示例

use Covery\Client\Facade;

$stream = fopen('PATH_TO_FILE', 'r');
$documentUrl = 'UPLOAD_URL'; //URL from Covery
$documentFileUploader = \Covery\Client\DocumentFileUploader\Builder::documentFileUploaderEvent(
    $documentUrl,
    $stream
)->build();

$result = \Covery\Client\Facade::uploadDocumentFile($documentFileUploader);

账户配置状态事件示例

use Covery\Client\Facade;

$accountConfigurationStatus = Facade::getAccountConfigurationStatus();

技术细节

外观

Covery\Client\Facade是Covery\Client\PublicAPIClient的静态包装器。如果您使用依赖注入或其他应用程序组装机制，您可能更愿意不使用Facade，而是直接使用客户端。

PSR-3、PSR-4和PSR-7

Covery客户端支持PSR-3日志记录器。您可以通过调用Facade::setLogger将它们分配给Facade，或将日志记录器作为构造函数参数传递给PublicAPIClient。
Covery客户端代码使用PSR-4自动加载器。只需require /vendor/autoload.php。
HTTP通信使用PSR-7 HTTP消息，因此您可以按需扩展客户端的功能。

传输方式

Covery客户端可以使用任何满足Covery\Client\TransportInterface的类来发送请求。Covery客户端附带两个主要实现

Covery\Client\Transport\Curl - 简单的PHP curl实现
Covery\Client\Transport\OverGuzzle - 基于Guzzle HTTP客户端的适配器

信封

sendEvent和makeDecision方法需要信封作为参数。信封是一组以下数据

SequenceID - 事件分组标识符。Covery将尝试使用此字段来分组事件。建议使用userID作为序列ID。然而，Covery要求此字段为长字符串（6-40个字符），因此您可以使用md5($userId)作为SequenceID以获得更好的结果。
Identities - 此事件所属的身份列表。在大多数情况下，单个Identities\Stub就足够了。
Type - 事件类型，以下之一
- install - 安装事件
- registration - 注册事件
- confirmation - 注册确认事件，必须与注册事件具有相同的SequenceID
- login - 登录事件，必须与注册事件具有相同的SequenceID
- transaction - 支付事件，必须与注册和登录事件具有相同的SequenceID
- refund - 退款事件
- payout - 支付事件
- transfer - 转账事件
- kyc_profile - kyc配置文件事件
- kyc_submit - kyc提交事件
- order_item - 订单项目事件
- order_submit - 订单提交事件
- document - 文档事件

信封规范包含在Covery\Client\EnvelopeInterface中。

您可以将以下内容作为信封提供

对 EnvelopeInterface 的自定义实现。例如，您的支付订单模型可以扩展以实现 EnvelopeInterface，然后您可以直接将其传递给 sendEvent 和/或 makeDecision。
自定义构建的 Covery\Client\Envelopes\Envelope
使用 Covery\Client\Envelopes\Builder 构建的信封（别忘了调用 build()！）

结果

sendEvent 将返回包含 Covery 侧存储实体 ID 的 integer（可能是 x64）。您应该记录它。
makeDecision 将返回 Covery\Client\Result 对象
- 调用 getScore() 获取范围 [-100, 100] 内的分数
- 方法 isAccept() 如果 Covery 在传入的信封数据中未发现欺诈，将返回 true
- 方法 isReject() 如果 Covery 在传入的信封数据中发现欺诈，将返回 true

异常树

Covery\Client\Exception - 基础异常
- Covery\Client\EnvelopeValidationException - 如果信封在客户端验证失败时抛出
- Covery\Client\DeliveredException - 为 Covery 服务器传递的异常
  - Covery\Client\AuthException - 授权异常
- Covery\Client\IoException - 服务器通信错误
  - Covery\Client\TimeoutException - 超时

错误记录器

\Covery\Client\Loggers\VarDumpLogger - 简单的 var_dump 记录器
\Covery\Client\Loggers\FileLogger - 将错误写入文件
您还可以编写自己的从 AbstractLogger 扩展的记录器类

变更日志

1.4.0
- 从 postback 事件中删除了 transaction_id 字段
- 将 MediaStorage 方法重命名为 DocumentMethod
- 将 MediaConnection 方法重命名为 DocumentConnection
- 将 UploadMediaFile 方法重命名为 DocumentMediaFile。
- 将 media_id 字段重命名为 document_id
- 为 postback 事件添加了可选的 merchant_advice_code 和 merchant_advice_text 字段
- 为 kyc_submit、profile_update 事件添加了可选的 anonymous 字段
- 将 plugins 字段的长度字段更改为 8192
- 引入了新的 document 事件
- 修改了旧测试
1.3.14 添加了 MediaStorage 方法。添加了 MediaConnection 方法。添加了 UploadMediaFile 方法。
- 为以下事件添加了可选的 media_id 字段：install、registration、confirmation、login、order-item、order-submit、transaction、refund、payout、transfer、profile-update、kyc-profile、kyc-submit。
- 为 KYC 配置文件和 KYC 提交事件添加了可选的 address_confirmed、second_address_confirmed 字段。
- 添加了 AccountConfigurationStatus 方法。
- 删除了健康检查方法。
1.3.13 添加了 StaleDataException 异常
1.3.12 添加了 sendCardId 方法
1.3.11 添加了 VarDumpLogger 和 FileLogger
1.3.10
- 移除了请求中自定义字段数量的限制
1.3.9
- 为 kyc_submit 事件添加了可选的 provider_id、profile_id、profile_type、profile_sub_type、firstname、lastname、fullname、gender、industry、wallet_type、website_url、description、employment_status、source_of_funds、birth_date、reg_date、issue_date、expiry_date、reg_number、vat_number、email、email_confirmed、phone、phone_confirmed、contact_email、contact_phone、country、state、city、address、zip、nationality、second_country、second_state、second_city、second_address、second_zip、ajax_validation、cookie_enabled、cpu_class、device_fingerprint、device_id、do_not_track、ip、real_ip、local_ip_list、language、languages、language_browser、language_user、language_system、os、screen_resolution、screen_orientation、client_resolution、timezone_offset、user_agent、plugins、referer_url、origin_url 字段。
1.3.8
- 为 transaction、refund、payout、transfer、profile_update、kyc_profile 和 kyc_submit 事件添加了可选的 links_to_documents 字段
1.3.7
- 添加了 profile_update 事件
1.3.6
- 为 kyc_start 事件添加了可选的 allowed_document_format 字段
1.3.5
- 为 transfer 事件添加了可选的 second_user_merchant_id 字段
1.3.4
- 为 kyc_start 事件添加了可选的 number_of_documents 字段。
- 添加了 kyc_proof 事件。
1.3.3
- 为 kyc_profile 事件添加了可选的 provider_id、contact_email、contact_phone、wallet_type、nationality、final_beneficiary、employment_status、source_of_funds、issue_date、expiry_date、gender 字段。
- 添加了 kyc_start 事件。
1.3.2
- 为交易事件添加了可选的 merchant_country、mcc、acquirer_merchant_id 字段。为安装、注册、确认、登录、交易、退款、支付和转账事件添加了可选的 group_id 字段。
1.3.1
- 添加了 order_item、order_submit 事件。为转账事件添加了可选的 transfer_source 字段。
1.3.0
- 为登录、注册、安装和交易事件添加了可选的 campaign 字段。
1.2.0
- 添加了对请求超时的支持。
1.1.9
- 为转账事件添加了可选的 bic 字段。
1.1.8
- 在请求路径前添加了斜杠（自 1.4 版本起 guzzle 弃用）。
1.1.7
- 添加了 kyc_profile、kyc_submit 事件。
1.1.6
- 添加了决策响应字段：type、createdAt、sequenceId、merchantUserId、reason、action 和自定义响应。
1.1.5
- 将 postback 请求的 request_id 变更类型为 int。
1.1.4
- 对空 postback 响应进行了错误处理。
1.1.3
- 带有 request_id 或 transaction_id 的 postback 请求。
1.1.2
- 添加了 sendPostback 方法以发送 postback 事件。
1.1.1
- 为登录、注册事件添加了可选的 password。
- 为转账事件添加了可选的 iban、second_iban。
1.1.0
- 为浏览器数据添加了可选的 local_ip_list、plugins、referer_url、origin_url、client_resolution。
- 为退款事件添加了可选的 email、phone、user_merchant_id。
1.0.9
- 引入了新的 transfer 事件。
1.0.8
- 为登录事件添加了可选的 traffic_source 和 affiliate_id。
1.0.7
- 修复了自定义字段验证。
1.0.6
- 更新了字符串验证。
1.0.5
- 引入了新的 postback 事件。
- 为登录事件添加了可选的 gender。
- 为支付事件添加了可选的 payout_account_id。
- 将 payout_card_id、payout_ammount_converted 移至支付事件的可选字段。
- 为交易事件添加了可选的 affiliate_id。
- 为退款事件添加了可选的 refund_method、refund_system、refund_mid。
- 将 device_id 添加到所有数据包。
- 添加了 postback 事件的测试。
- 修改了旧的测试。
1.0.4
- 引入了新的 install、refund 事件。
- 将 transaction_mode 移至交易事件的可选字段。
- 为交易事件添加了必填的 user_merchant_id。
- 为 install、refund、transaction 事件添加了测试。
- 修复了支付测试。
1.0.3
- 引入了新的 payout 事件。
- 身份节点现在是可选的。
- 为工作者引入了新的实验性 PersistentCurl 传输。
修复了 1.0.2 版本的 cURL 问题，状态码为 100。
1.0.1
- 将可选的 email 和 phone 添加到确认事件。
- 向所有数据包添加了更多可选字段：ajax_validation、cookie_enabled、cpu_class、device_fingerprint、do_not_track、ip、language、language_browser、language_system、language_user、languages、os、real_ip、screen_orientation、screen_resolution、timezone_offset、user_agent。
1.0.0 - 发布

covery / client

维护者

详情