Mash eCommerce API

Mash eCommerce API for pay by invoice / parts.
Overview

Contact, available platform integrations, API overview and update policy.

Contact

For more information about Mash, see https://www.mash.com/

If you need API keys for testing or have other integration related questions, please contact integration-support@mash.com

Include your contact information and any additional information about the integrated platform and the intended use of Mash services. Thanks!

Platforms

eCommerce platforms and payment gateways that support Mash payment methods include:

  • Magento 1
  • Magento 2
  • Shopify
  • ProsperCart
  • Vilkas
  • MyCashFlow
  • Whitestone
  • Finqu
  • Valmiskauppa
  • Prestashop
  • Verifone
  • Bambora
  • Checkout Finland
API overview

Mash eCommerce REST API is divided to two parts:

  • Orders and invoicing: Pay by invoice and part payments service. This part of the service typically applies to eCommerce e.g. web shop integrations.
  • Registrations and reports: Merchant registration and reporting service. This part of the service typically applies to payment service providers or eCommerce platform providers.

In addition, these web site integration points are needed for most eCommerce integrations:

Typical web shop usage of the API consists of these steps:

  1. Get pricing information via REST API and render the options to customer. See also Payment plan calculator.
  2. After the customer has selected the payment option, create order.
  3. If returned status is Pending, perform redirection to Mash website.
  4. After redirection back, get order information and verify the Order status is Approved .
  5. When products are delivered, charge order.
API versioning and update policy

The current API version is 1.2. Main API version will change if backwards incompatible changes are done, and the new version will be available in a separate URL.

Clients should expect that backwards compatible updates are done to API without separate notice. These changes are limited to:

  • Adding new API methods
  • Adding new fields to JSON objects
  • Adding new values to enumerations
Merchant extranet

Merchants can track invoices and orders in merchants extranet.

All the information needed to access the extranet is retrieved when a new merchant is added (Add merchant). Store your credentials in a secure place.

General

API headers, responses and error codes.

Headers
Authorization
string required
Applied to all operations

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required
Applied to all operations

Accept application/json

Example:
application/json
Content-Type
string required
Applied to all operations

Content type is application/json

Example:
application/json
Responses
400 Error

Generic error response

Body
Object
errorCode
number

Error code

Example:
12345
message
string

Description

Example:
Description of the error
localizedMessage
string

Message is translated based on the locale sent with the order. If translation fails, message is returned with default language.

Example:
Virheilmoitus suomeksi.
Error codes

Common errors

  • 10000 Invalid API keys (http 401)
  • 10001 Unauthorized request (http 403)
  • 10002 Badly formatted request (http 400)

Order and invoice management errors (http 400)

  • 20001 Error occurred when creating the order number. Please retry your order.
  • 20002 Order does not exist.
  • 20009 Total order amount must be more than 0 euros. Please check your order and retry.
  • 20010 You chose invoice as your payment method. You can pay it in instalments when receiving the invoice.
  • 20012 The total order amount cannot be negative.
  • 20013 Payment plan not possible or could not be created.
  • 20014 Refund cannot be done. Either the order is more than 40 days old, it has not been delivered or it cannot be found.
  • 20015 Order is not in Pending or Approved state.
  • 20016 Please select the number of instalments.
  • 20017 The supplied phone number is already in use.
  • 20018 The supplied email address is already in use.
  • 20019 Item articleId is not unique.
  • 20020 Unexpected error occurred. Please try again.
  • 20021 Number of instalments is incorrect. Please select another option.
  • 20022 In order to pay by invoice or instalments the total order amount must be 10 euros or more.
  • 20023 In order to pay by invoice or instalments the total order amount must be less than 10 000 euros.
  • 20024 Incorrect order status.
  • 20025 Invoice or instalments payment methods are unavailable for this order. Please select another payment option.
  • 20026 Maximum open balance with Mash payment options is 10000 euros. This order will exceed this limit.
  • 20027 Unfortunately you are not able to pay with Mash payment options right now.
  • 20028 Your credit limit is insufficient for this purchase. You can increase your credit limit by signing in and filling the credit application here: www.euroloan.fi/ostokset
  • 20050 Incorrect social security number input. Please try again.
  • 20051 To continue please accept terms.
  • 20052 Please select a method of payment.
  • 20053 Merchant does not exist. Please check the merchant number and retry.
  • 20054 Unexpected error occurred. Please contact customer service.
  • 20055 The amount of the order is too big.
  • 20056 Refund cannot be done. Order is not shipped or it is cancelled.
  • 20057 To continue please accept terms.
  • 20058 Address input does not match with official address. Please verify and try again.
  • 20059 Please verify your identity using secure authentication (TUPAS) if shipping to an address other than your official address.
  • 20060 Order does not contain requested item.
  • 20061 An order, shipping or invoice must contain at least one item. Check order item status for all order items!
  • 20062 Invalid email address.
  • 20063 The total order amount is too big or too small for payment plan.
  • 20064 Product, shipping or handling cannot be less than 0 euros.
  • 20065 The discount amount has to be negative (e.g. -10).
  • 20066 Number of units cannot be negative.
  • 20067 Corrections are not allowed when creating an order.
  • 20068 The correction is not possible. The order amount will become too big for this payment plan.
  • 20069 VAT percetange cannot have a negative value.
  • 20070 Incorrect business id input. Please try again.
  • 20071 The merchant already exists.
  • 20072 Merchant has already used this orderId.
  • 20073 Customer has already credit account and can’t create e-commerce account.
  • 20074 Refund order is not possible this way because the order has corrections. Please use a correction type item to change the order.
  • 20075 Payment plan already exists. Charge method not allowed.
  • 20076 Merchant is not active.
API endpoints

API endpoints for production and testing. Practical information for testing.

Production environment
Testing

Note about testing

Please use test environment for any API related testing. Live testing in production environment is not encouraged, as it requires using real identities. Note that test environment is cleaned regularly which may affect long-term testing.

SSNs for testing

