Ecster Pay (deprecated)

The Ecster Pay API is based on straight forward RESTful architecture principles using the lightweight data-interchange format JSON. Ecster Pay works great on all devices and screens. The UI is designed to be perceived as a natural part of your webshop.

Need help getting started? Check out our Tutorials

Ecster Pay REST API

In order to completely integrate Ecster Pay, there’s a REST API that exposes two methods – Create and Update cart. You will always need to execute Create cart, but it’s likely that you also need to execute Update cart. For both requests, you need to authorize your application.

Every call to the REST API must be made from your application’s backend.

Both calls return the same thing – a cart key. You will get a new cart key for every time you execute one of these functions and you always use the latest key, as this references the cart that is most up to date.

The base URL for the REST API is https://secure.ecster.se/rest/ for production environment. For test environment use https://labs.ecster.se/rest/.  In addition to the authorization headers below, you also need to send the correct content type (application/json) for JSON, as this is the data format for the API.

Authorization

The authorization contains three headers which are described below. The username and password is obtained by creating a test account. Once you’ve submitted the form, you’ll receive an email from us containing the information you need.

X-Ecster-origin: checkout
X-Ecster-username: <shop username>
X-Ecster-password: <shop password>

Read more about implementing request header in the Get started section.

Create cart

POST /eps/v1/cart

Once the customer enters the store checkout page, you need to execute Create cart. This will return a cart key which you need to initiate Ecster Pay in your application's frontend.

You need to somehow persist your cart key in your frontend as it is a mandatory parameter to the Update cart call.

The parameters required to execute Create cart are visible if you expand the example. You can also refer to Get started to get a good introduction.

You can choose if you want to send in delivery method in Create cart as an own object or as a cart row. NOTE: If you send in delivery methods as an own object you have to mark one as selected.

Create cart

Post https://secure.ecster.se/rest/eps/v1/cart

Request

Headers

X-Ecster-origin: checkout
X-Ecster-username: <username>
X-Ecster-password: <password>
Content-Type: application/json

Body

{
  "locale": {
    "language": "sv",
    "country": "SE"
  },
  "deliveryMethods": [
    {
      "id": "1a2c681f-7d88-425a-a3f7-cda2bbfc91cd",
      "name": "Hemleverans",
      "description": "Leverans till ditt hem.",
      "price": 4900,
      "selected": true
    }
  ],
  "cart": {
    "amount": 27800,
    "currency": "SEK",
    "message": null,
    "externalReference": null,
    "rows": [
      {
        "partNumber": "264275-0044_501",
        "name": "Vit T-shirt",
        "description": "Vit 100% bomull",
        "quantity": 2.0,
        "unitPrice": 13900,
        "unit": "st",
        "vatCode": "25%",
        "discount": 0,
        "serials": [
          "264275"
        ]
      }
    ]
  },
  "eCommercePlatform": {
    "reference": "2cc5c43d-fb92-472f-828a-1a5ad703d512",
    "info": "info about version"
  },
  "customer": null,
  "returnInfo": {
    "ok": "<url to shop>"
  },
  "notificationUrl": null
}

Response 201 Created

Body

{
    responseTime: 100
    status: 201,
    response: {
        key: 'cart key'
    }
}

Data types

= Mandatory
= Optional

Create cart

locale object

See data type locale

deliveryMethods object[]

An array of delivery methods. See data type delivery method.

cart object

See data type cart

customer object

See data type customer

notificationUrl string

Notification URL for OSN

eCommercePlatform object

E-Commerce Platform information

returnInfo object

Only used for external Ecster Pay

Locale

language String

language code (ISO-639) ”sv”, ”en”, ”no”, ”da”, ”fi”

country String

country code (ISO-3166), "SE"

Cart

amount int

Order amount in least valued denomination

currency string

Currency - SEK

rows object[]
message string
externalReference string

Shop order reference

cart row

partNumber string

Shop item identifier

name string
description string
quantity double
unitPrice int

Amount in least valued denomination (öre, cent...)

unit string

E.g. st, kg, cm...

vatCode string

0% | 6% | 12% | 25%

discount int

Discount in least valued denomination

serials string[]

Item serial numbers

Customer

ssn string

Country specific format, e.g. YYMMDD-XXXX

