Skip to main content

Regular Payment Flow

Step 1: Payment Method Selection

There are two options how payment method selection could be implemented:

  1. Redirect customer to MakeCommerce payment method selection page
  2. Show payment method selection on your e-shop

First option is easier and faster to implement, however, second one is considered to have better user experience and conversion rate. Below you will find instructions on how to implement each of those options.

1. Redirect customer to MakeCommerce payment method selection page​

Use POST Create Transaction endpoint and redirect customer to url returned under payment_methods -> other -> redirect

"other": [
{
"name": "redirect",
"url": "https://payment.maksekeskus.ee/pay.html?trx=fb907584-f352-4b5d-8b5f-e41b7e15d25d"
},
]

Customer will be redirected to following page:

Payment Gateway

When creating a transaction, under customer object there are optional fields country and locale. Field country will determine which country payment methods are preselected and field locale will determine preselected language of the page. Customer has the option to change preferred country and language. If these fields are not provided, then the country and language is preselected based on MakeCommerce system logic.

If you use this approach skip Step 2 and continue to Step 3: Handle Transaction Status.

2. Show payment method selection on your e-shop

Use GET Payment Methods endpoint without any parameters to receive all available payment methods. We recommend to cache results on server side to improve speed. Available payment methods are not changing often so it is enough to do 1-3 requests per 24 hours and cache results.

Example response (not full):

"banklinks": [
{
"name": "swedbank",
"url": "https://payment.maksekeskus.ee/open-banking.html?method=EE_SWED_OB&trx=",
"country": "ee",
"countries": [
"ee"
],
"channel": "Swedbank EE OB",
"max_amount": 20000.0,
"display_name": "Swedbank",
"logo_url": "https://static.maksekeskus.ee/img/channel/lnd/swedbank.png"
},
]

Returned payment methods will contain country in order to group payment methods by country in your UI. All payment methods will be grouped in following categories:

  • banklinks - bank based payment methods like payment initiation service or banklinks.
  • cards - card based payment methods like VISA, Mastercard, Apple Pay or Google Pay.
  • paylater - different buy now pay later payment methods.
  • other - under this category redirect URL is returned which is described in chapter Redirect customer to MakeCommerce payment method selection page. You should not dynamically display payment methods in your UI returned under other category.

All payment methods have max_amount parameter and some have min_amount parameter. If the order amount is not between those two parameters - you should not display that specific payment method for the customer.

Step 2: Transaction Creation

After customer selected payment method on your e-shop and pressed pay, use POST Create Transaction endpoint for transaction creation. Redirect customer to url of selected payment method.

Step 3: Transaction Status Handling

Your system should always be ready to handle transaction status which is provided with payment_return message. There are three different URLs where your system should expect to receive that message:

  • return_url - customer is redirected here after successful payment.
  • cancel_url - customer is redirected here after canceled/unsuccessful payment.
  • notifications_url - asynchronous transaction status information is sent to this url. 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.

There are two options how to set all those URLs:

  1. You can configure them in Merchant Portal under API section: Return url

  2. You can pass them when creating transaction using POST Create Transaction endpoint. If not passed via this endpoint - the URLs from Merchant Portal is used, if passed - it overwrites the URLs from Merchant Portal.

Structure of payment_return message

Field nameSub-field nameExample valueDescription
jsonamount90.95Transaction amount - any positive number with two decimal places maximum.
currencyEURCurrency.
customer_name- ec1adce4-b485-49c3-acf1-319bf80d5e29 - there will be just id value for those payment methods that do not return customer name.
- John Smith - there could be name and surname from those payment methods that return customer name.
Customer name. There will be just id value for those payment methods that do not return customer name. There could be name and surname from those payment methods that return customer name.
merchant_datainternalId321Value which was passed in merchant_data field when creating transaction.
message_time2024-11-13T12:03:48+0000Message time.
message_typepayment_returnMessage type. Your system should execute the logic described in this chapter if type of message is payment_return.
reference123abcValue which was passed in reference field when creating transaction.
shop1ad3a943-6958-430b-b58b-e55524a4e360Shop ID.
signature75DCA7CF1050E045C574D423B5A2E4BB62BC12B399F7E4
415D20D4FBDD0DD95E62FFF2DFAAF135D6FCBAF1B01CD9
25F9C098409215DDCD6995B7FA89917FD919
Legacy field to validate message. Don’t use it, use mac instead.
statusCOMPLETEDStatus of the transaction. Check all possible statuses here.
transactionf291af44-8d3c-4dc8-b4a9-31592023aae3Transaction ID.
macE4812E5D0EE8FE6A158826C52EF0E45D13E3746A4CA0BE
43562F09758C956E9D6C09671EF641C02BB967E5AFE2F0
AFD4BB3749EE36315F624763A2CBBD5DF34A
Field which allows your system to validate the message authenticity/integrity. Check how validation should be done here.

Raw content example:

json=%7B%22amount%22%3A%2290.95%22%2C%22currency%22%3A%22EUR%22%2C%22customer_name%22%3A%22ec1adce4-b485-49c3-acf1-319bf80d5e29%22%2C%22merchant_data%22%3A%22internalid321%22%2C%22message_time%22%3A%222024-11-13T12%3A03%3A48%2B0000%22%2C%22message_type%22%3A%22payment_return%22%2C%22reference%22%3A%22123abc%22%2C%22shop%22%3A%221ad3a943-6958-430b-b58b-e55524a4e360%22%2C%22signature%22%3A%2275DCA7CF1050E045C574D423B5A2E4BB62BC12B399F7E4415D20D4FBDD0DD95E62FFF2DFAAF135D6FCBAF1B01CD925F9C098409215DDCD6995B7FA89917FD919%22%2C%22status%22%3A%22COMPLETED%22%2C%22transaction%22%3A%22f291af44-8d3c-4dc8-b4a9-31592023aae3%22%7D&mac=E4812E5D0EE8FE6A158826C52EF0E45D13E3746A4CA0BE43562F09758C956E9D6C09671EF641C02BB967E5AFE2F0AFD4BB3749EE36315F624763A2CBBD5DF34A

Validation of mac value

Before executing any logic on your system, you should validate message authenticity/integrity with mac value. The mac value for any json message is created with such algorithm: 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.

To validate the message authenticity/integrity calculate the mac based on the received json and the Secret Key of your Shop, and compare the calculated mac with the one you received from the request.

Transaction statuses

Transaction statusDescription
CREATEDTransaction was initiated by the shop.
PENDINGPayment process is in progress.
CANCELLEDPayment was either canceled or declined.
EXPIREDCustomer has not completed the payment during 30 minutes after last change of the transaction status.
APPROVEDPayment process is in progress. Used only for some payment methods. This status does not guarantee transaction will be COMPLETED.
COMPLETEDTransaction has been successfully paid. Only after this status goods or services should be delivered.
PART_REFUNDEDTransaction amount has been partially refunded to the customer.
REFUNDEDTransaction amount has been fully refunded to the customer.