NAV

Introduction and overview

Welcome! In this page you can find a quick overview of the Makecommerce ecosystem which will be explained more thoroughly in this page.

MakeCommerce's developer portal is divided into 5 sections.

Section Description
API Docs API Docs is the starting point for using MakeCommerce ecosystem as a developer. This page has all the info gathered together or it is linking you to the right resource.
API Tester API Tester can be used to try out our REST API endpoints. After reading API Docs this is the place to go try out some requests. We have made a small tutorial to get you started with the API tester: "How to use our API Tester?"
Payment Gateway Create a transaction and get redirected to payment gateway.
Credit Card Whole section for Credit Card flow. There you can find flow descriptions, test cards and some code snippets.
Notifications Section about notifications.

First steps

Integration modules supported

API integration flow

API integration. Payment method selection is inside the shop. Transaction first.

  1. Customer proceeds to checkout page.
  2. Shop sends 'Create transaction' to MK system.
  3. Shop receives payment methods. A and B.
  4. Customer selects payment method.
  5. In case of credit card payment transaction is done over API, payment dialog is invoked in iframe by checkout.js. checkout.js redirects from and to shop page only in 3DSecure flow.
  6. In case of banklink Customer is directed to selected bank URL by the API.
  7. Customer makes payment.
  8. With successful payment Customer is redirected back to e-shop return-URL.
  9. In case of cancelling payment or on exception, Customer is redirected back to e-shop cancel-URL.
  10. Messages are sent to e-shop notification-URL. Notifications are sent as GET/POST/email only if shop has specified the values. 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.
  11. Transaction info is received by MK systems.
  12. Payout batch is made to Merchant bank account according to merchant payout frequency agreement; e.g. in case of bank-link payments payout will be done on next bank-day; in case of credit-card payment payout can take up to seven bank-days.
 Receive payment methods after 'Create transaction'
  • A. Take payment methods from 'Create transaction' response
  • B. Take payment methods from cache.
Payment methods can be cached from:
  • /v1/shop/configuration https://developer.maksekeskus.ee/shop.getconfig.php (preferred)
  • /v1/methods (amount is not required) https://developer.maksekeskus.ee/methods.php
For option A, it is possible
  • Request payment methods separately.
  • Request payment methods for current transaction.
Remark for taking payment methods from cache:
  • It is possible, that payment methods information in cache is not up to date. It is possible, that cached payment methods information does not have the information about transaction requirements; e.g. pay-later methods have different minimum amount requirements.


API integration flow, payment methods are requested first.

  1. Customer proceeds to checkout page.
  2. Shop receives payment methods. C and D.
  3. Shop sends 'Create transaction to MK system.
  4. Customer selects payment method.
  5. In case of credit card payment transaction is done over API, payment dialog is invoked in iframe by checkout.js. checkout.js redirects from and to shop page only in 3DSecure flow.
  6. In case of banklink Customer is directed to selected bank URL by the API.
  7. Customer makes payment.
  8. With successful payment Customer is redirected back to e-shop return-URL.
  9. In case of cancelling payment or on exception, Customer is redirected back to e-shop cancel-URL.
  10. Messages are sent to e-shop notification-URL. Notifications are sent as GET/POST/email only if shop has specified the values.
  11. Transaction info is received by MK systems.
  12. Payout batch is made to Merchant bank account according to merchant payout frequency agreement; e.g. in case of bank-link payments payout will be done on next bank-day; in case of credit-card payment payout can take up to seven bank-days.
 Receive payment methods before 'Create transaction'
  • C. Request payment methods according to amount
  • D. Take payment methods from cache.
Payment methods can be cached from:
  • /v1/shop/configuration https://developer.maksekeskus.ee/shop.getconfig.php (preferred)
  • /v1/methods (amount is not required) https://developer.maksekeskus.ee/methods.php
Remark for taking payment methods from cache:
  • It is possible, that payment methods information in cache is not up to date. It is possible, that cached payment methods information does not have the information about transaction requirements; e.g. pay-later methods have different minimum amount requirements.

Payment methods supported

Test environment

The Test Environment is a safe sandbox where you can explore and learn how our systems function without worrying about messing up your real account at MakeCommerce / Maksekeskus.

Find out more about Test environment:
https://makecommerce.net/for-developers/test-environment/

Transaction states

Status Description
CREATED Transaction initiated by merchant
PENDING Payment process has been initiated, customer is filling in data or payment is in progress in payment channel
CANCELLED Customer has explicitly terminated the payment process – pressed ‘cancel’ button in bank’s payment dialog
EXPIRED Customer has not completed the payment during 30 minutes in PENDING state
APPROVED This state is relevant to some payment channels only – card payments, Citadele bank-link and DNB bank-links. On card payments this means that card data has been already verified, and transaction is waiting now for payment. Regular card payments are however automatically completed.
COMPLETED Transaction has been successfully paid (green light for merchant to deliver goods/services). The funds will be transferred to merchant with next payout
PART_REFUNDED The transaction amount has been partially refunded to the customer
REFUNDED Transaction has been completely refunded

Refund states