Any formally valid SSN can be used for creating orders in test environment. Use the following method to generate test SSNs that will give expected credit decision results.

URLs for generating test SSN:

Finland:

Sweden:

TUPAS / BankID testing

After redirection to the authentication URL, a test SSN can be entered in “SSN-for-testing” input field. Clicking a bank logo emulates TUPAS / BankID authentication by skipping the bank redirection and processing the response similar to actual TUPAS / BankID.

Web site integration

Browser redirection and Javascript information.

Web frontend redirection

Created order may be Approved immediately, or set to Pending status. Pending orders require redirecting the customer to Mash site for additional credit check / authentication.

Perform browser redirect to “redirectionUrl” returned in OrderResult. Add these URL parameters:

  • okUrl: URL to return after authentication (please include the protocol - http / https)
  • cancelUrl: URL to return in the case of cancellation (please include the protocol - http / https)

Example:

After successful authentication Mash website redirects the browser back to okUrl.

Please note that order status has to be checked via REST API after returning to okUrl (see: Get order information), before the order can be charged.

Creating an invoice or payment plan charge will only be allowed if the order status is Approved.

Old redirection method below

Find the URL to redirect to under Production environment and Test environment.

Method: POST Form parameters:

  • merchantId: numeric identifier of the merchant
  • clientOrderId: client side order identifier
  • ssn: customer entered SSN (optional)
  • name: customer entered name (optional)
  • okUrl: URL to return after authentication
  • cancelUrl: URL to return in the case of cancellation
Payment plan calculator

Javascript based calculator is available as a light-weight alternative to REST API pricing method. It is recommended especially on pages that have multiple products with monthly prices. At checkout it is recommended to use API to get the payment plan prices.

Include the following javascript file in your project:

<script src="https://cdn.mash.com/ecommercescriptv1.js"></script>

In order to get the calculator for a certain amount use the following code:

var paymentPlan = new EL.eCommercePaymentPlan(amount);

paymentPlan.availablePaymentPlans is an array that contains all available payment plans for that amount.

Each object in the array has InstalmentCount, InstalmentAmount and TotalPrice. paymentPlan.smallestInstalmentPlan is the payment plan that has the smallest instalment amount

Examples:

Example 1:

var paymentPlan = new EL.eCommercePaymentPlan(2000);

paymentPlan.availablePaymentPlans is an array of 4 objects:

[ {"InstalmentAmount": 780.62, "InstalmentCount":3, "TotalPrice": 2336.29} ,{"InstalmentAmount": 421.45, "InstalmentCount":6, "TotalPrice": 2522.97} ,{"InstalmentAmount": 198.53, "InstalmentCount":12, "TotalPrice": 2376.53} ,{"InstalmentAmount": 110.41, "InstalmentCount":24, "TotalPrice": 2644.56} ]

paymentPlan.smallestInstalmentPlan contains: {"InstalmentAmount": 110.41, "InstalmentCount":24, "TotalPrice": 2644.56}

var smallestInstalment = paymentPlan.smallestInstalmentPlan.InstalmentAmount;

Example 2:

new EL.eCommercePaymentPlan(1000).smallestInstalmentPlan.InstalmentAmount returns 53.22

API Methods
Orders and invoicing

Methods for creating and invoicing orders. Create makes a credit check and cover reservation for the order, and charge activates it by creating and invoice or payment plan. Order can also be partially delivered.

GET /pricing
GET /personinfo
POST /orders
GET /orders/{orderId}
POST /orders/{orderId}/cancel
POST /orders/{orderId}/charge
POST /orders/{orderId}/refunds
Get pricing
GET /pricing

Authentication

Basic Auth

Get available pricing.

orderAmount is optional and must be at least 10€/10kr.

  • If orderAmount is given, matches the applicable payment plans based on amount and calculates the plan price.
  • If orderAmount is not provided, all available payment plan types are returned and can be used for calculating payment options.

Request parameters

merchantId
string required

Merchant identifier.

Example:
232423424
orderAmount
string optional

Total amount of the order.

If provided, it can’t be less than 10€ / 10kr.

Example:
1214.50

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Responses

200 OK
Body
Object
pricingUpdated
string

Pricing configuration last updated timestamp. yyyy-MM-dd HH:mm:ss

Example:
2018-12-12 09:25:29
invoice
Object

Invoice payment option.

invoicingFee
string

Fee for sending the invoice.

Example:
3.95
invoiceDue
string

Days between invoice date and due date.

Example:
14
paymentPlans

Payment plan options.

email
string

RFU

Example:
null
phone
string

RFU

Example:
null
Example 1
Example 2

Response with no errors

GET https://el-release.euroloan.fi/api/pricing?merchantId=232423424 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "pricingUpdated": "2019-02-06 00:00:00",
    "invoice": {
        "invoicingFee": 4.95,
        "invoiceDue": "3"
    },
    "paymentPlans": [
        {
            "id": "8",
            "installmentCount": 3,
            "initialFeeFixed": 0,
            "initialFeePercentage": 0,
            "notificationFeeFixed": 3.9,
            "notificationFeePercentage": 0,
            "interestRate": 19.9,
            "apr": 0,
            "fromAmount": 10,
            "toAmount": 10000,
            "pricingVersion": 0,
            "calculation": {
                "orderAmount": 0,
                "installmentAmount": 0,
                "totalAmount": 0,
                "initialFee": 0,
                "notificationFee": 0
            }
        },
        {
            "id": "9",
            "installmentCount": 6,
            "initialFeeFixed": 0,
            "initialFeePercentage": 0,
            "notificationFeeFixed": 3.9,
            "notificationFeePercentage": 0,
            "interestRate": 19.9,
            "apr": 0,
            "fromAmount": 10,
            "toAmount": 10000,
            "pricingVersion": 0,
            "calculation": {
                "orderAmount": 0,
                "installmentAmount": 0,
                "totalAmount": 0,
                "initialFee": 0,
                "notificationFee": 0
            }
        },
        {
            "id": "10",
            "installmentCount": 9,
            "initialFeeFixed": 0,
            "initialFeePercentage": 0,
            "notificationFeeFixed": 3.9,
            "notificationFeePercentage": 0,
            "interestRate": 19.9,
            "apr": 0,
            "fromAmount": 10,
            "toAmount": 10000,
            "pricingVersion": 0,
            "calculation": {
                "orderAmount": 0,
                "installmentAmount": 0,
                "totalAmount": 0,
                "initialFee": 0,
                "notificationFee": 0
            }
        }
    ],
    "email": null,
    "phone": null
}

