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

API headers, responses and error codes.

Headers
Authorization
string required

Authorization header containing username and password

Example:
Authorization: Basic 0b79bab50daca910b000d4f1a2b675d604257e42
Accept
string required

Accept application/json

Example:
Accept: application/json
Content-Type
string required

Content type is application/json

Example:
Content-Type: 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 Order already exists with the client order id
  • 20002 Order does not exist
  • 20003 Order is Denied
  • 20004 Order is Pending
  • 20005 Order is Cancelled
  • 20006 Order is Closed
  • 20007 Order has expired
  • 20008 Order has no rows
  • 20009 Order total cannot be negative
  • 20010 Payment option is not applicable
  • 20011 Order payment type not matching
  • 20012 Invoice total amount could not be authorized
  • 20013 Payment plan not possible or could not be created
  • 20014 Refund order not possible
  • 20015 Order is not in Pending or Approved state
  • 20016 installmentCount is mandatory if paymentType is PaymentPlan.
  • 20017 Phone number already in use
  • 20018 Email already in use
  • 20019 Item articleId is not unique
  • 20020 Internal Scoring workflow failed
  • 20021 InstallmentCount not possible for order amount
  • 20022 Minimum order amount for payment plan is 10 €
  • 20023 Maximum order amount for payment plan is 2000 €
  • 20024 Wrong order status
  • 20025 Negative credit decision
  • 20026 Credit limit not sufficient
API endpoints

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

Production environment
Test 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.

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.

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

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.

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://elfiprod.blob.core.windows.net/public/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

Get available pricing.

If orderAmount is given, matches the applicable payment plans based on amount and calculates the plan price. Without orderAmount, 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.

Example:
1214.50

Responses

200 OK
Body
Object
pricingUpdated
string

Pricing configuration last updated timestamp. yyyy-MM-ddTHH:mm:ssZ

Example:
2015-12-12T09:25:29Z
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.

Example 1
GET https://fi.mash.com/api/pricing?merchantId=232423424 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "pricingUpdated": "2015-12-12T09:25:29Z",
    "invoice": {
        "invoicingFee": "3.95",
        "invoiceDue": "14"
    },
    "paymentPlans": {
        "id": "4587",
        "installmentCount": 6,
        "initialFeeFixed": 20,
        "initialFeePercentage": 1,
        "notificationFeeFixed": 3.95,
        "notificationFeePercentage": 1,
        "interestRate": 1,
        "fromAmount": 100.01,
        "toAmount": 200,
        "calculation": {
            "orderAmount": 350.12,
            "installmentAmount": 65.64,
            "totalAmount": 393.82,
            "initialFee": 20,
            "notificationFee": 3.95
        }
    }
}
Get person information
GET /personinfo

Get person information based on personId (SSN).

Request parameters

personId
string required

Person id to lookup the customer.

Example:
1980001010101

Responses

200 OK
Body
Object
name
string

Name of the person

Example:
Maria Svensson
personId
string

Person identifier

Example:
1980001010101
officialAddress

Official address

Example 1
GET https://fi.mash.com/api/personinfo?personId=1980001010101 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Maria Svensson",
    "personId": "1980001010101",
    "officialAddress": {
        "address": "Pohjoinen Rautatiekatu 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    }
}
Create order
POST /orders

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.

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.

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

Optional address for delivery in the case official address is not used. Note that additional fraud prevention checks are required.

orderItems
OrderItem nullable

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:
PaymentPlan
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
POST https://fi.mash.com/api/orders HTTP/1.1 

Content-Type: application/json

{
    "merchantId": 23232323,
    "merchantUser": {
        "userId": "",
        "storeId": ""
    },
    "merchantInfo": {
        "name": "",
        "companyId": "",
        "email": "",
        "phone": "",
        "bankAccount": "",
        "website": "",
        "address": {
            "address": "Pohjoinen Rautatiekatu 9",
            "zipCode": "12345",
            "city": "Helsinki",
            "country": "FI"
        }
    },
    "clientOrderId": "",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "channel": "Web",
    "customer": {
        "personId": "010771-257W",
        "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 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "orderItems": {
        "articleId": "D234234234",
        "description": "Tuote x",
        "pricePerUnit": 123.45,
        "numberOfUnits": 5,
        "vatPercent": 24,
        "type": 1,
        "status": "Refunded"
    },
    "totalItems": 1,
    "paymentType": "Invoice",
    "installmentCount": 1
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": "1223435",
    "clientOrderId": "23423423423",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "status": "Pending",
    "statusCode": "1",
    "paymentType": "PaymentPlan",
    "paymentPlanTypeId": "123",
    "customer": {
        "personId": "010771-257W",
        "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 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "invoicingAddress": {
        "address": "Pohjoinen Rautatiekatu 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1,
            "status": "Cancelled"
        }
    ],
    "totalItems": 1,
    "chargedTotal": 1,
    "invoices": [
    ],
    "paymentPlans": [
    ]
}
Get order information
GET /orders/{orderId}

