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.
mTasku Whole section for mTasku flow. There you can find flow description and some code snippets for mTasku implementation.
Notifications Section about notifications.

First steps

Integration modules supported

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

4012001037141112 | expiration date: any in future | CVC: anything is valid

0-amount Authorization, "Save Card functionality"

Visa

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)

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.

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.

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 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' => '12.95',
            'currency' => 'EUR',
            'reference' => 'order 123'
            ),
        'customer' => array(
            'email' => 'mk.test@somedomain.xyz',
            'ip' => '80.235.22.114',
            'country' => 'ee',
            'locale' => 'et'
            )
        );
$transaction = $MK->createTransaction($_POST);

Example JSON body minimal fields

{ "transaction":{ "amount":"12.95", "currency":"EUR", "reference":"123abc", "merchant_data":"" }, "customer":{ "email":"mk.test@maksekeskus.ee", "ip":"80.235.22.114", "country":"ee", "locale":"et" } }

Example JSON all fields

{ "customer": { "country": "ee", "email": "mk.test@maksekeskus.ee", "ip": "80.235.22.114", "locale": "et" }, "transaction": { "amount": "99.99", "currency": "EUR", "id": "1", "merchant_data": "Merchant Data", "recurring_required": true, "reference": "reference", "transaction_url": { "cancel_url": { "method": "POST", "url": "CANCELURL" }, "notification_url": { "method": "POST", "url": "CALLBACKURL" }, "return_url": { "method": "POST", "url": "RETURNURL" } } } }

Example response body

{ "_links": { "Pay": { "href": "https://api-test.maksekeskus.ee/v1/transactions/b8a8cf11-69dd-419b-ba34-1e27cdf4a7df/payments" }, "self": { "href": "https://api-test.maksekeskus.ee/v1/transactions/b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" } }, "amount": 12.95, "country": "ee", "created_at": "2019-08-01T12:53:41+0000", "currency": "EUR", "customer": { "country": "ee", "created_at": "2019-08-01T12:53:41+0000", "email": "mk.test@maksekeskus.ee", "id": "b206643d-2bf6-4d71-b56e-39a08e118ac0", "ip": "80.235.22.114", "ip_country": "ee", "locale": "et", "name": "b206643d-2bf6-4d71-b56e-39a08e118ac0", "object": "customer" }, "id": "b8a8cf11-69dd-419b-ba34-1e27cdf4a7df", "method": null, "object": "transaction", "payment_methods": { "banklinks": [ { "country": "ee", "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/swedbank.png", "name": "swedbank", "url": "https://payment-test.maksekeskus.ee/banklink.html?method=EE_SWED&trx=b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" }, { "country": "ee", "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/seb.png", "name": "seb", "url": "https://payment-test.maksekeskus.ee/banklink.html?method=EE_SEB&trx=b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" }, { "country": "ee", "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/lhv.png", "name": "lhv", "url": "https://payment-test.maksekeskus.ee/banklink.html?method=EE_LHV&trx=b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" }, { "country": "ee", "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/luminor.png", "name": "nordea", "url": "https://payment-test.maksekeskus.ee/banklink.html?method=EE_NORDEA&trx=b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" }, { "country": "ee", "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/coop.png", "name": "krediidipank", "url": "https://payment-test.maksekeskus.ee/banklink.html?method=EE_KREDIIDI&trx=b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" }, { "country": "ee", "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/pocopay.png", "name": "pocopay", "url": "https://payment-test.maksekeskus.ee/banklink.html?method=EE_POCOPAY&trx=b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" }, { "country": "ee", "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/liisi_ee.png", "name": "liisi_ee", "url": "https://payment-test.maksekeskus.ee/banklink.html?method=EE_LIISI_EE&trx=b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" } ], "cards": [ { "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/visa.png", "name": "visa" }, { "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/mastercard.png", "name": "mastercard" }, { "logo_url": "https://static-test.maksekeskus.ee/img/channel/lnd/maestro.png", "name": "maestro" } ], "cash": [], "other": [ { "name": "redirect", "url": "https://payment-test.maksekeskus.ee/pay.html?trx=b8a8cf11-69dd-419b-ba34-1e27cdf4a7df" } ] }, "recurring_required": false, "reference": "123abc", "status": "CREATED", "type": null }

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 3166 country 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)
     
     

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

Create payment

$request = array(
    'amount' => '4.12',
    'currency' => 'EUR',
    'token' => '6385f130-8e5a-409a-a88b-ac0eefe1467e'
);

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

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

Create refund

$request = array(
    'amount' => '4.12',
    'comment' => 'broken package compensation'
);

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

