covery/client

Covery official client

Covery Client

, _(*1)

Official PHP Covery Client, _(*2)

• How to Start
• Basic Integration
• Internals
  • Facade
  • PSR-3 logging PSR-4 autoloading and PSR-7 HTTP messages
  • Transports
  • Envelopes
  • Results
  • Exceptions
  • Error loggers
• Changelog

, _(*3)

How to Start

1. You need to acquire an access token and a secret
2. Install a client using composer: composer require "covery/client=^1.0.0"

, _(*4)

Basic Integration

The first thing you need is to initialize Facade with credentials and transport. To do this, place the following code somewhere close to your application initialization:, _(*5)

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>');

Optional (use only for debug):, _(*6)

use Covery\Client\Loggers\FileLogger;

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

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

That's all!, _(*7)

Having completed this procedure, you can now query Covery using Facade::sendEvent, Facade::sendPostback, Facade::makeDecision., _(*8)

Login event example:, _(*9)

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 event example:, _(*10)

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 event example:, _(*11)

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

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

Card Id event example:, _(*12)

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

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

Document Storage event example:, _(*13)

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);

Attach document connection event example:, _(*14)

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

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

Detach document connection event example:, _(*15)

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

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

Document file upload example:, _(*16)

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);

Account Configuration Status event example:, _(*17)

use Covery\Client\Facade;

$accountConfigurationStatus = Facade::getAccountConfigurationStatus();

Tech Details

, _(*18)

Facade

Covery\Client\Facade is a static wrapper over Covery\Client\PublicAPIClient. If you use dependency injection or other application assembly mechanism, you may prefer not to use Facade, and rather use the client directly., _(*19)

, _(*20)

PSR-3, PSR-4 and PSR7

1. Covery client supports PSR-3 loggers. You may assign them to Facade calling Facade::setLogger or to PublicAPIClient passing a logger as a constructor argument.
2. Covery client code uses PSR-4 autoloader. Just require /vendor/autoload.php.
3. HTTP communication uses PSR-7 HTTP message, so you may extend the client's capabilities as you see fit.

, _(*21)

Transports

Covery client may use any class that satisfies Covery\Client\TransportInterface to send requests. Covery client ships with two major implementations:, _(*22)

1. Covery\Client\Transport\Curl - simple PHP curl implementation
2. Covery\Client\Transport\OverGuzzle - adapter over Guzzle HTTP client

, _(*23)

Envelopes

Methods sendEvent and makeDecision require envelope as argument. Envelope is a pack of following data:, _(*24)

• SequenceID - Event grouping identifier. Covery will attempt to group events using this field. It is recommended to use userID as a sequence ID. However, Covery requires a long string (6-40 characters) in this field, so you may use md5($userId) as SequenceID for better results.
• Identities - List of identities this event belongs to. For most cases a single Identities\Stub is enough.
• Type - Event type, one of:
  • install - install event
  • registration - registration event
  • confirmation - registration confirmation event, must have the same SequenceID with registration event
  • login - login event, must have the same SequenceID with registration event
  • transaction - payment event, must have the same SequenceID with registration and login events
  • refund - refund event
  • payout - payout event
  • transfer - transfer event
  • kyc_profile - kyc profile event
  • kyc_submit - kyc submit event
  • order_item - order item event
  • order_submit - order submit event
  • document - document event

Envelope specifications are bundled in Covery\Client\EnvelopeInterface., _(*25)

You may provide the following as envelopes:, _(*26)