Return order information.

Path variables

orderId
string required

Mash order identifier.

Responses

200 OK
Example 1
GET https://fi.mash.com/api/orders/123213213 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": "1223435",
    "clientOrderId": "23423423423",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "status": "Pending",
    "statusCode": "1",
    "paymentType": "PaymentPlan",
    "paymentPlanTypeId": "123",
    "customer": {
        "personId": "010771-****",
        "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 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "invoicingAddress": {
        "address": "Pohjoinen Rautatiekatu 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1,
            "status": "Refunded"
        }
    ],
    "totalItems": 1,
    "chargedTotal": 1,
    "invoices": [
    ],
    "paymentPlans": [
    ]
}
Cancel order
POST /orders/{orderId}/cancel

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 body

Object
merchantUser
MerchantUser nullable

If applicable, information about the user triggering the call.

Responses

200 OK
Charge order
POST /orders/{orderId}/charge

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.

Path variables

orderId
string required

Mash order id

Example:
223322332

Request body

Object
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
POST https://fi.mash.com/api/orders/223322332/charge HTTP/1.1 

Content-Type: application/json

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

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": "1223435",
    "clientOrderId": "23423423423",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "status": "Active",
    "statusCode": "4",
    "paymentType": "PaymentPlan",
    "paymentPlanTypeId": "123",
    "customer": {
        "personId": "010771-****",
        "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 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "invoicingAddress": {
        "address": "Pohjoinen Rautatiekatu 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1,
            "status": "Charged"
        }
    ],
    "totalItems": 1,
    "chargedTotal": 1,
    "invoices": [
    ],
    "paymentPlans": [
    ]
}
Refund order
POST /orders/{orderId}/refunds

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

Object
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
POST https://fi.mash.com/api/orders/1232321/refunds HTTP/1.1 

Content-Type: application/json

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

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "orderId": "1223435",
    "clientOrderId": "23423423423",
    "orderPlaced": "2020-10-26T14:47:09Z",
    "status": "Closed",
    "statusCode": "6",
    "paymentType": "PaymentPlan",
    "paymentPlanTypeId": "123",
    "customer": {
        "personId": "010771-****",
        "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 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "invoicingAddress": {
        "address": "Pohjoinen Rautatiekatu 9",
        "zipCode": "12345",
        "city": "Helsinki",
        "country": "FI"
    },
    "orderItems": [
        {
            "articleId": "D234234234",
            "description": "Tuote x",
            "pricePerUnit": 123.45,
            "numberOfUnits": 5,
            "vatPercent": 24,
            "type": 1,
            "status": "Cancelled"
        }
    ],
    "totalItems": 1,
    "chargedTotal": 1,
    "invoices": [
    ],
    "paymentPlans": [
    ]
}
Registrations and reports

Registering merchants and users. Reporting methods.

POST /merchants
GET /merchants/{merchantId}/report?startTime=2020-10-26T00:00:00Z&endTime=2020-10-27T00:00:00Z
Add merchant
POST /merchants

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

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://fi.mash.com/api/merchants HTTP/1.1 

Content-Type: application/json

{
    "merchantInfo": {
        "name": "",
        "companyId": "",
        "email": "",
        "phone": "",
        "bankAccount": "",
        "website": "",
        "address": {
            "address": "Pohjoinen Rautatiekatu 9",
            "zipCode": "12345",
            "city": "Helsinki",
            "country": "FI"
        }
    },
    "addApiKeys": true,
    "extranetUserEmail": ""
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "",
    "merchantId": 1,
    "apiKeys": {
        "username": "",
        "password": ""
    },
    "extranetUser": {
        "username": "",
        "password": "",
        "link": ""
    }
}
Get payout report
GET /merchants/{merchantId}/report?startTime=2020-10-26T00:00:00Z&endTime=2020-10-27T00:00:00Z

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

Responses

200 OK
Body
Object
items

Payout report items.

totalItemCount
number

Total number of payout report items.

Example 1
GET https://fi.mash.com/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

Invoices created based on order.

paymentPlans
Array of PaymentPlan

Payment plans created based on order.

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.

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
CreditAccount
Methods: Create order
OrderItemStatus

Status of an order item.

string
Enumeration:
Reserved

Order item has been reserved but not yet delivered

Cancelled

Order item has been cancelled

Charged

Order item has been delivered and charged

Refunded

Order item has been refunded

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