Maksekeskus developer portal | Payment notification messages

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

* Keep in mind that payment updates may be received twice. Once with payment_return and additionally with asyncronous notification message about the payment state change. Your server must firstly return a successful status code (2xx) and only then execute any other logic on your system, otherwise timeout could be caused if 2xx is not returned in 30 seconds.

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 () .

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

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

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

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