1. Own implementations of EnvelopeInterface. For example, your own payment order model may be extended to implement EnvelopeInterface, then you may pass it to sendEvent and/or makeDecision directly.
2. Custom-built Covery\Client\Envelopes\Envelope
3. Envelopes built using Covery\Client\Envelopes\Builder (don't forget to invoke build()!)

, _(*27)

Results

1. sendEvent will return integer (may be x64) containing ID of a stored entity on Covery side. You should log it.
2. makeDecision will return Covery\Client\Result object:
   • Call getScore() to obtain score in range [-100, 100]
   • Method isAccept() will return true if Covery did not found fraud in incoming envelope data
   • Method isReject() will return true if Covery found fraud in incoming envelope data

, _(*28)

Exception Tree

• Covery\Client\Exception - base exception
  • Covery\Client\EnvelopeValidationException - thrown if envelope failed client side validation
  • Covery\Client\DeliveredException - exception delivered for Covery server
  • Covery\Client\AuthException - authorization exception
  • Covery\Client\IoException - server communication error
  • Covery\Client\TimeoutException - timeout

, _(*29)

Error loggers

• \Covery\Client\Loggers\VarDumpLogger - simple var_dump logger
• \Covery\Client\Loggers\FileLogger - writing errors to a file
• You can also write your own logger class extended from AbstractLogger

, _(*30)

Changelog

• 1.5.2
  • Fixed validation of second_user_merchant_id field for the "Transfer" event
• 1.5.1
  • Change the data type of the field language_browser from string(255) to string(1024)
  • Change the data type of the field product_quantity from int to float for the "Order Item" event
  • Add the possibility to send zero in the following fields: amount, amount_converted, shipping_fee, shipping_fee_converted,
    source_fee, source_fee_converted, tax_fee, tax_fee_converted,
    transaction_amount, transaction_amount_converted, refund_amount, refund_amount_converted,
    payout_amount, payout_amount_converted, one_operation_limit,
    daily_limit, weekly_limit, monthly_limit, annual_limit
• 1.5.0
  • The minimum PHP version has been changed from 5.4 to 7.3.
  • Packages have been updated.
  • Old tests modified
• 1.4.1
  • Added optional mrz_authority and mrz_issue_date fields for document event
• 1.4.0
  • Removed transaction_id field from postback event
  • Renamed MediaStorage method to DocumentMethod
  • Renamed MediaConnection method to DocumentConnection
  • Renamed UploadMediaFile method to DocumentMediaFile.
  • Renamed media_id field to document_id
  • Added optional merchant_advice_code and merchant_advice_text fields for postback event
  • Added optional anonymous field for kyc_submit, profile_update events
  • Changed length field plugins to 8192
  • New document event introduced
  • Old tests modified
• 1.3.14 Added MediaStorage method. Added MediaConnection method. Added UploadMediaFile method.
  • Added optional media_id field for events: install, registration, confirmation, login, order-item, order-submit, transaction, refund, payout, transfer, profile-update, kyc-profile, kyc-submit.
  • Added optional address_confirmed, second_address_confirmed fields for KYC profile and KYC submit events.
  • Added AccountConfigurationStatus method.
  • Removed Health check method.
• 1.3.13 Added StaleDataException exception
• 1.3.12 Added sendCardId method
• 1.3.11 Added VarDumpLogger and FileLogger
• 1.3.10
  • Removed the limit on the number of custom fields in the request
• 1.3.9
  • Added optional 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 fields for kyc_submit event.
• 1.3.8
  • Added optional links_to_documents field for transaction, refund, payout, transfer, profile_update, kyc_profile and kyc_submit events
• 1.3.7
  • Added profile_update event
• 1.3.6
  • Added optional allowed_document_format field for kyc_start event.
• 1.3.5
  • Added optional second_user_merchant_id field for transfer event
• 1.3.4
  • Added optional number_of_documents field for kyc_start event.
  • Added kyc_proof event
• 1.3.3
  • Added optional provider_id, contact_email, contact_phone, wallet_type, nationality, final_beneficiary, employment_status, source_of_funds, issue_date, expiry_date, gender fields for kyc_profile event.
  • Added kyc_start event.
• 1.3.2
  • Added optional merchant_country, mcc, acquirer_merchant_id fields for transaction event. Added optional group_id field for install, registration, confirmation, login, transaction, refund, payout and transfer events
• 1.3.1
  • Added order_item, order_submit events. Added optional transfer_source field for transfer event
• 1.3.0
  • Added optional campaign field for login, registration, install and transaction events
• 1.2.0
  • Added support for request timeouts
• 1.1.9
  • Added optional bic field for transfer event
• 1.1.8
  • Added slash before request path (guzzle deprecation since version 1.4)
• 1.1.7
  • Added kyc_profile, kyc_submit events
• 1.1.6
  • Added decision response fields: type, createdAt, sequenceId, merchantUserId, reason, action and custom response
• 1.1.5
  • Postback request_id change type to int
• 1.1.4
  • Malformed error for empty postback response
• 1.1.3
  • Postback request with request_id or transaction_id
• 1.1.2
  • added sendPostback method to send posback events
• 1.1.1
  • added optional password for login, registration events
  • added optional iban, second_iban for transfer event
• 1.1.0
  • added optional local_ip_list, plugins, referer_url, origin_url, client_resolution for browser data
  • added optional email, phone, user_merchant_id for refund event
• 1.0.9
  • new transfer event introduced
• 1.0.8
  • added optional traffic_source and affiliate_id for login event
• 1.0.7
  • custom fields validation fixed
• 1.0.6
  • string validation actualized
• 1.0.5
  • new postback event introduced
  • added optional gender for login event
  • added optional payout_account_id for payout event
  • payout_card_id, payout_ammount_converted moved to optional for payout event
  • added optional affiliate_id for transaction event
  • added optional refund_method, refund_system, refund_mid for refund event
  • added device_id to all packets
  • tests for postback event added
  • old tests modified
• 1.0.4
  • new install, refund events introduced
  • transaction_mode moved to optional for transaction event
  • added mandatory user_merchant_id for transaction event
  • tests for install, refund, transaction events added
  • payout test fixed
• 1.0.3
  • new payout event introduced
  • identity nodes are optional now
  • new experimental PersistentCurl transport for workers
• 1.0.2 cURL issue with status code 100 fixed
• 1.0.1
  • added optional email and phone to confirmation event
  • added more optional fields to all packets: 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 - release