firstName string
lastName string
address string
city string
zip string
name string

Delivery method

id string
name string
description string
price int

Price in the least valued denomination (öre, cent e.t.c.)

selected bool

indicates if this option should be pre selected

eCommercePlatform

reference string

Unique identifier provided by Ecster Pay

info string

Info about version

Return info

ok string

Return URL back to shop

Update cart

PUT /eps/v1/cart/<cart key>

If the customer adds items to the cart after Ecster Pay has started on the checkout page,  you'll need to execute Update cart. The parameters are similar to Create cart, but you also need to provide the current cart key. If it’s the first time you execute Update cart, you will use the current cart key from the Create cart call. After a successful update, a new cart key will be returned to your system. Save this cart key as this is now the current active cart key.

You can choose if you want to send delivery method in Update cart as an own object or as a cart row. NOTE: If you send in delivery methods as an own object you have to mark one as selected.

Update cart

Put /eps/v1/cart/{cart key}

Request

Headers

X-Ecster-origin: checkout
X-Ecster-username: <username>
X-Ecster-password: <password>
Content-Type: application/json

Query parameters

cartKey string

The most recent cart key.

Body

{
  "locale": {
    "language": "sv-SE",
    "country": "SE"
  },
  "deliveryMethods": [
    {
      "id": "b7547b2f-96bf-4e1e-8854-6ab638290ac9",
      "name": "Hemleverans",
      "description": "Leverans till ditt hem.",
      "price": 4900,
      "selected": true
    }
  ],
  "cart": {
    "amount": 44700,
    "currency": "SEK",
    "message": null,
    "externalReference": null,
    "rows": [
      {
        "partNumber": "217844-0040_501",
        "name": "Vit T-shirt",
        "description": "Vit 100% bomull",
        "quantity": 2.0,
        "unitPrice": 14900,
        "unit": "st",
        "vatCode": "25%",
        "discount": 0,
        "serials": [
          "264275"
        ]
      },
     {
        "partNumber": "217844-0040_502",
        "name": "Svart T-shirt",
        "description": "Svart 100% bomull",
        "quantity": 1.0,
        "unitPrice": 14900,
        "unit": "st",
        "vatCode": "25%",
        "discount": 0,
        "serials": [
          "264276"
        ]
      }
    ]
  },
  "eCommercePlatform": {
    "reference": "2cc5c43d-fb92-472f-828a-1a5ad703d512",
    "info": "info about version"
  },
  "customer": null,
  "returnInfo": {
    "ok": "<url to shop>"
  },
  "notificationUrl": null
}

Response 200 OK

Body

{
  responseTime: 100
  status: 201,
  response: {
    key: 'cart key'
  }
}

Data types

= Mandatory
= Optional

Update cart

Locale locale
deliveryMethods object[]
cart object
customer object
eCommercePlatform object
returnInfo object

Only used for external Ecster Pay

Locale

language String

language code (ISO-639) ”sv”, ”en”, ”no”, ”da”, ”fi”

country String

country code (ISO-3166), "SE"

Delivery method

id string
name string
description string
price int

Price in the least valued denomination (öre, cent e.t.c.)

selected bool

indicates if this option should be pre selected

Cart

amount int

Order amount in least valued denomination

currency string

Currency - SEK

rows object[]
message string
externalReference string

Shop order reference

cart row

partNumber string

Shop item identifier

name string
description string
quantity double
unitPrice int

Amount in least valued denomination (öre, cent...)

unit string

E.g. st, kg, cm...

vatCode string

0% | 6% | 12% | 25%

discount int

Discount in least valued denomination

serials string[]

Item serial numbers

Customer

ssn string

Country specific format, e.g. YYMMDD-XXXX

firstName string
lastName string
address string
city string
zip string
name string

eCommercePlatform

reference string

Unique indentifier provided by Ecster Pay

info string

Info about version

Return info

ok string

Return URL back to shop

Get order

GET /orders/v1/<internalReference>

There’s potentially a lot of information that the customer provides in the checkout process that’s not directly available to your site. If the customer provides the address in the external checkout, it won’t be available to your site during the checkout process. It is the same when using the integrated Ecster Pay. Since the customer provides information within an iframe, it will not be available to your site. In this case, there are callbacks you can utilize to get some information during the checkout process. However, in order for you to get a complete order summary, there’s a REST API function called Get order.