Response with errors

GET https://fi.mash.com/api/pricing?merchantId=232423424&orderAmount=2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "errorCode": 20022,
    "message": "In order to pay by invoice or instalments the total order amount must be 10 euros or more.",
    "localizedMessage": "Jotta voit maksaa laskulla tai osamaksulla, ostoksesi arvon tulee olla 10 euroa tai enemmän."
}
Get person information
GET /personinfo

Authentication

Basic Auth

Get person information based on personId (SSN).

Request parameters

personId
string required

Person id to lookup the customer.

Example:
1980001010101

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Responses

200 OK
Body
Object
name
string

Name of the person

Example:
Maria Svensson
personId
string

Person identifier

Example:
1980001010101
officialAddress

Official address

firstName
string

RFU

Example:
null
lastName
string

RFU

Example:
null
alternativeAddress
string

RFU

Example:
null
Example 1
GET https://el-release.euroloan.fi/api/personinfo?personId=060764-603F HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Sakari Nieminen",
    "firstName": null,
    "lastName": null,
    "personId": "060764-603F",
    "officialAddress": {
        "address": "Birger Kaipiaisen tie 2",
        "zipCode": "07333",
        "city": "Enontekiö",
        "country": null
    },
    "alternativeAddress": null
}
Create order
POST /orders

Authentication

Basic Auth

Create a new order. Credit decision is done and credit reserved for the included order items.

Method is called when the customer has proceeded to pay the order with Mash and selected the payment option.

Resulting order status can be Approved, Pending or Denied.

Important: If the reponse contains redirectionUrl, you have to redirect the user to that url. Please follow the instructions provided on Web frontend redirection.

Notes

Common reasons for 20001 errors during the integration

  • ClientOrderId already exists on our db - this is a common issue during the integration. Please ensure the ClientOrderId is new
  • empty ClientOrderId - please ensure that ClientOrderId is valid
  • Invalid or missing data - please ensure that all mandatory fields are being sent and they respect the format specified on this documentation (eg: “orderPlaced”: "2020.10-26 14:47:09 " will fail with 20001)

Common reasons for 100001 errors during the integration proccess

  • non existing merchantId: please ensure that merchantId exists and its valid

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Request body

Object
merchantId
number

Merchant identifier provided by Mash.

Example:
23232323
merchantUser
MerchantUser nullable

If applicable, information about the user triggering the call.

merchantInfo
Merchant nullable

Detailed merchant information. Required for payment providers that do not register new merchants.

clientOrderId
string

Client side order identifier. This must be unique.

orderPlaced
string

Datetime when order was placed in ISO 8601 format.

Example:
2020-10-26T14:47:09Z
channel
string

Channel used in placing order.

Enumeration:
Web
Store
Helpdesk
Example:
Web
customer

Customer placing the order.

deliveryAddress

Delivery address where the good are sent to. Note: it is important that the deliveryAddress is the final delivery address and cannot be changed later in checkout. If this cannot be quaranteed, omit the deliveryAddress.

orderItems
Array of OrderItem

Order items list for reserving the credit. Either this or totalItems has to be provided.

totalItems
number nullable

Order total amount to reserve. This can be used as alternative to passing orderItems list, in which case the Charge call should always contain the full list of items.

paymentType

Selected payment type.

Example:
Invoice
installmentCount
number

Number of installments for the payment plan. Supported selection is 3,6,12,24. Note that available payment plans vary based on price range, check the pricing for availability. Mandatory parameter if paymentType is PaymentPlan.

Responses

200 OK
Example 1
Example 2
Example 3
Example 4
Example 5

Success

POST https://el-release.euroloan.fi/api/orders HTTP/1.1 

HTTP/1.1 200 OK 
Content-Type: application/json
{
    "merchantId": 17,
    "merchantUser": {
        "userId": "1",
        "storeId": "88",
        "deviceId": "99"
    },
    "clientOrderId": "1231233",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "channel": "Web",
    "customer": {
        "personId": "290284-6510",
        "name": "Teppo Testaaja",
        "email": "teppo.testaaja@mailinator.com",
        "mobile": "+358401111111",
        "clientCustomerId": "1233454",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI"
    },
    "deliveryAddress": {
        "address": "Pohjoinen Rautatiekatu 90",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "totalItems": 1,
    "paymentType": "Invoice",
    "installmentCount": 4
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": 8798,
    "clientOrderId": "1231233",
    "orderPlaced": "2019-02-07 14:46:57",
    "status": "Pending",
    "referenceNumber": null,
    "statusCode": 1,
    "paymentType": "Invoice",
    "paymentPlanTypeId": null,
    "customer": {
        "personId": "290284-****",
        "clientCustomerId": "1233454",
        "name": "Niemi Taneli",
        "email": "teppo.testaaja1@mailinator.com",
        "mobile": "0401111112",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI",
        "identificationType": 0,
        "identificationNumber": null
    },
    "deliveryAddress": {
        "address": "Pohjoinen Rautatiekatu 90",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": null
    },
    "invoicingAddress": {
        "address": "Tornikatu 1 V 1",
        "zipCode": "11199",
        "city": "Salo",
        "country": null
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1,
            "orderId": 8798,
            "deliveryDate": null,
            "refundDate": null,
            "status": 0,
            "referenceNumber": null,
            "invoicingDate": null
        }
    ],
    "totalItems": 617.25,
    "chargedTotal": 0,
    "invoices": null,
    "paymentplans": null,
    "refunds": null,
    "redirectionUrl": "https://sc-rel.mash.com/fi/ecommerce?merchantId=17&clientOrderId=1231233"
}

