Regular Payment Flow
Step 1: Payment Method Selection
There are two options how payment method selection could be implemented:
- Redirect customer to MakeCommerce payment method selection page
- 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:
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 categoryredirect
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 underother
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:
-
You can configure them in Merchant Portal under API section:
-
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 name | Sub-field name | Example value | Description |
---|---|---|---|
json | amount | 90.95 | Transaction amount - any positive number with two decimal places maximum. |
currency | EUR | Currency. | |
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_data | internalId321 | Value which was passed in merchant_data field when creating transaction. | |
message_time | 2024-11-13T12:03:48+0000 | Message time. | |
message_type | payment_return | Message type. Your system should execute the logic described in this chapter if type of message is payment_return . | |
reference | 123abc | Value which was passed in reference field when creating transaction. | |
shop | 1ad3a943-6958-430b-b58b-e55524a4e360 | Shop ID. | |
signature | 75DCA7CF1050E045C574D423B5A2E4BB62BC12B399F7E4 415D20D4FBDD0DD95E62FFF2DFAAF135D6FCBAF1B01CD9 25F9C098409215DDCD6995B7FA89917FD919 | Legacy field to validate message. Don’t use it, use mac instead. | |
status | COMPLETED | Status of the transaction. Check all possible statuses here. | |
transaction | f291af44-8d3c-4dc8-b4a9-31592023aae3 | Transaction ID. | |
mac | E4812E5D0EE8FE6A158826C52EF0E45D13E3746A4CA0BE 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))))
- The string values of the
json
message and the API secret are concatenated. - The resulting string is hashed by SHA-512.
- 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 status | Description |
---|---|
CREATED | Transaction was initiated by the shop. |
PENDING | Payment process is in progress. |
CANCELLED | Payment was either canceled or declined. |
EXPIRED | Customer has not completed the payment during 30 minutes after last change of the transaction status. |
APPROVED | Payment process is in progress. Used only for some payment methods. This status does not guarantee transaction will be COMPLETED . |
COMPLETED | Transaction has been successfully paid. Only after this status goods or services should be delivered. |
PART_REFUNDED | Transaction amount has been partially refunded to the customer. |
REFUNDED | Transaction amount has been fully refunded to the customer. |