Status Description Possible transitions
CREATED Refund initiated by merchant SENT
SENT Refund order sent to bank or processor. Maksekeskus has sent out payment order to respective bank/card network. Respective amount is reserved in Merchant account at Maksekeskus. SETTLED FAILED
SETTLED Refund order settled by bank or processor. The money has most probably already reached to customer account.  
FAILED Can happen only to refunds made to finnish bank-link payments. See more about complexity of Finnish bank-link refunds Or in case there was technical error while creating the refund at card payment processor  

API error codes


    
Client error response body

      {
        "code": 1001,
        "message": "Invalid input",
        "errors": [
            {
                "resource": "transaction",
                "field": "currency",
                "type": "invalid"
            },
            {
                "resource": "customer",
                "field": "ip",
                "type": "missing"
            }
        ]
    
      }

HTTP Status Codes
API responds with the following HTTP status codes in case of errors:

Error code Description
400 Bad request, invalid body or parameters; business logic errors
401 Authentication failed or not sufficient (ie. when level 1 provided, but level 2 required)
404 Resource does not exist or is not available for this shop (belongs to another shop)
409 Resource conflict
415 Request content type is not application/json.
500 Server Error: all server internal errors

Error Response Body

Client Errors:

In case of client errors, API responds with a code and message parameter. An optional errors collection may be returned with more information about the error occurred.

Server Errors:

Server errors return no response body.

Business logic errors

All business logic errors are returned with a 400 HTTP Status.

Code Message
1001 Invalid request
1002 Resource not found
101x Errors related to shop or merchant
1011 Shop not active
1012 Card payments not enabled for this shop
1013 OCP or Recurring disabled for shop
102x Errors related to transactions
1021 Transaction in wrong status
103x Errors related to payments
1031 Payment in wrong status
1032 Cannot make payment (transaction status violation)
1033 Card expired
1034 Not sufficient funds
1035 Payment declined
1036 Authorization failed
104x Errors related to refunds
1041 Transaction in wrong status, cannot be refunded
1042 Refund amount greater than available to refund
105x Errors related to customers
106x Errors related to tokens
1061 Invalid transaction
1062 Transaction conflict
1063 Failed to create Payment Token
1064 Token expired
1065 Token in wrong status
2003 Unable to deposit payment
2005 Unable to refund payment

Test credit cards

To test 0-amount Authorization & "Save Card functionality", please use the cards that have defined expiration date and CVC

To simulate decline you should use same test cards with amount 99.99 EUR. All card payments with such amount will fail.

Getting Started

Basic Flow

  1. The buyer has reached to the check-out page on e-shop site
  2. The shop presents the selection of payment methods available
  3. The buyer makes a choice and proceeds to payment
  4. The shop registers a new Transaction in MK-API and directs user to the selected payment channel – either redirects to bank-link or launches the Credit Card Dialog
  5. Shop server now creates the transaction in MK API and recieves back an array of urls pointing to payment channels
  6. Depending on method the user selected, the e-shop server:
    1. Case banklink: redirects user to the banklink url supplied by the transaction creation response
    2. Case credit card: launches MK Credit Card Dialog by invoking checkout.js
  7. Payment links should not be placed inside an iframe, otherwise payments will not work.
  8. The user performs the payment in the channel
  9. Returning from:
    1. Bank link: user is redirected to return_url of the shop with payment_return message
    2. Credit card dialog: user is redirected back with token_return message (POST to return_url)
  10. Payment links should not be placed inside an iframe, otherwise payments will not work.
  11. The shop will verify the message and state of transaction within and display successful payment confirmation page (or goes back to payment method selection step)
  12. MK servers will send additional async message about the transaction status change to the shop server’ notification_url (see notifications). 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.

banklink payment diagram

card payment diagram 3d

card payment diagram 3d

Create account

Request us to create you an account in our Test Environment so you could explore and test your integration in full.
Send your request to: support@maksekeskus.ee

We will create you a shop in our Test environment.
This is how you get you API keys for the integration.

SDK

We do have a small library for PHP available in github.

Java SDK

We also have a library for Java available in github.

Return URLS

As you see in the basic flow description in the basic basic flow section, your shop is expected to accept few messages about payments from MK systems. The messages may arrive in-band (from user browser) or directly from MK server to your e-shop server (M2M).

There are 2 messages:

The shop should implement following entry-points where the user (and the messages) can be sent:

The entry-points can be declared in your shop configuration, you can change them in Merchant Portal under API settings. You can get there by going to Test Merchant Portal

api endpoints

Alternatively, you can dynamically specify them for each transaction when you create the transaction (transaction_urls). For example using API tester you can set these urls here API tester - Create transaction

If you have problems with this please take a look at "How to use our API tester?" section.

How to use our API tester?

Using our API tester for the first time can be confusing.

Setting up your API tester context:

  1. Firstly choose a context Setup your context
  2. For example select in the Predefined setup "mk-test" or setup your own API keys from the Shop Configuration. Make sure you use test environment
  3. After setting up your context with either predefined setup or your shop setup click on the Save context button which is located in the bottom of the page.

setting context in api tester


Making your first API tester request
We will be creating a transaction as an example.

response from the api tester

Making requests with REST API

Environments & Endpoints

