Our Credit Card Dialog is a secure way to take payments from your clients so that the sensitive card data does not pass through your systems, thus avoiding the PCI DSS compliancy requirement on you.
Our checkout.js builds a card data collection dialog as a semi-transparent iFrame layer on top of shop checkout page. The sensitive card data is submitted directly within this iFrame to Maksekeskus backend. If applicable the user is redirected through 3DS dialog. On sucessful authorization, payment is completed and result is passed back to the shop.
The request contains a payment token that - if you requested as 'multi-use token' - you could store in your system for later reuse. See more about it: recurring credit card payments

For testing with credit cards you can use the information procided on our test cards page.

Important: checkout.js could be used only from approved HTTPS domains. In Test environment you could add as many domains as you want in Merchant self-service portal (Settings -> General settings -> Shop domain). In Live environment domains are added by our support team.

Not all the 3D Secure payments can be processed within iFrame. They will involve redirecting user to extenal authorization page, and when done, the user is redirected back to thereturn_url of the shop. Thus the return_url of your shop must be always ready to process also the token_return message.

  1. Create a transaction in API
  2. Prepare parameters for the checkout.js script and trigger it:
    • Place an hidden form on your checkout page that checkout.js will use to post the data to your backend
      OR
    • Invoke checkout.js with a callback function to process the data returned
  3. checkout.js now builds an iFrame with dialog where the customer fills in Credit card data and submits the data to MK backend
  4. Customer is redirected to card issuer bank's authentication dialog
  5. After authentication the customer is redirected back to MK systems, our backend will process the payment through respective card networks
  6. The customer is redirected back to the shop return_url by making POST request with (token_return message)
  7. Verify the transaction state within the message returned: if state='COMPLETED' you may consider the payment successful and proceed with your order fulfillment logic
  8. Display success message to buyer
  1. Customer reaches to the check-out page on e-shop site.
  2. E-shop registers a new Transaction in MK-Systems.
  3. MK System responds to e-shop back-end server, which initiates payment dialog with displaying payment methods to customer.
  4. Customer selects to pay with credit card.
  5. E-shop prepares parameters and invokes checkout.js, which builds a card data collection and launches Credit Card Dialog as a semi-transparent iFrame layer on top of shop checkout page. The sensitive card data is submitted directly within this iFrame to Maksekeskus backend. If applicable the user is redirected through 3DS dialog. E-shop must to trigger checkout.js.
  6. In the dialog the customer fills in credit card data and submits the data to MK backend, to perform the payment in the selected channel.
  7. iFrame sends to MK System ajax POST message with card data and xid.
  8. MK System initiates payment in Card Networks with submitted card data. Card network makes lookup, if card is 3D-enabled.
  9. MK Systems sends redirect to 3D to MK iFrame which turns to e-shop browser.
  10. E-shop browser makes Payment Authentication POST request to Card Issuer Bank which responds with authentication dialog.
  11. Customer enters authentication data.
  12. E-shop responses to MK System, which completes payment in Card Network. Card Network responses with payment status to MK System. MK System sends POST message with token to merchant return url.
  13. This step depends on e-shop solution, what is done on e-shop side after message is received from MK Systems to e-shop return_url. Eg. e-shop can make request with token to its back-end server, which responses by displaying to customer 'Thank you page'.
  14. Payout batch is made to Merchant account from MK System according to merchant agreement. For card payments it takes 7 banking-days, that transaction becomes visible under Accounting details.

Tutorial(click on collapsed titles for more info)

Create a transaction

<?php

$request_body = array(
    'transaction' => array(
        'amount' => $context->transaction->amount,
        'currency' => $context->transaction->currency,
        'reference' => $context->transaction->reference
    ),
    'customer' => array(
        'email' => $context->customer->email,
        'ip' => $context->customer->ip,
        'country' => $context->customer->country,
        'locale' => $context->customer->locale
    )
);

$transaction = $MK->createTransaction($request_body);

?>
Request
Content type
Headers
Body
Response
Content type
Headers
Body

    So we have now a Transaction, ID:


      4505131234000011    | expiration date: 06/24 | CVC: 123 | (expand for more cards..)
There are 2 approaches how to invoke the checkout.js and receive back data from the dialog:
  • place an hidden form on page that checkout.js will use to post the data to your backend, OR
  • invoke checkout.js with a callback function

Important: checkout.js could be used only from approved HTTPS domains. In Test environment you could add as many domains as you want in Merchant self-service portal (Settings -> General settings -> Shop domain). In Live environment domains are added by our support team.

checkout.js binds itself to the form within which it was included
We have placed such form to this page:
 <form id="checkoutForm" action="return.php" method="POST">
    <input type="hidden" name="transaction" id="transaction" value="<?php echo $transaction->id; ?>" />

    <script src="/checkout/dist/checkout.min.js"
        data-key=""
        data-transaction=""
        data-email=""
        data-client-name=""
        data-locale=""
        data-selector="#checkoutBtn"
        data-backdrop-close="false">
    </script>

</form>

We use here js callback function to receive the data back from the credit card dialog
We have placed such js script to the page:

<script src="<?php echo $context->creditcard->url; ?>/checkout/dist/checkout.min.js"></script>
    
<script>
    window.cc_callback = function(data)
    {   
        alert( 'The CC dialog returned: \r\n \r\n'+ JSON.stringify(data) ); 
    }

    window.Maksekeskus.Checkout.initialize(
    {   'key' : '<?php echo $context->shop->publishableKey; ?>', 
        'transaction' : '<?php echo $transaction->id; ?>',
        'email' : 'john@diehard.ly', 
        'clientName' : 'John McLane', 
        'locale' : 'en',
        'completed' : 'cc_callback', 
        'cancelled' : 'cc_callback' }
    );
</script>

<button type="button" class="btn btn-primary" aria-label="Open CC Payment dialog" onclick="window.Maksekeskus.Checkout.open();">Open CC Payment dialog</button> 






Note that 3D Secure card payment dialog does not end here, instead it will arrive to your return_url
If you use Form Submit based approach, then you examine the data in submit request handler.

Data returned to js callback(will appear here if you complete the tutorial):