Error - existing email

POST https://el-release.euroloan.fi/api/orders HTTP/1.1 

HTTP/1.1 200 OK 
Content-Type: application/json
{
    "merchantId": 17,
    "merchantUser": {
        "userId": "1",
        "storeId": "88",
        "deviceId": "99"
    },
    "clientOrderId": "1231233",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "channel": "Web",
    "customer": {
        "personId": "290284-6510",
        "name": "Teppo Testaaja",
        "email": "teppo.testaaja@mailinator.com",
        "mobile": "+358401111111",
        "clientCustomerId": "1233454",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI"
    },
    "deliveryAddress": {
        "address": "Pohjoinen Rautatiekatu 90",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "totalItems": 1,
    "paymentType": "Invoice",
    "installmentCount": 4
}

HTTP/1.1 400 Bad Request 

Content-Type: application/json

{
    "errorCode": 20001,
    "message": "Error occurred when creating the order number. Please retry your order.",
    "localizedMessage": "Tilausnumeron luonnissa tapahtui virhe. Ole hyvä ja aloita tilauksen tekeminen alusta."
}

Error - existing client order id

POST https://el-release.euroloan.fi/api/orders HTTP/1.1 

HTTP/1.1 200 OK 
Content-Type: application/json
{
    "merchantId": 17,
    "merchantUser": {
        "userId": "1",
        "storeId": "88",
        "deviceId": "99"
    },
    "clientOrderId": "1231233",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "channel": "Web",
    "customer": {
        "personId": "290284-6510",
        "name": "Teppo Testaaja",
        "email": "teppo.testaaja12@mailinator.com",
        "mobile": "+358401111114",
        "clientCustomerId": "1233454",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI"
    },
    "deliveryAddress": {
        "address": "Pohjoinen Rautatiekatu 90",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "totalItems": 1,
    "paymentType": "Invoice",
    "installmentCount": 4
}

HTTP/1.1 400 Bad Request 

Content-Type: application/json

{
    "errorCode": 20001,
    "message": "Error occurred when creating the order number. Please retry your order.",
    "localizedMessage": "Tilausnumeron luonnissa tapahtui virhe. Ole hyvä ja aloita tilauksen tekeminen alusta."
}

Error - Terms not accepted

POST https://el-release.euroloan.fi/api/orders HTTP/1.1 

HTTP/1.1 200 OK 
Content-Type: application/json
{
    "merchantId": 17,
    "clientOrderId": "32131223122321",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "channel": "Web",
    "customer": {
        "personId": "290284-6510",
        "name": "Teppo Testaaja",
        "email": "teppo.testaaja@mailinator.com",
        "mobile": "+358411111122",
        "clientCustomerId": "1233454",
        "allowMarketing": true,
        "allowCreditCheck": false,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "totalItems": 1,
    "paymentType": "Invoice",
    "installmentCount": 4
}

HTTP/1.1 400 Bad Request 

Content-Type: application/json

{
    "errorCode": 20057,
    "message": "To continue please accept terms.",
    "localizedMessage": "Ole hyvä ja hyväksy ehdot."
}

Success - Order with PaymentPlan

POST https://el-release.euroloan.fi/api/orders HTTP/1.1 

HTTP/1.1 200 OK 
Content-Type: application/json

{
    "merchantId": 17,
    "clientOrderId": "60330944813434",
    "orderPlaced": "2020-10-26 14:47:09 ",
    "channel": "Web",
    "deliveryAddress": {
        "address": "Tornikatu 1 V 2",
        "zipCode": "11199",
        "city": "Salo2",
        "country": null
    },
    "customer": {
        "personId": "050684-652S",
        "name": "Teppo Testaaja",
        "email": "teppo.testaajq2a@mailinator.com",
        "mobile": "+3584111111193",
        "clientCustomerId": "12334584",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 1,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "totalItems": 1,
    "paymentType": "PaymentPlan",
    "installmentCount": 3
}

HTTP/1.1 200 Ok 

Content-Type: application/json

{
    "orderId": 8813,
    "clientOrderId": "60330944813434",
    "orderPlaced": "2020-10-26 14:47:09",
    "status": "Pending",
    "referenceNumber": null,
    "statusCode": 1,
    "paymentType": "PaymentPlan",
    "paymentPlanTypeId": null,
    "customer": {
        "personId": "050684-****",
        "clientCustomerId": "12334584",
        "name": "Niemi Taneli",
        "email": "teppo.testaajq2a@mailinator.com",
        "mobile": "04111111193",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI",
        "identificationType": 0,
        "identificationNumber": null
    },
    "deliveryAddress": {
        "address": "Tornikatu 1 V 2",
        "zipCode": "11199",
        "city": "Salo2",
        "country": null
    },
    "invoicingAddress": {
        "address": "Tornikatu 1 V 1",
        "zipCode": "11199",
        "city": "Salo",
        "country": null
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 1,
            "vatPercent": 24,
            "type": 1,
            "orderId": 8813,
            "deliveryDate": null,
            "refundDate": null,
            "status": 0,
            "referenceNumber": null,
            "invoicingDate": null
        }
    ],
    "totalItems": 123.45,
    "chargedTotal": 0,
    "invoices": null,
    "paymentplans": null,
    "refunds": null,
    "redirectionUrl": "https://sc-rel.mash.com/fi/ecommerce?merchantId=17&clientOrderId=60330944813434"
}
Get order information
GET /orders/{orderId}

Authentication

Basic Auth

Return order information.

Path variables

orderId
string required

Mash order identifier.

Request parameters

merchantId
string optional

Merchant identifier. Mandatory for clients like PSPs that use shared API keys.

Example:
1234

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Responses

200 OK
Example 1
Example 2

Denied Status

GET https://el-release.euroloan.fi/api/orders/11?merchantId=17 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": 8811,
    "clientOrderId": "6033094481343_denied",
    "orderPlaced": "2019-02-07 15:45:23",
    "status": "Denied",
    "referenceNumber": null,
    "statusCode": 3,
    "paymentType": "Invoice",
    "paymentPlanTypeId": null,
    "customer": {
        "personId": "050684-****",
        "clientCustomerId": "123345w4",
        "name": "Niemi Taneli",
        "email": "teppo.testaajq1a@mailinator.com",
        "mobile": "04111111193",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI",
        "identificationType": 0,
        "identificationNumber": null
    },
    "deliveryAddress": {
        "address": "Tornikatu 1 V 2",
        "zipCode": "11199",
        "city": "Salo2",
        "country": null
    },
    "invoicingAddress": {
        "address": "Tornikatu 1 V 1",
        "zipCode": "11199",
        "city": "Salo",
        "country": null
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1,
            "orderId": 8811,
            "deliveryDate": null,
            "refundDate": null,
            "status": 0,
            "referenceNumber": null,
            "invoicingDate": null
        }
    ],
    "totalItems": 617.25,
    "chargedTotal": 0,
    "invoices": null,
    "paymentplans": null,
    "refunds": [],
    "redirectionUrl": null
}

Accepted Status

GET https://el-release.euroloan.fi/api/orders/8812?merchantId=17 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": 8812,
    "clientOrderId": "6033094481343",
    "orderPlaced": "2020-10-26 14:47:09",
    "status": "Approved",
    "referenceNumber": null,
    "statusCode": 2,
    "paymentType": "Invoice",
    "paymentPlanTypeId": null,
    "customer": {
        "personId": "050684-****",
        "clientCustomerId": "12334584",
        "name": "Niemi Taneli",
        "email": "teppo.testaajq1a@mailinator.com",
        "mobile": "04111111193",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI",
        "identificationType": 0,
        "identificationNumber": null
    },
    "deliveryAddress": {
        "address": "Tornikatu 1 V 2",
        "zipCode": "11199",
        "city": "Salo2",
        "country": null
    },
    "invoicingAddress": {
        "address": "Tornikatu 1 V 1",
        "zipCode": "11199",
        "city": "Salo",
        "country": null
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 1,
            "vatPercent": 24,
            "type": 1,
            "orderId": 8812,
            "deliveryDate": null,
            "refundDate": null,
            "status": 0,
            "referenceNumber": null,
            "invoicingDate": null
        }
    ],
    "totalItems": 123.45,
    "chargedTotal": 0,
    "invoices": null,
    "paymentplans": null,
    "refunds": [],
    "redirectionUrl": null
}
Cancel order
POST /orders/{orderId}/cancel