Example request body

{ "amount":"5", "comment":"Refund reason", "email":"" }

HTTP REQUEST

POST /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.
email Only for finnish bank-link payments. Email of the original payer.

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", "username":"your_username_smartpost", "password":"your_psw_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", "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" } } ] }

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. Returns shipmentId(s).

POST /v1/shipments

Credentials object

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

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
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 postalcode.

Try in API tester

Create labels



    

Example request

{ "credentials":[ { "carrier":"OMNIVA", "username":"45041", "password":"x1bcN0x0" } ], "orders":[ { "orderId":"order 12346", "carrier":"OMNIVA", "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" } ], "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. Returns url to generated label(s) in .pdf format.

POST /v1/shipments/createlabels

Credentials object

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

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
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

Try in API tester

Simple checkout

Simple checkout overview

Instead of your store’s normal checkout page, customers will temporarily be directed to the Simple Checkout system, where the customer can link their social media accounts to fill in their information automatically. Our system is already being used by many online stores in the Baltics and if your customer has used Simple Checkout with another online store before, their data will already be prefilled. Only at the very first encounter with Simple Checkout it takes a few extra seconds for the customer to link their social media account.

Simple checkout is currently supported by WooCommerce, PrestaShop and OpenCart platforms. Manuals for those can be found at the bottom of Simple Checkout Manuals

These platform plugins will cover all the technical parts of the Simple Checkout. If you wish to use it without these platforms then read the next chapter.

Create cart


  

Example request

{ "cartRef": "cart 1256", "pluginUrls": { "cartToOrder": "https://developer.maksekeskus.ee/cartToOrder.php", "calculateShipment": "https://developer.maksekeskus.ee/calculateshipment", "tos": "https://developer.maksekeskus.ee/tos" }, "amount": "1.29", "currency": "EUR", "sourceCountry": "EE", "locale": "et", "shipmentMethods": [ { "countries": [ "EE" ], "carrier": "SMARTPOST", "type": "APT", "name": "SmartPOST pakiautomaat", "methodId": "parcelmachine_smartpost:48", "amount": "2.99" }, { "countries": [ "EE" ], "type": "OTH", "name": "Tulen ise järgi", "methodId": "local_pickup:57", "amount": "0" }, { "countries": [ "EE" ], "type": "COU", "name": "Kuidagi saadame su aadressile (vbl kulleriga)", "methodId": "flat_rate:59", "amount": "15" } ] }

Example response body

{ "_links":{ "self":{ "href":"https://api-test.maksekeskus.ee/v1/carts/b6ae0a9f-f45e-4e82-9aec-2ab0bf29df61" } }, "id":"b6ae0a9f-f45e-4e82-9aec-2ab0bf29df61", "object":"cart", "scoUrl":"https://payment-test.maksekeskus.ee/sco.html?id=b6ae0a9f-f45e-4e82-9aec-2ab0bf29df61" }

HTTP REQUEST

POST /v1/carts

How to implement Simple Checkout without using plugins made for WooCommerce, PrestaShop and OpenCart platforms?

  1. Create a cart request (look at the example in the "Examples" tab)
  2. Choose which shipment methods you want to offer and for what prices
  3. You need to have the cartToOrder endpoint(add it to the request as well), which will capture carts info, save it somewhere(in database for example)
  4. Wait for info about payment which will be sent to the return url More info about return urls
  5. If payment has been received from the client find the carts info that was sent to your server based on the succesful payment info and then create a shipment using our API or using third-party carrier API straightly.
  6. Take a look at Shipments and Destinations for more info about using our API to fulfill your order.

  7. IMPORTANT: To do everything automatically you need to only offer carriers which you have contracts for, because Shipments and Destinations require credentials for those service providers.

sco sequence diagram

From the response open "scoUrl" link to see the created cart.

Field Description
cartRef Cart reference number or symbol.
cartToOrder Your callback url for Simple Checkout. Simple Checkout will send the user's cart info there. This endpoint must respond with status code 200 and empty JSON.
calculateShipment Shipment calculation endpoint.
tos Link to your TOS page.
amount Amount of the transaction.
currency Transaction currencry
sourceCountry Source country code (example: "EE")
locale ISO 639-1 locale code List of ISO 3166 country codes
shipmentMethods Which shipment methods does this cart accept. Look at the example in the examples tab.
carrier Example values: OMNIVA, SMARTPOST, DPD, OMNIVA_LV
type Example values: APT - (Parcel machine), COU - (Courier), OTH - (For local pickup)

Try in API tester