Shared functions

Security

For security reasons the following limitations apply:

1. All communication with Ecster is over secure https connections.
2. All calls need to be authenticated.
3. All calls are done from your backend, and not from a consumer's browser, to avoid compromising your server credentials.

Rate limiting

Ecster utilizes rate limiting to protect services from excessive use. Ecster will respond with a HTTP 429 (Too Many Requests) if that limit is exceeded.

Rate limiting will be configured to not affect expected transaction volumes. Prior intention is to prevent abuse.

Authentication

All calls against Ecster's API need to be authenticated using custom HTTP headers.

• x-api-key: JKN675aVeMR9Mleh786FGf2ff7T1okmH6 (example)
• x-merchant-key: 10569832 (example)

An api key can be used for one or mulitple merchants.

• Organisations having multiple point of sales, both ECOM and/or multiple POS
• Parties acting on behalf of multiple merchants, e.g. back office services

API and merchant key administration

• Merchants can generate and revoke API keys using Ecster Dashboard. To determine what an API key is allowed to do a permission based system is used. API key permissions are derived by the user creating the API key, i.e. the api key has the same permissions as the creating user
• Merchants can view associated merchant keys using the Ecster Dashboard
• Multiple keys with same profile can be created and be valid concurrently

Locale

String representation of locale, conforming to the IETF language tag format language-regionwhere language are ISO 639-1 language code and region is ISO 3166-1 alpha-2. For Swedish in Sweden the locale is sv-SE. Locale is not case sensitive.

Localized info/terms

Many REST services provide localized information/terms which can be used by the integrating part to present in dialogues with consumer.

Each info/term is an object identified by parameter id. For each id parameters text, value and unit with associated values can be used for presentation purposes.

localizedTerms (object, 0-*): Formatted and localized headings and values for presentation pusposes.

• id (string, 1):
• text (string, 1):
• value (string, 1):
• unit (string, 0-1):

As shown above, localized information/terms are returned as a list of objects. Different subsets of valid values for parameter id apply in different contexts. For more information, see each use case.

Following is a simplified example to present two part payment fees (submethodPARTPAYMENT_SE_1). Two localized term objects are returned with parameters id, text, value and unit with associated values.

"localizedTerms": [
    {
        "id": "startFee",
        "text": "Uppläggningsavgift",
        "value": "395",
        "unit": ":"kr"
    },
    {   "id": "adminFee",
        "text": "Administrativ avgift",
        "value": "29",
        "unit": ":"kr"
    }
}

Identify each object by id, in this example “startFee” and “adminFee”. Present in dialogue by retreiving associated values for text, value and unit.

"text"                 "value"   "unit"
Uppläggningsavgift:    395 kr    ("id": "startFee")
Administrativ avgift:  29 kr     ("id": "adminFee")

List of valid values for id.

• startFee
• adminFee
• interestRate
• payments
• perMonth
• effectiveRate
• creditCost
• totalAmount
• name
• description
• termsPdfUrl
• secciPdfUrl

Error response object

When an API call fails a HTTP status of 400 or greater is returned indicating the type of error.

The response body will contain an object with the following fields:

• code (int, 1): Ecster error code
• type (string, 1): Error type, e.g. ‘Input validation error’
• message (string, 0-1): Further information about the error

Different HTTP status error codes:

Pagination

When an API call returns a collection of resources the result will be paged. Page size and offset can be requested using query parameters limit and offset respectively. If further resources can be obtained a Link http header with rel="next" is returned with the URL of the next page.

If a response is paginated it will contain a Link-header with a link to the next page.

In the example below the request for orders, https://api.ecster.com/v1/orders?offset=100?limit=20 returns the following header:

Link: <https://<host>/v1/orders>; rel="first", <https://<host>/v1/orders?offset=120?limit=20>; rel="next", <https://<host>/v1/orders?offset=80?limit=20>; rel="prev"

Order life cycle

Life cycle of an order, starting as a (unpaid) cart in the first step, complete with order statuses is visualised in the graph below.

Order Event Notification (OEN)

Ecster will send an event notification to the notification URL supplied when the order was created. An OEN will be sent as soon as an event has affected the order. Most events imply an order changing status, but not all. For example, a partially debited order being partially debited again will have the same order status (“PARTIALLY_DELIVERED”) before and after the event.

Note that Ecster does not send the complete order information but rather a signal that something has happened with the order.

NOTE As the name indicates, Async OEN is an asynchronous notification. An OEN can be sent within seconds but can also be delayed for minutes, thus you should NOT build your application relying on an OEN being sent within a certain amount of time. 

• Merchant must answer with HTTP 200 or Ecster will try to send the notification again in 2 hours. Ecster will try to send the notification 24 times.
• Ecster recommends that the merchant makes a get order request with the orderId to get all the updated order information from the response when an async OEN is received.
• For authentication purpose, a custom http header can be supplied in the OEN call. The name and value of this http header must be provided to Ecster for configuration.

Tags

Tags can be supplied when creating an order or a cart and will be used to provide the merchant with statistics. It is possible to provide multiple tags on a per order/cart basis.

Tag strategy is decided soley by merchant.

A value can be typed or untyped:

• typed: both tag name and tag are supplied, separated by a colon <tagName>:<tag>. Example “product:TV”
• untyped: only the tag is supplied, <tag>. Example: “TV”

Typed tags will enable aggregated statistics.

Document URLs

The various document URLs provided will be usable directly in client applications. Where required, the document URLs will be time limited.

Data types

Custom data types used by Ecster are as follows.

Custom objects

Ecster have created custom objects that are used in all the REST-services.