This function is typically called when Ecster Pay calls your site through the Order status notification (OSN). When a customer completes a payment, Ecster Pay will call the URL provided in notification URL in Create cart.

You must provide the internal order reference in the URL when making the call.

Get order

Get /orders/v1/{InternalReference}

Request

Headers

X-Ecster-origin: checkout
X-Ecster-username: <shop username>
X-Ecster-password: <shop password>
Content-type: application/json

Query parameters

internalReference string

The internal order reference from OSN

Body

Response 200 OK

Body

{
   "responseTime":52,
   "status":200,
   "response":{
      "order":{
         "idMethod":"BANKID_MOBILE",
         "amount":44700,
         "currency":"SEK",
         "rows":[
            {
               "partNumber":"264275-0044_501",
               "name":"Vit T-shirt",
               "description":"Vit 100% bomull",
               "quantity":2.0,
               "unitPrice":13900,
               "unit":"st",
               "vatCode":"25%",
               "discount":0,
               "serials":[
                  "264275"
               ]
            },
            {
               "partNumber":"264275-0044_502",
               "name":"Svart T-shirt",
               "description":"Svart 100% bomull",
               "quantity":1.0,
               "unitPrice":13900,
               "unit":"st",
               "vatCode":"25%",
               "discount":0,
               "serials":[
                  "264276"
               ]
            }
         ],
         "externalReference":"TMP604",
         "debitedAmount":0,
         "creditedAmount":0,
         "internalReference":"pNRpI7KtqHwMx4zU",
         "status":"ready",
         "date":"2016-06-17T11:43:34.124+02:00"
      },
      "customer":{
         "id":10182,
         "ssn":"670704-0082",
         "name":"BERGLUND, BERFIN",
         "address":"HAMMARBERGSGATAN 13",
         "city":"FINSPÅNG",
         "zip":"612 41",
         "cellular":"0700000000",
         "email":"email@email.se"
      },
      "deliveryMethod":{
         "id":"1a2c681f-7d88-425a-a3f7-cda2bbfc91cd",
         "name":"Hemleverans",
         "description":"Leverans till ditt hem.",
         "price":4900,
         "selected":true
      },
      "paymentMethod":{
         "type":"CARD",
         "sortOrder":0,
         "terms":[
            {
               "cardBrand":"MASTER"
            }
         ]
      },
      "transactions":[
         {
            "type":"ORIGINAL",
            "amount":44700,
            "closeOrder":false,
            "rows":[
               {
                  "partNumber":"264275-0044_501",
                  "name":"Vit T-shirt",
                  "description":"Vit 100% bomull",
                  "quantity":2.0,
                  "unitPrice":13900,
                  "unit":"st",
                  "vatCode":"25%",
                  "discount":0,
                  "serials":[
                     "264275"
                  ]
               },
               {
                  "partNumber":"264275-0044_502",
                  "name":"Svart T-shirt",
                  "description":"Svart 100% bomull",
                  "quantity":1.0,
                  "unitPrice":13900,
                  "unit":"st",
                  "vatCode":"25%",
                  "discount":0,
                  "serials":[
                     "264276"
                  ]
               }
            ],
            "created":"2016-06-17T11:43:34.123+02:00"
         }
      ]
   }
}

Data types

= Mandatory
= Optional

Get order

order object

See Order object

customer object

See Customer object

recipient object

See Recipient object

deliveryMethod object

See Delivery method object

paymentMethod object

See Payment method object

transactions object

See Transactions object

order

amount int

Order amount in least valued denomination

currency string

Currency - SEK, NOK, EUR...

rows object[]
message string
externalReference string

Shop order reference

internalReference string

Ecster internal order reference

Customer

ssn string

Country specific format, e.g. YYMMDD-XXXX

firstName string
lastName string
address string
city string
zip string
name string

recipient

Recipient object, that contians information of the current customer. The customer have chosen to use an alternative address from their registered address.

name string

Name of the current customer.

firstName string
lastName string
address String

Address of the current customer.

adress2 String

Example C/O adress, company name

streetName String

Street name is only available with country code DE and AT

streetNumber String

Street number is only available with country code DE and AT

zip String

Zip/Area code of the current customer.

city String

