Shared functions

This section provides a general description that applies for all of Ecsters API:s including
important information about security and authentication.

You are always welcome to reach out to us if you have any questions.

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 textvalue 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 idtextvalue 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 textvalue 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:

HTTP status Information
400 input data validation failed
403 no access
404 reference not found
422 unprocessable request
500 could not complete operation
503 service unavailable right now

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.

Life cycle of order

 

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.

Order status

Ecster uses orderstatus to describe the current status of an order. See Ecsters different order status below.

Orderstatus Description
Ready (“READY”) Order is ready to be delivered by merchant.
Pending, pending payment ("PENDING_PAYMENT") Payment is being processed.
Pending, awaiting decision (“PENDING_DECISION”) Order is pending and cannot be delivered by merchant.
Pending, awaiting signature (“PENDING_SIGNATURE”) Order is approved and Ecster awaits signed consumer contract. Order cannot be delivered by merchant.
Pending, awaiting processing (“PENDING_PROCESSING”) Order is approved but needs further processing. Order cannot be delivered by merchant.
Denied (“DENIED”) Order was denied and cannot be delivered.
Failed (“FAILED”) Order failed payment.
Aborted (“ABORTED”) Consumer aborted payment.
Partly delivered (“PARTIALLY_DELIVERED”) Merchant has delivered part of the order. Merchant can deliver the rest of the order at any time.
Fully delivered (“FULLY_DELIVERED”) Merchant has delivered complete order or closed a part delivered order. Merchant cannot deliver order.
Annulled (“ANNULLED”) Merchant has annulled order. Merchant cannot deliver order.
Expired (“EXPIRED”) Order is too old.
Blocked (“BLOCKED”) Order is stopped by Ecster. This happens for example when Ecster suspects that the order is fraudulent.
Manual handling (MANUAL_PROCESSING) The order is manually beeing handled by Ecster.

Event status

In addition Ecster uses order event statuses to describe an action, for example when a credit transaction has been processed. See Ecsters different event status below.

Orderevent  Description
Partial credit (“PARTIAL_CREDIT”) Order partially credited, total credited amount < totally debited amount
Full credit (“FULL_CREDIT”) Order fully credited, total credited amount = totally debited amount
Partial debit (“PARTIAL_DEDIT”) Order partially debited, order status is “PARTIALLY_DELIVERED”
Full debit (“FULL_DEDIT”) Order fully dedited, order status is “FULLY_DELIVERED”
Partial annulment (“PARTIAL_ANNULMENT”) Order partially annuled, order status is “FULLY_DELIVERED”
Full annulment (“FULL_ANNULMENT”) Order fully annuled, order status is “ANNULLED”

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.

Name Data type  Description
amount integer

Amount sent as integer number using smallest denominator for current currency. Ex: in Sweden the smallest currency unit is öre and the amount 156,75 SEK would be expressed as 15675

percent integer integer number percent representation, allowing maximum two decimals. Ex: 6,70% should be expressed as 670
currency string, size 3 3 letter currency name according to ISO 4217
date string, size 10  Date expressed as a string in extended ISO 8601 format, i.e. YYYY-MM-DD. Ecster does not support dropped values for reduced accuracy 
nationalid 

string, size 13 

Personal id containing information about person and country. Format is ISO 3166-1 alpha-2 code for country and then a country specific person identifier. For Sweden the personnummer is used as person identifier and the composite format is SEYYMMDD-XXXX with size 13. Nationalid is not case sensitive 
orderstatus

string

Enumeration with order statuses
orderevent

string

Enumeration with order events
 timestamp string, size 25   Combined date and time with time zone information, expressed as a string in extended ISO 8601 format, i.e. YYYY-MM-DDTHH:MM:SSZZZZZZ. The time zone information ZZZZZZ has format (+/-)HH:MM. Ecster does not support dropped values for reduced accuracy or decimal fraction on seconds
transactiontype string  Enumeration with transaction types, see types below
Initial cart "INITIAL" Initial cart on order. Read only
Debit "DEBIT" Debit transaction
Credit  "CREDIT" Credit transaction
Annul  "ANNUL" Annul transaction

Custom objects

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

Request test account