Authentication

Basic Auth

Cancel the order before delivery, i.e. the order status has to be Approved or Pending.

Path variables

orderId
string optional

Mash order identifier.

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Request body

Object
merchantId
string

Merchant identifier. Mandatory for clients like PSPs that use shared API keys.

merchantUser
MerchantUser nullable

If applicable, information about the user triggering the call.

Responses

200 OK
Example 1
Example 2

Cancel order in pending status

GET https://el-release.euroloan.fi/api/orders/8813/cancel HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": 8813,
    "clientOrderId": "60330944813434",
    "orderPlaced": "2020-10-26 14:47:09",
    "status": "Cancelled",
    "referenceNumber": null,
    "statusCode": 5,
    "paymentType": "PaymentPlan",
    "paymentPlanTypeId": null,
    "customer": {
        "personId": "050684-****",
        "clientCustomerId": "12334584",
        "name": "Niemi Taneli",
        "email": "teppo.testaajq2a@mailinator.com",
        "mobile": "04111111193",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI",
        "identificationType": 0,
        "identificationNumber": null
    },
    "deliveryAddress": {
        "address": "Tornikatu 1 V 2",
        "zipCode": "11199",
        "city": "Salo2",
        "country": null
    },
    "invoicingAddress": {
        "address": "Tornikatu 1 V 1",
        "zipCode": "11199",
        "city": "Salo",
        "country": null
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 1,
            "vatPercent": 24,
            "type": 1,
            "orderId": 8813,
            "deliveryDate": null,
            "refundDate": null,
            "status": 0,
            "referenceNumber": null,
            "invoicingDate": null
        }
    ],
    "totalItems": 123.45,
    "chargedTotal": 0,
    "invoices": null,
    "paymentplans": null,
    "refunds": null,
    "redirectionUrl": null
}

Cancel order in Denied status or already canceled order

GET https://el-release.euroloan.fi/api/orders/8811/cancel HTTP/1.1 

{
    "errorCode": 20024,
    "message": "Incorrect order status.",
    "localizedMessage": "Tilauksen tila on väärä."
}
Charge order
POST /orders/{orderId}/charge

Authentication

Basic Auth

Charge specified order items.This method is called when some or all order items are delivered.

Depending on Order PaymentType either a new Invoice or PaymentPlan is created. Order status is changed to Active.

If invoice, you can’t call refund for the same day (The system might create an invoice the day after and will be delivered to the customer immediately. You can still make changes to your order on that day,to update the invoice.). For further details, merchants can check the extranet and search for by orderId (mash order id).

Path variables

orderId
string required

Mash order id

Example:
223322332

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Request body

Object
merchantId
string

Merchant identifier. Mandatory for clients like PSPs that use shared API keys.

merchantUser
MerchantUser nullable

If applicable, information about the user triggering the call.

orderItems
Array of OrderItem

Order items to be marked as Charged. A ChargeEvent is recorded for each of them.

fullDelivery
boolean

Mark all items in the order as Charged. If set true, orderItems parameter is ignored.

Example:
false

Responses

200 OK
Example 1
Example 2

Success

POST https://el-release.euroloan.fi/api/orders/223322332/charge HTTP/1.1 

Content-Type: application/json

