README

这是Cardinity API的官方PHP客户端库，[Cardinity的API](https://developers.cardinity.com/api/v1/)。
库包括了API提供的所有功能。库被设计得灵活且易于开发者理解和使用。

文档

更详细的文档和使用示例可以在这里找到：这里。

使用方法

通过Composer安装

$ php composer.phar require jpranskaitis/cardinity-sdk-php

直接下载

您可以下载以cardinity-sdk-php-*.zip开头的最新版本文件：这里。

进行API调用

初始化客户端对象

use Cardinity\Client;
$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

创建新的支付

use Cardinity\Method\Payment;

$method = new Payment\Create([
    'amount' => 50.00,
    'currency' => 'EUR',
    'settle' => false,
    'description' => 'some description',
    'order_id' => '12345678',
    'country' => 'LT',
    'payment_method' => Payment\Create::CARD,
    'payment_instrument' => [
        'pan' => '4111111111111111',
        'exp_year' => 2021,
        'exp_month' => 12,
        'cvc' => '456',
        'holder' => 'Mike Dough'
    ],
    'threeds2_data' =>  [
        "notification_url" => "your_shop_url_for_handling_callback", 
        "browser_info" => [
            "accept_header" => "text/html",
            "browser_language" => "en-US",
            "screen_width" => 600,
            "screen_height" => 400,
            'challenge_window_size' => "600x400",
            "user_agent" => "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:21.0) Gecko/20100101 Firefox/21.0",
            "color_depth" => 24,
            "time_zone" => -60
        ],
    ],
]);

所有threeds2_data参数应该动态设置。

browser_info中的screen_width、screen_height、browser_language、color_depth、time_zone参数可以使用javascript动态收集

document.addEventListener("DOMContentLoaded", function() {
    document.getElementById("screen_width").value = screen.availWidth;
    document.getElementById("screen_height").value = screen.availHeight;
    document.getElementById("browser_language").value = navigator.language;
    document.getElementById("color_depth").value = screen.colorDepth;
    document.getElementById("time_zone").value = new Date().getTimezoneOffset();
});

并将其放置到HTML表单中

<!-- ... -->
<input type='hidden' id='screen_width' name='screen_width' value='' />                
<input type='hidden' id='screen_height' name='screen_height' value='' />                
<input type='hidden' id='browser_language' name='browser_language' value='' />                
<input type='hidden' id='color_depth' name='color_depth' value='' />                
<input type='hidden' id='time_zone' name='time_zone' value='' />
<!-- ... -->

然后使用try ... catch块执行对Cardinity API的调用

$errors = [];
try {
    /** @type Cardinity\Method\Payment\Payment */
    $payment = $client->call($method);
    $status = $payment->getStatus();
    if ($status == 'approved') {
        echo '<p>Your payment approved without 3D secure.</p>';
    } elseif ($status == 'pending') {
        if ($payment->isThreedsV2()) {
            // $auth object for data required to finalize payment
            $auth = $payment->getThreeds2Data();
            // finalize process should be done here.
        }else if ($payment->isThreedsV1()) {
            // $auth object for data required to finalize payment
            $auth = $payment->getAuthorizationInformation();
            // finalize process should be done here.
        }
    }
} catch (Cardinity\Exception\InvalidAttributeValue $exception) {
    foreach ($exception->getViolations() as $key => $violation) {
        array_push($errors, $violation->getPropertyPath() . ' ' . $violation->getMessage());
    }
} catch (Cardinity\Exception\ValidationFailed $exception) {
    foreach ($exception->getErrors() as $key => $error) {
        array_push($errors, $error['message']);
    }
} catch (Cardinity\Exception\Declined $exception) {
    foreach ($exception->getErrors() as $key => $error) {
        array_push($errors, $error['message']);
    }
} catch (Cardinity\Exception\NotFound $exception) {
    foreach ($exception->getErrors() as $key => $error) {
        array_push($errors, $error['message']);
    }
} catch (Exception $exception) {
    $errors = [$exception->getMessage()];
}
if ($errors) {
    print_r($errors);
}

完成支付

要完成支付，其状态应该是pending。从3D安全系统接收的数据应用于创建Finalize $method。

use Cardinity\Method\Payment;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

if($v2){
    $method = new Payment\Finalize(
        $payment->getId(), // payment object received from API call
        $auth->getCreq(), // payment object received from API call
        true // BOOL `true` to enable 3D secure V2 parameters
    );
}elseif($v1){
    $method = new Payment\Finalize(
        $payment->getId(), // payment object received from API call
        $auth->getData(), // payment object received from API call
        false // BOOL `false` to enable 3D secure V1 parameters
    );
}

// again use same try ... catch block
try {
    $payment = $client->call($method);
}
// same catch blocks ...
// ...

获取现有支付

$method = new Payment\Get('cb5e1c95-7685-4499-a2b1-ae0f28297b92');
/** @type Cardinity\Method\Payment\Payment */
$payment = $client->call($method);

API文档

https://developers.cardinity.com/api/v1/

开发状态

所有API v1方法都已实现。

测试

在Windows上php vendor/phpunit/phpunit/phpunit