The Test Environment is a safe sandbox where you can explore and learn how our systems function without worrying about messing up your real account at MakeCommerce / Maksekeskus.

These two environments are totally isolated - the identifiers and API keys are different in the Test and Live environments – so please be careful and do not mix them up

Authentication

curl -u 1ca58c6f-89c2-442f-950a-cd5fa3484397:d4a581cceff06c03a49915643661ee75 https://api.maksekeskus.ee/transactions

API requests are made via HTTPS. Each request must be authenticated with HTTP Basic Authentication using Shop’s ID (as username) and an API authentication key (as password)
Two types of authentication keys exist:

The API tokens can be found under the API settings section in the Merchant Interface. Remember that anyone who has the authentication token has access to see and change everything available via the API. If an API key has been discovered by another party, it can be changed using Reset the Publishable/Secret Key option under the API settings section in the Merchant Interface.

Validating the response



Java code example for validating the response

private static String sha512(String input, String secret)  {
      MessageDigest md5;
      try {
        md5 = MessageDigest.getInstance(SHA_512);
      } catch (NoSuchAlgorithmException e) {
        throw new RuntimeException(e);
      }
      md5.update(input.getBytes(StandardCharsets.UTF_8));
      md5.update(secret.getBytes(StandardCharsets.UTF_8));
      byte[] digest = md5.digest();
      StringBuilder sb = new StringBuilder();
      for (int i = 0; i < digest.length; ++i) {
        sb.append(Integer.toHexString((digest[i] & 0xFF) | 0x100), 1, 3);
      }
      return sb.toString().toUpperCase();
    }
}

All message-specific content is sent as an JSON object in request parameter json and the message authentication code (MAC) is sent in request parameter mac.

The MAC is composed as follows:

UPPERCASE(HEX(SHA-512(string(JSON) + string(Secret Key))))

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.

In the right side of the screen Java example of validating the response can be found.

Request limits

Shop

Shop object

A shop represents an entity that is collecting online payments.

Get configuration

$myEnvironment=array(
    'platform'=>'magento 2.1',
    'module'=>'codejunkies 1.0.1');
$request = array('environment' => json_encode($myEnvironment) );

$shop = $MK->getShopConfig($request);

HTTP REQUEST

GET /v1/shop/configuration

Retrieves configuration of the 'Shop’ as an json array that can be handy to cache on your server side. (You could refresh this i.e. each hour or daily).

Most importantly the returned data contains:

As input we ask you to provide description of the integration environment - info about the e-commerce platform and integration module you are developing. We need this information for better problem resolution capability and for estimating imapct of changes in our API.

Try in API tester

HTTP RESPONSE

JSON: Shop Object

Get payment methods

HTTP REQUEST

GET /v1/methods?transaction=&amount=&currency=&country=

GET /v1/methods has four possible GET parameters

Parameter Required Description
transaction no Returns payment methods available for the specific transaction
amount no Returns payment methods available for the specific amount
currency no Returns payment methods available for the specific currency
country no Returns payment methods available for the specific country

Retrieves payment methods that are available.

The returned data contains all the available payment methods, which are grouped into four subarrays:

Try in API tester

HTTP RESPONSE

Array of available payment methods

Obtaining the shop specific payment methods via shop configuration

It is also possible to retrieve shop specific methods with the shop configuration request. The response has all the information about the specific shops' configuration but also has all the available payment methods included

Read more about the shop configuration

Obtaining the transaction specific payment methods when creating the transaction itself

Lastly, all the possible payment methods for a specific transaction are included in the response, whenever the transaction is created.

Read more about creating transactions

Get account statement

$request = array( 'since' => date("Y-m-d", strtotime("-1 Months")) );
$statement = $MK->getAccountStatement($request);



Get account statement response body

[
    {
        "created": "2019-04-12T09:09:09+0000",
        "amount": 12.95,
        "type": "INCOME",
        "transaction": "468526",
        "channel": "Visa/Mastercard",
        "balance_before": 212.82,
        "balance_after": 225.77,
        "merchant_reference": "123abc",
        "payout_id": "17041",
        "original_amount": 0.0,
        "exchange_rate": 0.0
    },
    {
        "created": "2019-04-12T09:09:09+0000",
        "amount": -0.3,
        "type": "TRX_FEE_FIX",
        "transaction": "468526",
        "channel": "Visa/Mastercard",
        "balance_before": 225.77,
        "balance_after": 225.47,
        "merchant_reference": "123abc",
        "payout_id": "17041",
        "original_amount": 0.0,
        "exchange_rate": 0.0
    },
    {
        "created": "2019-04-12T09:09:09+0000",
        "amount": -0.06,
        "type": "VAT",
        "transaction": "468526",
        "channel": "Visa/Mastercard",
        "balance_before": 225.47,
        "balance_after": 225.41,
        "merchant_reference": "123abc",
        "payout_id": "17041",
        "original_amount": 0.0,
        "exchange_rate": 0.0
    }
]

HTTP REQUEST

GET /v1/shop/accountstatements

GET /v1/shop/accountstatements/xml

GET /v1/shop/accountstatements/camt053

Either since or payout_id is required other fields are voluntary.
For XML and camt053 format endpoint until parameter is also required!