{
    "merchantUser": {
        "userId": "2",
        "storeId": "1"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "fullDelivery": true
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": 8817,
    "clientOrderId": "1231213",
    "orderPlaced": "2019-02-07 17:08:08",
    "status": "Active",
    "referenceNumber": "2100017601256018",
    "statusCode": 4,
    "paymentType": "PaymentPlan",
    "paymentPlanTypeId": 8,
    "customer": {
        "personId": "130384-****",
        "clientCustomerId": "12334584",
        "name": "Niemi Taneli",
        "email": "teppo.testaajq12a@mailinator.com",
        "mobile": "04111111192",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI",
        "identificationType": 0,
        "identificationNumber": null
    },
    "deliveryAddress": {
        "address": "Tornikatu 1 V 2",
        "zipCode": "11199",
        "city": "Salo2",
        "country": null
    },
    "invoicingAddress": {
        "address": "Tornikatu 1 V 1",
        "zipCode": "11199",
        "city": "Salo",
        "country": null
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 1,
            "vatPercent": 24,
            "type": 1,
            "orderId": 8817,
            "deliveryDate": "2019-02-07T17:12:24.468Z",
            "refundDate": null,
            "status": 5,
            "referenceNumber": "2100017601256018",
            "invoicingDate": null
        }
    ],
    "totalItems": 123.45,
    "chargedTotal": 123.45,
    "invoices": null,
    "paymentplans": [
        {
            "id": 16,
            "lengthInMonths": 3,
            "monthlyAmount": 46.41,
            "initialFee": 0,
            "invoicingFee": 3.9,
            "totalAmount": 139.20985,
            "orderItems": [
                {
                    "articleId": "D234234234",
                    "description": "Tuote x",
                    "pricePerUnit": 123.45,
                    "numberOfUnits": 1,
                    "vatPercent": 24,
                    "type": 1,
                    "orderId": 8817,
                    "deliveryDate": "2019-02-07T17:12:24.468Z",
                    "refundDate": null,
                    "status": 5,
                    "referenceNumber": "2100017601256018",
                    "invoicingDate": null
                }
            ],
            "refundedItems": []
        }
    ],
    "refunds": [],
    "redirectionUrl": null
}

Error - already charged order

POST https://el-release.euroloan.fi/api/orders/223322332/charge HTTP/1.1 

Content-Type: application/json

{
    "merchantUser": {
        "userId": "2",
        "storeId": "1"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "fullDelivery": true
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "errorCode": 20075,
    "message": "Payment plan already exists. Charge method not allowed.",
    "localizedMessage": "Osamaksu on jo käytössä. Maksutavan valinta ei ole mahdollinen. "
}
Refund order
POST /orders/{orderId}/refunds

Authentication

Basic Auth

Create a refund to an order. Only items that have been charged can be refunded. Order status is Active or Closed. Invoice or payment plan total is changed accordingly and a notification sent to customer.

Input order items are matched to existing ones with articleId+type (if not available, description+type).

Matching order items are refunded according to their original price. Non-matching items are ignored, unless they are of Correction type.

If a refund using the original prices is not applicable or the total should be adjusted for other reasons, use Correction order item type. Note the usage of positive/negative values!

  • Negative value reduces the total charged from customer.
  • Positive value increases the total charged from customer.

Path variables

orderId
string required

Mash order id

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Request body

Object
merchantId
string

Merchant identifier. Mandatory for clients like PSPs that use shared API keys.

merchantUser
MerchantUser nullable

If applicable, information about the user triggering the call.

orderItems
Array of OrderItem

Order items to refund.

fullRefund
boolean

Refund all items in the order.

referenceNumber
string nullable

Reference number of the invoice to correct. Only needed if partial deliveries are used.

Responses

200 OK
Example 1
Example 2

Success - full refund

POST https://el-release.euroloan.fi/api/orders/1232321/refunds HTTP/1.1 

Content-Type: application/json

{
    "merchantUser": {
        "userId": "2",
        "storeId": "1"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "fullRefund": true
}


HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": 8817,
    "clientOrderId": "1231213",
    "orderPlaced": "2019-02-07 17:08:08",
    "status": "Closed",
    "referenceNumber": null,
    "statusCode": 6,
    "paymentType": "PaymentPlan",
    "paymentPlanTypeId": 8,
    "customer": {
        "personId": "130384-****",
        "clientCustomerId": "12334584",
        "name": "Niemi Taneli",
        "email": "teppo.testaajq12a@mailinator.com",
        "mobile": "04111111192",
        "allowMarketing": true,
        "allowCreditCheck": true,
        "ipAddress": "173.194.71.94",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1...",
        "locale": "fi-FI",
        "identificationType": 0,
        "identificationNumber": null
    },
    "deliveryAddress": {
        "address": "Tornikatu 1 V 2",
        "zipCode": "11199",
        "city": "Salo2",
        "country": null
    },
    "invoicingAddress": {
        "address": "Tornikatu 1 V 1",
        "zipCode": "11199",
        "city": "Salo",
        "country": null
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 1,
            "vatPercent": 24,
            "type": 1,
            "orderId": 8817,
            "deliveryDate": "2019-02-07T17:12:24Z",
            "refundDate": "2019-02-07T17:16:06.547Z",
            "status": 4,
            "referenceNumber": "2100017601256018",
            "invoicingDate": null
        }
    ],
    "totalItems": 123.45,
    "chargedTotal": 123.45,
    "invoices": null,
    "paymentplans": [
        {
            "id": 16,
            "lengthInMonths": 0,
            "monthlyAmount": 46.41,
            "initialFee": 0,
            "invoicingFee": 0,
            "totalAmount": 0,
            "orderItems": [],
            "refundedItems": [
                {
                    "articleId": "D234234234",
                    "description": "Tuote x",
                    "pricePerUnit": 123.45,
                    "numberOfUnits": 1,
                    "vatPercent": 24,
                    "type": 1,
                    "orderId": 8817,
                    "deliveryDate": "2019-02-07T17:12:24Z",
                    "refundDate": "2019-02-07T17:16:06.547Z",
                    "status": 4,
                    "referenceNumber": "2100017601256018",
                    "invoicingDate": null
                }
            ]
        }
    ],
    "refunds": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 1,
            "vatPercent": 24,
            "type": 1,
            "orderId": 8817,
            "deliveryDate": "2019-02-07T17:12:24Z",
            "refundDate": "2019-02-07T17:16:06.547Z",
            "status": 4,
            "referenceNumber": "2100017601256018",
            "invoicingDate": null
        }
    ],
    "redirectionUrl": null
}

