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 provided on our test cards page.

Important: checkout.js can only be used with approved domain served over HTTPS. In TEST environment you can 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.

3D secure card payment flow

Not all the 3D Secure payments can be processed within an 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 always be ready to process 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
3D secure single one-off card payment flow
  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)

1. Let's create a transaction (we use settings from the session context)

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:


2. Select a Test card for use in the dialog (copy to clipboard)

      4505131234000011    | expiration date: 06/28 | CVC: 123 | (expand for more cards..)

3. prepare parameters and trigger checkout.js

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.

Form submit approach

JS callback approach


See all checkout.js options

4. Examine returned data

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.