Field Description
since From which date you wish to query account statements. (Example since=2019-04-10%2B0300)
payout_id Statements for with this payout_id
page Which page to show. This is useful for frontend together with per_page parameter
per_page How many statements in one page. This is useful for frontend together with page parameter
until Until which date you wish to query account statements.

Returns all movements on your account, including service fees, payouts etc.

Parameters 'since’ and 'until’ can be expressed as date or timestamp. If no timezone is indicated then UTC is applied

See response example in right panel

You may also request the statement as an .xml file

HTTP REQUEST EXAMPLES

GET /v1/shop/accountstatements?payout_id=17041&since=2019-04-10%2B0300

GET /v1/shop/accountstatements/xml?since=2019-04-10%2B0300&until=2019-04-10%2B0300

GET /v1/shop/accountstatements/camt053?since=2019-04-10%2B0300&until=2019-04-10%2B0300

Try in API tester

Get fees

HTTP REQUEST

GET /v1/shop/fees

Returns accounting records that are not realted to transactions (monthly service fees).

$request = array( 'since' => date("Y-m-d", strtotime("-1 Months")) );
$statement = $MK->getShopFees($request);


    
Get fees response body

[
    {
        "object":"accounting",
        "amount":-10.0,
        "vat":-2.0,
        "id":"bf37a5d4-4b7f-4f44-900c-b288cd1562da",
        "created_at":"2019-04-30T01:00:37+0000"
    },
    {
        "object":"accounting",
        "amount":-10.0,
        "vat":-2.0,
        "id":"11c14967-6cbf-45bc-a618-bcc44e2b4d37",
        "created_at":"2019-04-30T20:30:07+0000"
    },
    {
        "object":"accounting",
        "amount":-5.0,
        "vat":-1.0,
        "id":"b460f282-0346-45be-b8e8-8a455cde17d6",
        "created_at":"2019-04-30T20:30:07+0000"
    }
]
Field Required Description
since Yes (when using api tester, no with Postman) From which date from you would like to query fees.
until No Until which date you would like to query fees to.
page No Which page to show. This is useful for frontend together with per_page parameter
per_page No How many statements in one page. This is useful for frontend together with page parameter

Try in API tester

HTTP REQUEST EXAMPLE

GET /v1/shop/fees?since=2019-04-10%2B0300

Transaction

Create transaction


$reqbody = array(
        'transaction' => array(
            'amount' => '75.95',
            'currency' => 'EUR',
            'reference' => '123abc'
            ),
        'customer' => array(
            'ip' => '10.128.96.76',
            'country' => 'ee',
            'locale' => 'en'
            ),
        'app_info' => array(
            'module' => 'WooCommerce',
            'module_version' => '3.4.2',
            'platform' => 'Wordpress',
            'platform_version' => '6.1'
            )
        );
$transaction = $MK->createTransaction($_POST);


Example JSON body minimal fields

{
    "transaction":{
        "amount":"75.95",
        "currency":"EUR",
        "reference":"123abc"
    },
    "customer":{
        "ip":"10.128.96.76",
        "country":"ee",
        "locale":"en"
    },
    "app_info":{
        "platform":"Wordpress"
    }
}

Example JSON all fields

{
    "transaction":{
        "amount":"75.95",
        "currency":"EUR",
        "reference":"123abc",
        "merchant_data":"Internal Order ID: 321",
        "recurring_required":"false",
        "transaction_url": {
            "return_url": {
                "url": "https://example.com/return_url",
                "method": "POST"
            },
            "cancel_url": {
                "url": "https://example.com/cancel_url",
                "method": "POST"
            },
            "notification_url": {
                "url": "https://example.com/notification_url",
                "method": "POST"
            }
        }
    },
    "customer":{
        "email":"mk.test@maksekeskus.ee",
        "ip":"10.128.96.76",
        "country":"ee",
        "locale":"en"
    },
    "app_info":{
        "module":"WooCommerce",
        "module_version":"3.2.0",
        "platform":"Wordpress",
        "platform_version":"5.1"
    }
}

HTTP REQUEST

POST /v1/transactions

To create a new transaction simply provide a JSON object containing the required attributes for the new transaction. When creating a new transaction, an embedded payment_methods list is returned, containing the available payment methods for making a payment for this transaction. Transaction amount and currency are required. Transaction reference max-length is 20 characters.Customer ip is required. Customer country must be passed as an alpha-2 code according to ISO 3166-1. Customer locale must be passed as an alpha-2 code according to ISO 639-1. Transaction_url - optionalEach shop has its set of urls manageable in Mercant Portal under the API settings. You can optionally over-ride these urls when creating the transaction. If specified then full set must be provided (return_ur, cancel_url, notification_url)

Customer object

Field Required Description
country No(Default will be chosen if not provided) ISO 3166 country code List of ISO 3166 country codes
email; No Customer email.
locale No(Default will be chosen if not provided) ISO 639-1 locale code List of ISO 639-1 locale codes
ip Yes Customer IP address.

Transaction object