Error - Invoice must be delivered

POST https://el-release.euroloan.fi/api/orders/1232321/refunds HTTP/1.1 

Content-Type: application/json

{
    "merchantUser": {
        "userId": "2",
        "storeId": "1"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1
        }
    ],
    "fullRefund": false,
    "referenceNumber" : "2100017601256021"
}

Content-Type: application/json

{
    "errorCode": 20014,
    "message": "Refund cannot be done. Either the order is more than 40 days old, it has not been delivered or it cannot be found.",
    "localizedMessage": "Hyvitys ei ole mahdollinen. Joko tilaus on yli 40 päivää vanha, tilausta ei ole toimitettu tai tuotetta ei löydy."
}
Registrations and reports

Registering merchants and users. Reporting methods.

POST /merchants
GET /merchants/{merchantId}/report
Add merchant
POST /merchants

Authentication

Basic Auth

Register a new merchant. Merchant account is immediately useable, but payments to merchant will not be done until verification of merchant.

Notes

Please note that in order to add merchants, the account you are using must allow it.

If you get a 10001 error using corret credentials, the it usually indicates that ou cannot add new merchants using those credentials.

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Request body

Object
merchantInfo

Merchant information

addApiKeys
boolean

Generate and return API keys that allow the merchant to make API calls. If false, merchant is assumed to use the same (payment provider) keys that were used for this method call.

extranetUserEmail
string nullable

Add extranet user account for provided email address. User account credentials are returned in response.

Responses

200 OK
Body
Object
name
string

Merchant name.

merchantId
number

Merchant identifier. To be used when creating orders etc.

apiKeys
Object nullable

API keys if requested.

username
string

API username.

password
string

API password.

extranetUser
Object nullable

Extranet user information if requested.

username
string

Extranet username.

password
string

Extranet password.

link
string

URL to extranet.

Example 1
POST https://el-release.euroloan.fi/api/merchants HTTP/1.1 
            
Content-Type: application/json
 
{
    "merchantInfo": {
        "name": "My company",
        "companyId": "XXXXXXX-X",
        "email": "info@mycompany.com",
        "phone": "0000000",
        "bankAccount": "FIXXXXXXXXXXXXXXXXS",
        "website": "www.my-company-website.com",
        "address": {
            "address": "Pohjoinen Rautatiekatu 9",
            "zipCode": "12345",
            "city": "Helsinki",
            "country": "FI"
        }
    },
    "addApiKeys": true,
    "extranetUserEmail": "extranetuseremail@mycompany.com"
}

HTTP/1.1 200 OK 

{
    "name": "My company",
    "merchantId": 15,
    "apiKeys": {
        "username": "mycompany",
        "password": "eC@92V3zsFyM_ajQib4cMZ6M"
    },
    "extranetUser": {
        "username": "mycompany",
        "password": "somepassword",
        "link": "https://el-release.euroloan.fi/merchants"
    }
}
Get payout report
GET /merchants/{merchantId}/report

Authentication

Basic Auth

Get report of payouts (activity)

Path variables

merchantId
string required

Request parameters

startTime
string required

Start time for report. ISO 8601 format.

Example:
2020-10-26T00:00:00Z
endTime
string required

End time for report.

Example:
2020-10-27T00:00:00Z

Request headers

Authorization
string required

Authorization header. Basic authentication scheme.

The credentials are provided by us or generated by the method Add merchant

Example:
Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
application/json
Content-Type
string required

Content type is application/json

Example:
application/json

Responses

200 OK
Body
Object
items

Payout report items.

totalItemCount
number

Total number of payout report items.

Example 1
GET https://el-release.euroloan.fi/api/merchants/{merchantId}/report?startTime=2020-10-26T00:00:00Z&endTime=2020-10-27T00:00:00Z?startTime=2020-10-26T00:00:00Z&endTime=2020-10-27T00:00:00Z HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "items": [
        {
            "orderId": 1,
            "created": "2020-10-26",
            "payoutType": "Correction",
            "amount": 100.25,
            "orderReferenceNumber": "21000123456789",
            "payoutReferenceNumber": "100001234567",
            "username": "",
            "clientOrderId": "23423423423",
            "clientCustomerId": "1233454",
            "customerName": "Pelle Miljoona"
        }
    ],
    "totalItemCount": 1
}
Data Reference
Customer

Customer information

Object
personId
string

Person identifier, SSN. In response data partially filtered.

Examples:
010771-257W010771-****
name
string

Full name of the customer.

Example:
Teppo Testaaja
email
string

Email address.

Example:
teppo.testaaja@mailinator.com
mobile
string

Mobile phone number.

Example:
+358401111111
clientCustomerId
string

Client side customer identifier.

Example:
1233454
allowMarketing
boolean

Has the customer allowed marketing messages.

Example:
true
allowCreditCheck
boolean

Asiakastieto consumer loan query. is this really necessary.

Example:
true
ipAddress
string

IP address where the customer made the request from.

Example:
173.194.71.94
browserUserAgent
string

User-Agent header of the customer’s browser.