City location of current customer.

region String
countryCode String

Country code format ISO 3166-1 alpha-2

Delivery method

id string
name string
description string
price int

Price in the least valued denomination (öre, cent e.t.c.)

selected bool

indicates if this option should be pre selected

Payment method

type string
sortOrder int
idMethodsAllowed string[]
terms object[]

See Payment method terms

providers object[]

See object Payment provider

Payment methods terms

id int
name string
interestRate double
adminFee int
startFee int
payments int

Number of part payments

perMonth int

Amount to pay per month using part payment

effectiveRate double
creditCost int
minAmount int
maxAmount int
newLimit int
expiryDays int

Payment provider

cardBrand string

transactions

type string
amount int
closeOrder bool
rows object[]

See transaction row

created string

A date in ISO 8601 format with timezone information

createdBy string

transaction row

description String

Contains a description of the current order row.

discount String

Percentage of discount that is used in the current order row.

name String

Name of the current order row.

partNumber String

Shop's item identifier.

quantity String

Quantity of the current order row.

serials Array

Array of item serial numbers.

unit String

Provides information about what unit that is measured.

unitPrice String

Price of the current order row.

vatCode String

The value added tax for the current order row.

External Reference

Set External Reference

 

POST /orders/v1/<internalReference>/externalReference

Creates an external order reference for a specific order if it does not exist or updates an existing external reference if does exist.

Set external reference

Post /orders/v1/{internalReference}/externalReference

Request

Headers

X-Ecster-origin: checkout
X-Ecster-username: <shop username>
X-Ecster-password: <shop password>
Content-type: application/json

Query parameters

internalReference string

Internal reference

Body

{
  "externalReference": "<Shop_order_reference>" 
 }

Response 201 Created

Body

{
    responseTime: 100,
    status: 200
}

Data types

= Mandatory
= Optional

Order status notification (OSN)

Whenever an order changes status, e.g. READY, Ecster Pay communicates this back to your site. This function is called Order status notification (OSN). Ecster Pay will call an URL determined by the parameter notification URL provided in createCart.

You will need to create a web service that Ecster Pay communicates with. Ecster Pay will execute a POST request containing the internal and external order references as well as the new order status. Use the internal order reference to get order details from Ecster Pay.

If your site successfully received and processed the call from Ecster Pay, you must return HTTP status 200 OK. Otherwise, Ecster Pay will retry the call every other hour for 48 hours.

Order status notification

Post http://yoursite.com/api/ecster

Request

Headers

Body

{
    internalReference: '9VVacR2X15uHV1dk', // Ecster Pay order ref
    externalReference: 'PO1000', // as sent from create order
    status: 'READY'
}

Response 200 OK

Body

Data types

= Mandatory
= Optional

Order status notification

internalReference string

Reference in Ecster

externalReference string

Shop reference (as provided via Create order)

Maximum value 16 characters

status string
Orderstatus Description
Ready (“ready”) The order is ready to be delivered by the store.
Awaiting contract (“awaitingContract”) The order is approved and Ecster awaits signed customer contract, order cannot be delivered by store.
Awaiting payment
("awaitingPayment")		 The order is being processed.
Denied (“denied”) The order was denied and cannot be delivered.
Failed (“failed”) The order failed payment.
Aborted (“aborted”) The customer aborted the payment.
Partly delivered (“partiallyDelivered”) The store has delivered part of the order and can deliver the rest of the order at any time.
Fully delivered (“fullyDelivered”) The store has delivered a complete order or closed a part delivered order. The store cannot deliver the order.
Annuled (“annuled”) The store has annuled the order and cannot deliver the order.
Expired (“expired”) The order is too old.
Blocked (“blocked”) The order is stopped by Ecster. This happens for example when Ecster suspects that the order is fraudulent.
Manual handling (“manualHandling”) The order is manually beeing handled by Ecster.

Ecster JS API

Implementation script

To be able to run Ecster Pay, the following script has to be included on the page where Ecster Pay is going to be used.

Production

https://secure.ecster.se/pay/integration/ecster-pay.js

<script src="https://secure.ecster.se/pay/integration/ecster-pay.js"></script>

Labs / test

https://labs.ecster.se/pay/integration/ecster-pay-labs.js

