See Regular payment process flow
There are two types of messages that you should be ready to process on entry-points specified in your Shop configuration:
  • payment_return message
    When user returns from bank-link to e-shop the MK systems redirect the user to the shop's 'return_url', passing details of the payment with the request
    Additionally another asyncronous notification message about the payment state change is sent from MK systems to your 'notification_url'
  • token_return message
    credit card payments that involve 3DS are sometimes not possible to compleate on shopping cart page since browser is redirected to payers home bank for authentication. In such cases the user is rediected back to return_url with the 'token_return' message
The request are either http(s) POST or GET request, as defined in the shop configuration (see in merchant portal Test / Live)

All message-specific details are sent as a JSON object in request parameter 'json' and the message authentication code is sent in request parameter 'mac'.


Structure of the payment_return message (POST parameter 'json')

data field example data description
shop 30d7d5d1-ec42-49ab-aa11-458cda4be9c9 identifier of the shop in MK systems
amount 11.0 Any positive number with two decimal places maximum
currency EUR
reference Order 12 merchant-side reference identifier, to associate data in MK and merchant' systrems
merchant_data \"voucher\":\"B17-0105408\ merchant-side additional data that was supplied on transaction creation
transaction 6ab058fd-f560-4199-b159-ac5a784fd08b transaction identifier
status COMPLETED CREATED | PENDING | CANCELLED | EXPIRED | APPROVED | COMPLETED | PART_REFUNDED | REFUNDED
see more about the state model
signature 98A123D3E2F6AB1D2E99... obsolete, ignore this
message_time 2016-04-11T14:29:42+0000
message_type payment_return
customer_name Tõõger Leõpäöld Name of the payer as it appeared in the bank or on credit card

Note! Some older integration modules out there may use our obsolete legacy message format that use partly different satuses:
RECEIVED, PAID, CANCELLED, EXPIRED, PART_REFUNDED, REFUNDED, DECLINED.
See more: 'redirect mode' flavour

The easiest way to explore real messages here is to walk through a bank-link payment in the Payment Gateway dialog.

Structure of the token_return message (POST parameter 'json')

data field example data description
transaction {"status":"PENDING","type":"card","method":"visa_mastercard","country":"ee","id":"0a2251a9-4b49-402c-942d-3a5cdacdbc32"} array with few relevant attributes of the transaction
token {"multiuse":false,"id":"746d59b1-d3db-4cec-9b51-3c31de664acb","valid_until":"2019-12-31"} array describing the payment token itself
error {"code":1064,"message":"Token expired"} array: Error code, error description
message_time 2016-04-11T14:29:42+0000
message_type token_return

To explore a real message in the flow walk through a credit-card payment dialog in Payment Gateway dialog with a Test card that has 3DS enabled () .


Message validation
The MAC for any JSON message exchanged is composed as follows:
UPPERCASE(HEX(SHA-512(string(JSON) + string(Secret Key))))
  1. The string values of the JSON message and the API secret are concatenated.
  2. The resulting string is hashed by SHA-512.
  3. The resulting hash is presented in upper-case HEX-encoding.
So to validate the message authenticy compose the MAC based on the received 'json' and the SecretKey of your Shop, and compare the computed MAC with the one you recieved from request.