Start Ecster Pay

This tutorial will show you how to render Ecster Pay in a created Div after the user have selected what products they want to purchase and continues to the checkout.

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

Endpoint URLs

Ecster have different endpoints for testing and for live purchases. All request have to be done with HTTPS. See details in API reference section. 

Create checkout cart

This is the first REST call you will have to do in order to render Ecster Pay for the user on your website.

createCart call have some mandatory parameters you have to send in the JSON body and some optional. You can see all parameters in API reference section.

Below is some parameters that will make Ecster Pay adjust for that specific purchase.

  • locale for setting which language and country for visual presentation to be used. Ecster supports (Swedish, English, Finnish, Norwegian and Danish)
  • countryCode will filter which payment methods and identification methods that specific country supports
  • purchaseType will filter which payment methods and identification methods that supports B2C or B2B purchase 
  • defaultDeliveryCountry sets the default delivery country in Ecster Pay when user chooses to use another delivery adress

When you have called createCart you will receive the full body that you have sent in and a unique cart key. This is the key that you have to persist.

createCart JSON example

Below you see a createCart request and the response included the cart key.

POST /v1/carts

x-api-key: njdfdsdkjfl5598503mnfkfe
x-merchant-key: 86969769
Content-Type: application/json

{
  "locale": {
    "language": "sv",
    "country": "SE"
  },
  "countryCode": "SE",
  "parameters": {
    "shopTermsUrl": "https://ecster.com/terms/storeTerms.html",
    "returnUrl": "https://ecster.com/return/to/page.html",
    "defaultDeliveryCountry": "SE",
    "purchaseType": {
      "type": "B2C",
      "show": false
    }
  },
  "deliveryMethods": [
    {
      "id": "Delivery1010",
      "name": "Shipping by car",
      "description": "Shipping with a large car",
      "price": 10000,
      "selected": true
    }
  ],
  "cart": {
    "amount": 10000,
    "currency": "SEK",
    "rows": [
      {
        "partNumber": "264275-0044_345",
        "name": "Adidas Stan Smith",
        "description": "White size 9",
        "quantity": 1,
        "unitAmount": 10000,
        "unit": "st",
        "vatRate": 2500,
        "discountAmount": 0,
        "serials": [
          "951358"
        ]
      }
    ]
  },
  "orderReference": "123123",
  "notificationUrl": "https://ecster.se/osn/API",
  "platform": {
    "reference": "2cc5c43d-fb92-472f-828a-1a5ad703d512",
    "info": "info about version"
  },
  "tags": [
    "Shoes:White",
    "Sales:12345"
  ]
}

Here you see the response from the createCart REST call.

Status: 201 Created

{
    "checkoutCart": {
        "key": "083085A4620308EDD0C43B8890E0C392",
        "locale": {
            "language": "sv",
            "country": "SE"
        },
        "deliveryMethods": [
            {
                "id": "Delivery1010",
                "name": "Shipping by car",
                "description": "Shipping with a large car",
                "price": 10000,
                "selected": true
            }
        ],
        "cart": {
            "amount": 10000,
            "currency": "SEK",
            "rows": [
                {
                    "name": "Adidas Stan Smith",
                    "quantity": 1,
                    "unitAmount": 10000,
                    "vatRate": 2500,
                    "partNumber": "264275-0044_345",
                    "description": "White size 9",
                    "unit": "st",
                    "discountAmount": 0,
                    "serials": [
                        "951358"
                    ]
                }
            ]
        },
        "notificationUrl": "https://ecster.se/osn/API",
        "platform": {
            "reference": "2cc5c43d-fb92-472f-828a-1a5ad703d512",
            "info": "info about version"
        },
        "tags": [
            "APIv1",
            "Shoes:White",
            "Sales:12345"
        ],
        "parameters": {
            "returnUrl": "https://ecster.com/return/to/page.html",
            "shopTermsUrl": "https://ecster.com/terms/storeTerms.html",
            "defaultDeliveryCountry": "SE",
            "purchaseType": {
                "type": "b2c",
                "show": false
            }
        },
        "countryCode": "SE"
    }
}

Render Ecster Pay

Prepare the site by creating a Div element that serves as a container where Ecster Pay is loaded (see example). Then reference the Ecster Pay JavaScript library in order to access mandatory functions to be able to initiate Ecster Pay.

When the cart key is received from Ecster you can call the start functions (see example) in the JavaScript library. All the functions is available in the API reference section. This will make Ecster Pay appear on the checkout page.

<div id="ecster-pay-ctr"></div>
...
<script src="https://secure.ecster.se/pay/integration/ecster-pay.js"></script>
EcsterPay.start({
    cartKey: 'E0D30C4B583C4D06C5ABAEB787865A71', shopTermsUrl: 
    'https://ecster.se', showPaymentResult: true
})

Ecster Pay appears in your created Div

It looks something like this depending on which parameters you have sent to createCart.

Ecster Pay

Use locking mechanism

Whenever a user goes to the checkout page, makes changes to a cart or the merchant wants to make changes the REST calls createCart is used. These calls are describe more in detail further down in this tutorial.

Note

If a user would spam changes to the cart, an equal number of calls would be made with updateCart. A lot of asynchronous requests executed in a short time span, does not ensure that the responses are returned in the same order.

The effect of this, could be that the last returned key is actually not the most recent key. Therefore, you need to disable the user from making changes to the cart while updateCart or createCart is executing. This will prevent new calls from being executed before the current call has been handled and finished.

How to know when to lock your page

Ecsters JavaScript libary have functions to help you accomplish this. First of all Ecster Pay has its own locking mechanism.

When you start or update Ecster Pay, its interface disables the user from making any changes in Ecster Pay. If you were to try and execute additional calls during the lock, these will generate an error which you can catch.

If your store checkout page allows the user to make changes to the cart, you will need to disable these options while createCart and updateCart is being executed.

Use Ecster's callback functions to know when to lock and unlock your checkout page

Upon start, locking your store should start when the callback onCheckoutStartInit is called and unlocking will be done when the onCheckoutStartSuccess or onCheckoutStartFailure is called.

Upon update, locking your store should start when the callback onCheckoutUpdateInit is called and unlocking will be done when the onCheckoutUpdateSuccess or onCheckoutUpdateFailure is called.

Next step

Continue to read about how to handle changes e.g. updates to the cart and information updates.

Go to the next step here

Request test account