<script src="https://labs.ecster.se/pay/integration/ecster-pay-labs.js"></script>

EcsterPay

.start(startOptions)

The start method is used to render Ecster Pay in the container on your store checkout page.

View the example below to see all options you can pass to this function. The parameters cartKey and shopTermsUrl are required.

onCheckoutStartInit()

An event that’s trigged before the checkout starts.

BEST PRACTICE: While starting Ecster Pay, we recommend that you prevent the customer from making any changes to the cart. Read more under locking mechanism.

onCheckoutStartSuccess()

An event that’s trigged when Ecster Pay successfully started.

onCheckoutStartFailure(onStartFailureData)

An event that’s trigged when the checkout failed to start.

onChangedDeliveryAddress(newDeliveryAddress)

An event that’s trigged when the delivery address is changed.

NOTE: A new delivery address may render the current delivery method and/or price as invalid. We recommend that you run the logic for choosing delivery method again, then execute update cart with the new values.

The new delivery address is sent as a parameter to the event.

onChangedContactInfo

An event that’s trigged when the contact information is changed.

The new contact information is sent as a parameter to the event.

onPaymentSuccess(onPaymentSuccessData)

An event that´s trigged when the payment has been successfully executed. When triggered, you should update the order in your system accordingly. Furthermore, if Ecster Pay is indicating shop´s own result page (.start and showPaymentResult set to false),  you should direct the consumer to your shops result page. Your backend system will receive an OSN request with order status information (asynchronously within a reasonable  amount of time, e.g. a few seconds up to 5 minutes). Your backend must be able to handle your order being updated twice, both from the triggered event and from the OSN request, regardless which action happens first.

NOTE: It may occur that the onPaymentSuccess event is not triggered even though the order was successfully executed in Ecster Pay, e.g. if the consumer closes the browser.  In this case you should update the order in your system upon receiving the OSN request.

onPaymentFailure()

An event that’s trigged when the payment has failed.

NOTE: It may occur that the onPaymentFailure event is not triggered even though the order process was completed in Ecster Pay, e.g. if the consumer closes the browser. In this case you should update the order in your system upon receiving the OSN request.

onPaymentDenied(onPaymentDeniedData)

An event that’s trigged when the payment was denied by the payment service.

NOTE: It may occur that the onPaymentDenied event is not triggered even though the order process was completed in Ecster Pay, e.g. if the consumer closes the browser. In this case you should update the order in your system upon receiving the OSN request.

onCheckoutUpdateInit()

An event that executes before the update of Ecster Pay starts.

BEST PRACTICE: While updating Ecster Pay, we recommend that you prevent the customer from making any changes to the cart. Read more under locking mechanism.

 

onCheckoutUpdateSuccess()

An event that's trigged when the update of Ecster Pay has been successfully executed.

onCheckoutUpdateFailure()

An event that’s trigged when the update of Ecster Pay has failed to execute.

onCustomerAuthenticated(onCustomerAuthenticatedData)

An event that's triggered when the customer has completed a successful BankID authentication.

NOTE: This is where you can communicate with this particular customer by, for example, presenting the customer with certain discounts or bonuses.

.initUpdateCart(currentCartKey)

Ecster Pay must be notified when the cart is going to be updated. Use the initUpdateCart function in the Ecster Pay JS API.

First call initUpdateCart with the current cart key in your application’s frontend. The initUpdateCart call returns a callback function.

Then execute initUpdateCart containing the updated information through your application’s backend to receive a new cart key.

Finally execute the callback function with the new cart key. This will cause Ecster Pay to be refreshed with the new information.

(function(window, $) {
    var currentCartKey = '<cart key>';
    var updatedCartCallback = EcsterPay.initUpdateCart(currentCartKey);
    $.post('<Url to update API>', function(newCartKey) {
        updatedCartCallback(newCartKey);
        currentCartKey = newCartKey;
    })
})(window, jQuery)

BEST PRACTICE: While updating Ecster Pay, we recommend that you prevent the customer from making any changes to the cart. Read more under locking mechanism.

DEPRECATED: .updateCart(currentCartKey)

.getUrl(options)

This function generates a URL to the external Ecster Pay. This is the fastest way to implement Ecster Pay. See this tutorial for a complete implementation.

DEPRECATED: .getNewWindowUrl(options)

Request test account