Example:
Mozilla/5.0 (Windows NT 6.1...
locale
string

Selected localization on the web site. Returned error messages will be localized accordingly. 2-letter language code followed with 2-letter country code.

Example:
fi-FI
Methods: Create order
Types: OrderResult
OrderItem

Ordered product or service. Can also contain discount with negative amount, handling or other fee, refund or any other item that has a monetary value.

Object
articleId
string

Identifier of the product in ecommerce system.

Example:
D234234234
description
string

Description of the ordered item.

Example:
Tuote x
pricePerUnit
number

Price of one unit including VAT. Can be negative for discount items.

Example:
123.45
numberOfUnits
number

Number of units included in the order.

Example:
5
vatPercent
number

VAT percentage included in the product price.

Example:
24
type
number

1=product 2=shipping cost 3=handling cost 4=discount (negative) 5=correction (positive or negative)

Order item status.

Address

Address information.

Object
address
string

Street address.

Example:
Pohjoinen Rautatiekatu 9
zipCode
string

Zip code.

Example:
12345
city
string

City.

Example:
Helsinki
country
string

Country code (2 letter ISO 3166).

Example:
FI
OrderResult

Order information.

Object
orderId
string

Mash order ID.

Example:
1223435
clientOrderId
string
Example:
23423423423
orderPlaced
string
Example:
2020-10-26T14:47:09Z
status
string
Example:
Pending
statusCode
string

Numeric status code

Example:
1
paymentType
string

Selected payment type for the order.

Example:
PaymentPlan
paymentPlanTypeId
string

Selected payment plan type.

Example:
123
customer

Customer information.

deliveryAddress

Delivery address.

invoicingAddress

Official address used for invoice and payment plan delivery.

orderItems
Array of OrderItem

List of reserved order items.

totalItems
number

Total of reserved order items.

chargedTotal
number

Total of charged order items, reduced with any refunded items.

invoices
Array of Invoice

Obsolete, please ignore.

paymentPlans
Array of PaymentPlan

Obsolete, please ignore.

redirectionUrl
string

URL for redirecting customer to Mash site. To be used if the status is Pending.

PaymentPlanType

Payment plan type available for customer.

Object
id
string

Payment plan identifier.

Example:
4587
installmentCount
number

Number of installments.

Example:
6
initialFeeFixed
number

Set up fee for payment plan. Fixed amount.

Example:
20
initialFeePercentage
number

Set up fee for payment plan. Percentage of total amount.

Example:
0
notificationFeeFixed
number

Fee charged for each invoice. Fixed amount.

Example:
3.95
notificationFeePercentage
number

Fee charged for each invoice. Percentage of total.

Example:
0
interestRate
number

Interest rate for the payment plan.

Example:
0
fromAmount
number

Payment plan is applicable starting from this amount.

Example:
100.01
toAmount
number

Payment plan is applicable up to this amount.

Example:
200
calculation
Object nullable

Calculation based on order price (if given).

orderAmount
number
Example:
350.12
installmentAmount
number

Amount to pay on monthly basis.

Example:
65.64
totalAmount
number

Total to pay.

Example:
393.82
initialFee
number

Set up fee for payment plan.

Example:
20
notificationFee
number

Fee charged for each invoice sent to customer.

Example:
3.95
Methods: Get pricing
Invoice

Invoice data

Object
id
number

Invoice identifier.

Example:
12121221
duedate
string

Due date of the invoice.

Example:
2020-02-15
invoicedate
string

Date and time (UTC) when invoice was created.

Example:
2020-02-01T12:19:17Z
totalAmount
number

Total amount to pay.

Example:
621.02
minimumAmount
number

Minimum amount to pay.

Example:
50.5
orderItems
Array of OrderItem

Order items included in the invoice.

refundedItems
Array of OrderItem

Refunded order items.

Types: OrderResult
PaymentPlan

Payment plan information.

Object
id
string

Payment plan identifier

Example:
5673
lengthInMonths
number

Length of the payment plan in months.

Example:
12
monthlyAmount
number

Monthly installment amount.

Example:
25.45
initialFee
number

Set up fee for the payment plan.

Example:
4.95
notificationFee
number

Fee charged for each invoice sent to customer.

Example:
2.95
totalAmount
number

Total amount of the plan.

Example:
299.4
orderitems
Array of OrderItem

Order items included in the payment plan.

chargedItems
Array of OrderItem

Order items that are charged for.

refundedItems
Array of OrderItem

Refunded order items.

Types: OrderResult
ChargeEvent

Credit account event charged.

Object
id
number

Charge event identifier.

orderItem

Order item that was charged.

MerchantUser

Identifies user and store.

Object
userId
string

Identifier of a user.

storeId
string

Identifier of a store.

deviceId
string

Identifier of a device.

OrderStatus

Status of the order.

string
Enumeration:
Pending

Order is pending and requires authorization.

Approved

Order has been approved with the included reservations, and can be delivered.

Denied

Order has been denied and cannot be delivered.

Active

Order is active, and has been delivered partially or fully. Additional partial delivery is possible, but no new reservations can be added.

Cancelled

Order was cancelled.

Closed

Order has expired or is fully paid.

PaymentType

Invoice, paymentplan or credit account.

string
Enumeration:
Invoice
PaymentPlan
Methods: Create order
OrderItemStatus

Status of an order item.

string
Enumeration:
NotDelivered

Order item has been reserved but not yet delivered

Cancelled

Order item has been cancelled

Invoiced

Order item has been delivered and charged

Returned

Order item has been refunded

Delivered

Order item has been delivered

Types: OrderItem
Merchant

Merchant information.

Object
name
string

Company name.

companyId
string

Company identifier (Y-tunnus)

email
string nullable

Email address for customer support.

phone
string nullable

Phone number for customer support.

bankAccount
string nullable

Bank account number (IBAN) to use for payments.

website
string nullable

Web site address.

address
Address nullable

Company address information.

PayoutReportItem

Payout report item information

Object
orderId
number

Mash order ID.

created
string

Created date. ISO-8601.

Example:
2016-03-09
payoutType
string

Payout type.

Enumeration:
Charge
Correction
amount
number

Amount of the order.

Example:
100.25
orderReferenceNumber
string

Order reference number.

Example:
21000123456789
payoutReferenceNumber
string

Payout reference number.

Example:
100001234567
username
string

Extranet username.

clientOrderId
string

Client side order identifier.

Example:
23423423423
clientCustomerId
string

Client side customer identifier.

Example:
1233454
customerName
string

Name of the customer.

Example:
Pelle Miljoona