Field Required Description
amount Yes Transaction amount
currency Yes Transaction currency
id No Transaction ID
merchant_data No Use this to pass additional data. It will be available in API and displayed in merchant portal but not in callback messages.
recurring_required No true/false. If true payment can be done only with recurring card payment.
reference No Set a reference for the transaction.
cancel_url, notification_url, return_url No Each shop has its set of urls manageable in Mercant Portal under the API settings You can optionally over-ride these urls when creating the transaction It might be handy at some e-commerce platforms where otherwise it is difficult to determine previous context (i.e. user language) Or situation when multiple developers are working on integration of one shop on their local work stations. Be careful to provide correct urls, with protocol (i.e. https://myshop.com/returnhandler/). We reccommend to use POST method. If already, then you have to specify full set - you can not pass just one of the 3 urls (though they can be equal)
     
     

app_info object

Not required but recommended: used for identification of software for debugging and statistics

Field Required Description
module No Module name, that the request is sent from. (Up to 64 characters)
module_version No Module version in use. (Up to 64 characters)
platform Yes Platform name, that the request is sent from. (Up to 64 characters)
Required only if app_info is used in the request
platform_version No Platform version in use. (Up to 64 characters)

Try in API tester

Get transaction

$transaction = $MK->getTransaction($transaction_id);

HTTP REQUEST

GET /v1/transactions/{id}

Field Description
id Transaction ID you get from here: Create transaction

Try in API tester

HTTP RESPONSE

JSON: Transaction Object

Get transaction statement

$transaction = $MK->getTransactionStatement($transaction_id);

HTTP REQUEST

GET /v1/transactions/{id}/statement

Field Description
id Transaction ID you get from here: Create transaction

Try in API tester

HTTP RESPONSE

JSON: Transaction Object

Get transaction list

$request = array( 'since' => date("Y-m-d", strtotime("-1 Months")) );
$transaction = $MK->getTransactions($request);

HTTP REQUEST

GET /v1/transactions

Field Description
since From which date you wish to query transactions. (Example since=2019-04-10%2B0300)
until Until which date you wish to query account transactions.
completed_since Transactions in completed status from the date (Example completed_since=2019-04-10%2B0300)
completed_until Transactions in completed status to the date (Example completed_until=2019-04-10%2B0300)
refunded_since Transactions in refunded status from the date (Example refunded_since=2019-04-10%2B0300)
refunded_until Transactions in refunded status to the date (Example refunded_until=2019-04-10%2B0300)
status One or more transaction status. (Example status=approved%2Ccompleted)
page Which page to show. This is useful for frontend together with per_page parameter
per_page How many statements in one page. This is useful for frontend together with page parameter

Try in API tester

HTTP RESPONSE

JSON: array of Transaction Objects

HTTP REQUEST EXAMPLE

GET /v1/transactions?since=2019-04-10%2B0300&status=approved%2Ccompleted

Add merchant data to transaction

Merchant data can be overwritten. New request overwrites and replaces the old merchant data.

  
    $transaction_id = '0368156c-...-282f7eada86a';
    $request_body = array('merchant_data' => 'my new metadata');

    $transaction = $MK->addTransactionMeta($transaction_id, $request_body);

HTTP REQUEST

POST /v1/transactions/{transaction_id}/addMeta

Try in API tester

HTTP RESPONSE

JSON: Transaction Object

HTTP REQUEST EXAMPLE

POST /v1/transactions/f8c02f00-7e1e-409e-9fd5-b0986ad7f602/addMeta

Create payment

$request = array(
    'token' => '6385f130-8e5a-409a-a88b-ac0eefe1467e'
);

$payment = $MK->createPayment($transaction_id, $request);


Example JSON request body

{
    "token": "2d1abacb-de54-4b2f-94c7-35230d0c6289"
}

HTTP REQUEST

POST /transactions/{id}/payments

You create payment in the flow of Recurring Credit Card Payment. In context of bank-link payments flow the 'payment’ creation operation is irrelevant.

Try in API tester

Refund

Integration overview

Partial refund with Inbank Slice

Partial refunding flow with Inbank Slice

  1. Customer contacts Merchant for Refunding.
  2. Merchant is clicking on 'Refund' in Merchant Portal and makes partial refund.
  3. MK System sends out e-mail to Customer to request Customer IBAN for refunding. MK System sends out up to 3 e-mail notification, in case Customer is not responding.
  4. Customer submits his IBAN for refunding.
  5. MK System makes balance transfer from Merchant account to MK account and makes payout to customer account.
  6. MK System sends partial refunding notification e-mail to Inbank.

If Customer never replies to MK IBAN request message, then the process ends after 3 e-mail requests are sent out to customer.

Full refund with Inbank Slice

Full refunding flow with Inbank Slice

  1. Customer contacts Merchant for Refunding.
  2. Merchant is clicking on 'Refund' in Merchant Portal and makes full refund.
  3. and 4. MK System makes virtual balance transfer between Merchant account and MK account and virtual balance transfer between MK account and Inbank account. With payment MK System sends refunding payment status to hire purchase provider. Merchant sees refunding transaction in Refunding compartment.

Payout to customer is done by Inbank.

Refunding with banklinks and credit card payment

Refunding flow with banklinks and credit card payments

  1. Customer contacts Merchant for Refunding.
  2. Merchant is clicking on 'Refund' in Merchant Portal and makes full or partial refund.
  3. MK System makes virtual balance transfer between Merchant account and MK account. Payout is done from MK account to customer account.

Refunding in case of hire purchase provider

Full refunding flow with hire purchase provider Liisi, Mokilizingas and Moki3

  1. Customer contacts Merchant for Refunding.
  2. Merchant is clicking on 'Refund' in Merchant Portal and makes full refund.
  3. MK System makes virtual balance transfer between Merchant account and MK account and payout to hire purchase provider account.

Payout to customer is made by hire purchase provider.

Create refund

$request = array(
    'amount' => '4.12',
    'comment' => 'broken package compensation',
    'app_info' => array(
      'module' => 'WooCommerce',
      'module_version' => '3.2',
      'platform' => 'Wordpress',
      'platform_version' => '5.1'
    )
);

$payment = $MK->createRefund($transaction_id, $request);


Example request body

{
  "amount":"5",
  "comment":"Refund reason",
  "app_info":{
    "module":"WooCommerce",
    "module_version":"3.2.0",
    "platform":"Wordpress",
    "platform_version":"5.1"
  }
}

HTTP REQUEST

POST /v1/transactions/{id}/refunds

Note that you should verify state of the refund in the response. You may be returned 200 response (resource created) but it's state may be FAILED. While the refund is in state SENT its amount is reserved on shop's account. You need sufficent balance on the account to make refunds. Take a look at the refund states here: Refund states

Field Required Description
amount Yes Amount of the refund.
comment Yes Comment for the refund.

app_info object

Not required but recommended: used for identification of software for debugging and statistics

Field Required Description
module No Module name, that the request is sent from. (Up to 64 characters)
module_version No Module version in use. (Up to 64 characters)
platform Yes Platform name, that the request is sent from. (Up to 64 characters)
Required only if app_info is used in the request
platform_version No Platform version in use. (Up to 64 characters)

Try in API tester

Get refund

$payment = $MK->getRefund($refund_id);

HTTP REQUEST

GET /v1/refunds/{$refund_id}

Field Description
id Refund ID you get from here: Create refund

Try in API tester

Get refund list

$payment = $MK->getRefunds($refund_id);

HTTP REQUEST

GET /v1/refunds

Field Description
since From which date you wish to query refunds. (Example since=2019-04-10%2B0300)
until Until which date you wish to query refunds.
status One or more transaction status. (Example status=approved%2Ccompleted)
page Which page to show. This is useful for frontend together with per_page parameter
per_page How many statements in one page. This is useful for frontend together with page parameter

Try in API tester

Destinations

Get shipment destinations


    
Example request

    {
      "carriers": [
        "OMNIVA"
      ],
      "countries": [
        "EE"
      ],
      "types": [
        "PO"
      ]
    }

    
Example response body

  [
    {
        "carrier": "OMNIVA",
        "type": "PO",
        "name": "Abja-Paluoja postipunkt",
        "city": "Mulgi vald",
        "country": "EE",
        "availability": "E-R 9.00-18.00; L 9:00-14:00; P suletud",
        "tempServiceHours": "10.06-10.08 avatud: E-R 9:00-17:00; L 9:00-14:00; P suletud;",
        "tempServiceHoursUntil": "10.08.2019",
        "provider": "OMNIVA",
        "id": "69494",
        "address": "Pärnu maantee 21",
        "zip": "69494",
        "x": "58.1261506146408",
        "y": "25.353927148133"
    },
    {
        "carrier": "OMNIVA",
        "type": "PO",
        "name": "Adavere postipunkt",
        "city": "Põltsamaa vald",
        "country": "EE",
        "availability": "E-P 9:00-19:00",
        "provider": "OMNIVA",
        "id": "48094",
        "address": "Tallinna maantee 6",
        "zip": "48094",
        "x": "58.7059373138417",
        "y": "25.8996412135384"
    }
  ]

HTTP REQUEST

Returns a list of possible delivery destinations based on the filter set with the fields below.

POST /v1/shipments/destinations

Field Required Description
carries No List of carries, if blank shows all. OMNIVA, (SMARTPOST, DPD, OMNIVA_LV, PASTA_LV, OMNIVA_LT)
countries No List of ISO 3166 country codes
Types No APT = Automated parcel terminal, PO = Post office, PUP = Pickup point

Try in API tester

Shipments

Create shipments



  
Example request

  {
      "credentials":[
          {
              "carrier":"SMARTPOST",
              "apiKey":"your_apiKey_smartpost"
          },
          {
              "carrier":"OMNIVA",
              "username":"your_uername_omniva",
              "password":"your_psw_omniva"
          },
          {
              "carrier":"DPD",
              "username":"your_uername_dpd",
              "password":"your_psw_dpd"
          }
      ],
      "orders":[
          {
              "orderId":"order 12345",
              "carrier":"SMARTPOST",
              "destination":{
                  "destinationId":"101"
              },
              "recipient":{
                  "name":"Test Robot",
                  "phone":"37258875115",
                  "email":"mk.test@maksekeskus.ee"
              },
              "sender":{
                  "name":"myTestShop.com",
                  "phone":"+37258875115",
                  "email":"support@mytestshop.com",
                  "country": "EE",
                  "county": "Harjumaa",
                  "city": "Tallinn",
                  "street": "Viru-vääna 8",
                  "postalCode":"69400"
              }
          },
          {
              "orderId":"order 12346",
              "carrier":"OMNIVA",
              "destination": {
                "postalCode": "96047",
                "country": "EE",
                "county": "Harjumaa",
                "city": "Tallinn",
                "street": "Vana Lõuna 12"
              },
              "recipient":{
                  "name":"Test Robot",
                  "phone":"37258875115",
                  "email":"mk.test@maksekeskus.ee"
              },
              "sender":{
                  "name":"myTestShop.com",
                  "phone":"37258875115",
                  "email":"support@mytestshop.com",
                  "postalCode":"69400"
              }
          }
      ],
      "app_info":{
        "module":"WooCommerce",
        "module_version":"3.2.0",
        "platform":"Wordpress",
        "platform_version":"5.1"
      }
  }

  
Example request with TMS

  {
      "credentials":[],
      "orders":[
          {
              "orderId":"order 12346",
              "carrier":"OMNIVA",
              "destination": {
                "postalCode": "96047",
                "country": "EE",
                "county": "Harjumaa",
                "city": "Tallinn",
                "street": "Vana Lõuna 12"
              },
              "recipient":{
                  "name":"Test Robot",
                  "phone":"37258875115",
                  "email":"mk.test@maksekeskus.ee"
              },
              "sender":{
                  "name":"myTestShop.com",
                  "phone":"37258875115",
                  "email":"support@mytestshop.com",
                  "postalCode":"69400"
              }
          }
      ],
      "app_info":{
        "module":"WooCommerce",
        "module_version":"3.2.0",
        "platform":"Wordpress",
        "platform_version":"5.1"
      }
  }

  
Example response body

  {
    "manifests":[
        "https://static.test.maksekeskus.ee/mf/201908050iAIhZTAw5y8MNkG0muTz4o1nqSI19nt.pdf"
    ],
    "shipments":[
        {
            "orderId":"order 12346",
            "shipmentId":"CC320669628EE"
        },
        {
            "orderId":"order 12348",
            "shipmentId":"CC320669631EE"
        }
    ]
}

HTTP REQUEST

Generates Shipments in the carrier systems (Itella, Omniva, DPD..) Requires your own credentials at these systems provided as input or the use of TMS. Returns shipmentId(s).

POST /v1/shipments

While using MakeCommerce's Transport Mediation Service (TMS), the credentials object is not required, or it can be empty. TMS currently supports Omniva and DPD orders.

Credentials object

Field Required Description
carrier Yes Potential values: OMNIVA, DPD, OMNIVA_LV, PASTA_LV, OMNIVA_LT
username Yes Your carrier username
password Yes Your carrier password

Credentials object for Smartpost

Field Required Description
carrier Yes Potential values: SMARTPOST
apiKey Yes Your Smartpost API Key

NB! The use of the username and password fields for Smartpost are deprecated. Registering shipments or labels in Smartpost now requires the apiKey.

Orders object

Field Required Description
orderId Yes Order id which to create the shipment for.
carrier Yes Potential values: OMNIVA, SMARTPOST, DPD, OMNIVA_LV, PASTA_LV, OMNIVA_LT
services -> serviceType No Potential values (Omniva only):
QK: courier -> courier
QP: post office -> courier
PK: parcel machine -> courier
* For courier serviceType is required

PA: parcel machine -> parcel machine
PU: courier -> parcel machine
PV: post office -> parcel machine
PO: parcel machine -> post office

* default: PA
destinationId Use this with ID or DestinationID from Get shipment destination
destination(postalCode, country, county, city, street) Use this or destinationId Destinations postal code, country(List of ISO 3166 country codes), county, city and street.
Recipient(name, phone, email) Yes Recipient name, phone number and email address
Sender(name, phone, email, country, county, city, street, postalCode)
OR
Sender(name, phone, email, postalCode) 		Yes Senders name, phone number, email address, country, county, city, street name and postalcode.
OR
Senders name, phone number, email address and postalcode, where postalCode is a parcel machine ID (except for DPD - can be either).

app_info object

Not required but recommended: used for identification of software for debugging and statistics

Field Required Description
module No Module name, that the request is sent from. (Up to 64 characters)
module_version No Module version in use. (Up to 64 characters)
platform Yes Platform name, that the request is sent from. (Up to 64 characters)
Required only if app_info is used in the request
platform_version No Platform version in use. (Up to 64 characters)

Try in API tester

Get label formats



  
Example response body

  [
    "A4",
    "A4_FULL_PAGE",
    "A5",
    "A6_FULL_PAGE"
  ]

HTTP REQUEST

Returns an array of all possible label print variants / formats

* LP Express currently only supports A4 - 3 per page. printFormat is ignored for create labels request

GET /v1/shipments/labels/formats


Try in API tester

Create labels



    
Example request

  {
      "credentials":[
          {
              "carrier":"OMNIVA",
              "username":"45041",
              "password":"27T<9\\"m^F1"
          }
      ],
      "orders":[
          {
              "orderId":"order 12346",
              "carrier":"OMNIVA",
              "services":{
                "serviceType":"PA"
              }
              "destination":{
                  "destinationId":"9950"
              },
              "recipient":{
                  "name":"Test Robot",
                  "phone":"37258875115",
                  "email":"mk.test@maksekeskus.ee"
              },
              "sender":{
                  "name":"myTestShop.com",
                  "phone":"37258875115",
                  "email":"support@mytestshop.com",
                  "city":"Riga",
                  "street":"brivibas iela",
                  "country":"LV",
                  "postalCode":"911"
              },
              "shipmentId":"CE441412466EE"
          }
      ],
      "app_info":{
        "module":"WooCommerce",
        "module_version":"3.2.0",
        "platform":"Wordpress",
        "platform_version":"5.1"
      },
      "printFormat":"A4"
  }

    
Example request with TMS

  {
      "credentials":[],
      "orders":[
          {
              "orderId":"order 12346",
              "carrier":"OMNIVA",
              "services":{
                "serviceType":"PA"
              }
              "destination":{
                  "destinationId":"9950"
              },
              "recipient":{
                  "name":"Test Robot",
                  "phone":"37258875115",
                  "email":"mk.test@maksekeskus.ee"
              },
              "sender":{
                  "name":"myTestShop.com",
                  "phone":"37258875115",
                  "email":"support@mytestshop.com",
                  "city":"Riga",
                  "street":"brivibas iela",
                  "country":"LV",
                  "postalCode":"911"
              },
              "shipmentId":"CE441412466EE"
          }
      ],
      "app_info":{
        "module":"WooCommerce",
        "module_version":"3.2.0",
        "platform":"Wordpress",
        "platform_version":"5.1"
      },
      "printFormat":"A4"
  }

  
Example response body

  {
    "labelUrl":"https://static.test.maksekeskus.ee/lbl/20190805tshY9Vf3Q6OO2PR1UJByFShffc6DeWhi.pdf"
  }

HTTP REQUEST

Generates Parcel Labels based on Shipments created in the carrier systems (Itella, Omniva, DPD..) Requires your own credentials at these systems provided as input or the use of TMS. Returns url to generated label(s) in .pdf format.

POST /v1/shipments/createlabels

While using MakeCommerce's Transport Mediation Service (TMS), the credentials object is not required, or it can be empty. TMS currently supports Omniva and DPD orders.

Credentials object

Field Required Description
carrier Yes Potential values: OMNIVA, DPD, OMNIVA_LV, PASTA_LV, OMNIVA_LT
username Yes Your carrier username
password Yes Your carrier password

Credentials object for Smartpost

Field Required Description
carrier Yes Potential values: SMARTPOST
apiKey Yes Your Smartpost API Key

NB! The use of the username and password fields for Smartpost are deprecated. Registering shipments or labels in Smartpost now requires the apiKey.

Orders object

Field Required Description
orderId Yes Order id which to create the shipment for.
carrier Yes Potential values: OMNIVA, SMARTPOST, DPD, OMNIVA_LV, PASTA_LV, OMNIVA_LT
Service (serviceType)
destinationId Use this with ID or DestinationID from Get shipment destination
destination(postalCode, country, county, city, street) Use this or destinationId Destinations postal code, country(List of ISO 3166 country codes), county, city and street.
Recipient(name, phone, email) Yes Recipient name, phone number and email address
Sender(name, phone, email, postalCode) Yes Senders name, phone number, email address and postal code.
shipmentId Yes shipmentId from Create shipments
printFormat Yes Page size

app_info object

Not required but recommended: used for identification of software for debugging and statistics

Field Required Description
module No Module name, that the request is sent from. (Up to 64 characters)
module_version No Module version in use. (Up to 64 characters)
platform Yes Platform name, that the request is sent from. (Up to 64 characters)
Required only if app_info is used in the request
platform_version No Platform version in use. (Up to 64 characters)

Try in API tester

Tracking Service



    
Examples of use

    Test environment request:
    https://tracking.test.makecommerce.net/CE400031817EE?carrier=omniva&dst=ee&lang=en
    Redirects to:
    https://minu.omniva.ee/track/CE400031817EE/?language=en

    Live environment request:
    https://tracking.makecommerce.net/CE400031817EE?carrier=omniva&dst=ee&lang=et
    Redirects to:
    https://minu.omniva.ee/track/CE400031817EE/?language=et

REDIRECTION

MakeCommerce's tracking service provides a service that allows a simple redirection for locating different carriers' packages.
This removes the need for keeping any tracking links locally, provides an easy implementation for tracking shipments and allows for realtime updates.

https://tracking.makecommerce.net/{shipmentId}?carrier=&dst=&lang=

Parameter Required Description
shipmentId Yes Shipment ID that is used to track the package
carrier Yes Potential values: omniva, smartpost, dpd, lpexpress
dst No Destination country of the shipment in order to display that country's page. Values: ee, lv, lt, fi
lang No Which language to display. Values: en, et, lv, lt, ru. Without translations: fi, sv

The service will use default dst and lang values when they are not provided.