Skip to content

Quickstart

Jump to bottom Edit New page
Shabab Haider Siddique edited this page May 25, 2021 · 1 revision

Quick Start

Here is a step by step overview of a a payment from start to finish.

Initialize the client object

use Cardinity\Client;

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

Gather device data

For 3dsv2 we need some device information. Parameters screen_width, screen_height, browser_language, color_depth, time_zone of browser_info could be collected dynamically using javascript. For example -

<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='' />
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();
});

Create new payment

We create the payment by calling the Payment\Create method providing all the information.

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

Calling the method

Then call the Cardinity API on our created client. This should be executed using try ... catch blocks:

$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') {
      ///Process 3d secure
    }
} 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);
}

3D secure Authorization

If initial payment request return with status pending, further authorization will be required. The following example is simplest form of 3ds authorization issue process.

if ($payment->isThreedsV2()) {
    // $auth object for data required to finalize payment
    $auth = $payment->getThreeds2Data();

    echo '<html>
       <head>
          <title>3-D Secure Example</title>
          <script type="text/javascript">
              function OnLoadEvent()
              {
                // Make the form post as soon as it has been loaded.
                document.ThreeDForm.submit();
              }
          </script>
       </head>
       <body onload="OnLoadEvent();">
          <p>
              If your browser does not start loading the page,
              press the button below.
              You will be sent back to this site after you
              authorize the transaction.
          </p>
          <form name="ThreeDForm" method="POST" action="'.$auth->getUrl().'">
              <button type=submit>Click Here</button>
              <input type="hidden" name="PaReq" value="'.$auth->getData().'" />
              <input type="hidden" name="TermUrl" value="'.$your_callback_url.'" />
              <input type="hidden" name="MD" value="'.$your_transaction_identifier.'" />
          </form>
       </body>
    </html>';

}else if ($payment->isThreedsV1()) { //fallback is necessary as not all cards may be 3dsv2 yet
    // $auth object for data required to finalize payment
    $threeds2AuthorizationInfo = $payment->getAuthorizationInformation();

    echo '<html>
       <head>
          <title>3-D Secure Example</title>
          <script type="text/javascript">
              function OnLoadEvent()
              {
                // Make the form post as soon as it has been loaded.
                document.ThreeDForm.submit();
              }
          </script>
       </head>
       <body onload="OnLoadEvent();">
          <p>
              If your browser does not start loading the page,
              press the button below.
              You will be sent back to this site after you
              authorize the transaction.
          </p>
          <form name="ThreeDForm" method="POST" action="'.$threeds2AuthorizationInfo->getAcsUrl().'">
              <button type=submit>Click Here</button>
              <input type="hidden" name="creq" value="'.$threeds2AuthorizationInfo->getCReq().'" />
              <input type="hidden" name="threeDSSessionData" value="'.$your_transaction_identifier.'" />
          </form>
       </body>
    </html>';
    // finalize process should be done here.
}

Finalize payment

Once authorization completed the pending payment can be finalized. To finalize payment it should have status pending. Data received from 3D secure system should be used to create 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 ...
// ...

Get existing payment

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

Clone this wiki locally