Create Order

First you will need to get the available payment options for a consumer for a specific amount.

This operation enables you to:
  • Showing available payment methods for a consumer with a specific amount.
  • Showing a consumers existing accounts (only applicable on payment method part payment) the consumer must be identified using a strong identification method: either electronic identification or a physical ID document.

When you get available payment options you have to send in the below attributes:

  • ticket: Ticket used to identify consumer
  • amount: Amount on order.
  • currency: Currency on order
  • availableCredit: Available credit on account, both on a new account and an existing. If not set, a default available credit will be set automatically.
  • invoiceFee:  will implicitely be added to the requested amount

Attribute availableCredit applies only to payment method PARTPAYMENT. Attribute invoiceFee applies only to payment method INVOICE. See more information on attribute availableCredit & invoiceFee in API reference here.

1. Get available payment options

To get available payment options for a specific consumer you have to send the above attributes,  via a server-side call to our REST API. You’ll find the complete REST API reference here.

GET /v1/paymentoptions/?ticket=eYBtAD0wTZIzDWkVpGhe&amount=300000&currency=SEK&invoiceFee=0

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

All request parameters have to submittet in the url. No message body should be sent in.

2. Handle the response

You can either get OK response, or an error.

The response contains following information:

  • id: payment method reference - used in create order to determine how the order is paid for.
  • paymentMethod: “PARTPAYMENT”, “INVOICE”
  • paymentSubmethod: “PARTPAYMENT_SE_1”, “INVOICE_SE_1”
  • name: name of payment method
  • allowAlternateRecipient: indicates if an alternate recipient can be provided when creating order
  • properties: properties specified by submethod.
  • localizedTerms: Formatted and localized headings and values for presentation pusposes. See section Localized info/terms for usage. See below for valid values for id
    • id
    • text
    • value
    • unit

Below you have an example of the response from request obove. This is a response which includes Ecsters localized terms. You can see all valid values for parmeter id in object localizedTerms here.

Status: 200 OK

  {
    "id": "YmbW6PMwJFdkmmN61uNe",
    "paymentMethod": "PARTPAYMENT",
    "paymentSubmethod": "PARTPAYMENT_SE_1",
    "name": "Delbetala",
    "allowAlternateRecipient": true,
    "properties": {
      "totalAmount": 115150,
      "termsDescription": "17 delbetalningar till 8,90 % ränta",
      "termId": 44,
      "currency": "SEK",
      "startFee": 25000,
      "adminFee": 1500,
      "interestRate": 890,
      "effectiveRate": 23680,
      "perMonth": 3300,
      "payments": 35,
      "creditCost": 85150,
      "raise": false,
      "new": true,
      "accountName": "MultiCard MasterCard",
      "termsName": "35 delbetalningar till 8,90 % ränta",
      "termProductType": "MCARD001",
      "accountType": "MCARD001",
      "newCreditLimit": 200000,
      "termsPdfUrl": "https://labs.ft.ecster.se/rest/se/sv/terms/pdf/MCARD001",
      "secciPdfUrl": "https://labs.ft.ecster.se/rest/se/sv/secci/pdf/MCARD001?amount=30000",
      "termsHtmlUrl": "/docs/notImplemented.html",
      "accountRank": 1,
      "termRank": 1
    },
    "localizedTerms": [
      {
        "id": "startFee",
        "text": "uppläggningsavgift",
        "value": "250",
        "unit": "kr"
      },
      {
        "id": "adminFee",
        "text": "administrativ avgift",
        "value": "15",
        "unit": "kr"
      },
      {
        "id": "interestRate",
        "text": "ränta",
        "value": "8,9",
        "unit": "%"
      },
      {
        "id": "payments",
        "text": "antal betalningar",
        "value": "35"
      },
      {
        "id": "perMonth",
        "text": "betalning per månad",
        "value": "33",
        "unit": "kr"
      },
      {
        "id": "effectiveRate",
        "text": "effektivränta",
        "value": "236,8",
        "unit": "%"
      },
      {
        "id": "creditCost",
        "text": "kreditkostnad",
        "value": "851,5",
        "unit": "kr"
      },
      {
        "id": "newCreditLimit",
        "text": "sökt ny limit",
        "value": "2 000",
        "unit": "kr"
      },
      {
        "id": "totalAmount",
        "text": "totalt att betala",
        "value": "1 151,5",
        "unit": "kr"
      }
    ]
  },
  {
    "id": "K6WqMoIOZEQ1eCYQ9Gp2",
    "paymentMethod": "INVOICE",
    "paymentSubmethod": "INVOICE_SE_1",
    "name": "Faktura",
    "allowAlternateRecipient": true,
    "properties": {
      "termsDescription": "Betala om 14 dagar",
      "termsHtmlUrl": "/docs/notImplemented.html",
      "dueDays": 14,
      "invoiceFee": 0
    },
    "localizedTerms": [
      {
        "id": "dueDays",
        "text": "dagar förfallo",
        "value": "14"
      },
      {
        "id": "invoiceFee",
        "text": "fakturaavgift",
        "value": "0",
        "unit": "kr"
      }
    ]
  }

Create order

Create an order with a specific cart on a specified consumer with a determined payment option.

Operation enables merchant to:
  • Create and complete a order

When you create a order you have to send in the below attributes:

  • ticket: ticket used to identify consumer
  • paymentOption: how order should be paid. Use id returned in get available payment options for consumer
  • cart: object describing a cart
  • orderReference: merchant’s order reference
  • contactInfo: contact information for consumer. At least one of email/cellular must be provided
  • recipient: Order should be delivered to this recipient. May only be provided if allowed by payment option, see allowAlternateRecipient in Get available payment options for consumer
  • notificationURL: where async OEN should be sent
  • salesPerson: sales person contact information. Mandatory if inPerson set to true when creating ticket
  • parameters: see spec for orderSubtypeParameters object
  • tags: provide tags for statistics purposes.

Attribute recipient , i.e. a custom delivery address, can only be used if consumer is identified using a strong identification method. If recipient is not specified the order should be delivered to the consumer’s home address (Swedish: folkbokföringsadress).

If attribute paymentOption is INVOICE and merchant having a predefined invoice fee, Ecster will add one or multiple rows regarding invoice fees with associated vat to the original transaction (“ORIGINAL”) of the cart. Invoice fees will be added proportially to provided cart and vat rates.

Example:
If merchant has a predefined invoice fee, the following applies:
Cart has four rows with amounts 100, 200, 125 and 175, with vat rates 6%, 12%, 25% and 25% respectively. Merchants predefined invoice fee is 30, then three invoice fee rows (one per vat rate) will be added to the original transaction (“ORIGINAL”);

  • one fee row with amount 5, vat rate 6%
  • one fee row with amount 10, vat rate 12%
  • one fee row with amount 15, vat rate 25%

For these rows provided will be set to true in the row object.

1. Create order request

To create a order with a cart for a specific consumer with determined payment option you have to send the above attributes,  via a server-side call to our REST API. You’ll find the complete REST API reference here.

POST /v1/orders

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

{
  "ticket":"eYBtAD0wTZIzDWkVpGhe",
  "paymentOption":"YmbW6PMwJFdkmmN61uNe",
  "cart":{
    "amount": 300000,
    "currency":"SEK",
    "rows":[{
      "name":"Oak table",
      "quantity":1.0,  "unitAmount": 300000,
      "vatRate":2500,
      "partNumber":"00012",
      "description":"Oak table 200x300",
      "unit":"st",
      "discountAmount":0,
      "serials":[],
      "fee":false,
      "provided":false
    }],
    "message":"Message to consumer"
  },
  "contactInfo":{
    "email":"algot@testson.se",
    "cellular":{
      "country":"46",
      "number":"701111111"
    },
    "phone":{
      "country":"46",
      "number":"01811111"
    }
  },
  "orderReference":"orderReferenceDefValue",
  "notificationURL":"https://yourURL",
  "parameters":{
    "issueCard":true,
    "openReservation":true,
    "directDebit":false
  },
  "recipient":{
    "name":null,
    "address":null,
    "contactInfo":null
  },
  "salesPerson":{
    "nationalId":"65385415",
    "reference":"65385415",
    "name":{
      "firstName":"Test name def value",
      "lastName":"TestLastNameDefValue",
      "title":"TestTitleDefValue"
    },
    "address":null,
    "contactInfo":{
      "email":"user@mail.com",
      "cellular":{
        "country":"46",
        "number":"707333444"
      },
      "phone":{
        "country":"46",
        "number":"707333444"
      }
    }
  },
  "tags":["testTagType1:testTagMsg1","testTagType2:testTagMsg2"],
  "platform":{
    "reference":"123e4567-e89b-12d3-a456-426655440000",
    "info":"platformInfoDefValue"
  }
}

2. Handle response

You can either get OK response, or an error.

The response contains following information:

  • order:  an object that holds the information of the created order

 You can see all Ecsters custom objects here

Below you have an example of the response from the request obove.

Status: 201 Created

{
    "order": {
        "id": "rSW0BZRvtwQ0ZZxj3jje",
        "merchantId": "65363601",
        "status": "READY",
        "properties": {
            "method": "PARTPAYMENT",
            "submethod": "PARTPAYMENT_SE_1",
            "startFee": 25000,
            "adminFee": 1500,
            "perMonth": 3300,
            "payments": 35,
            "creditCost": 85150,
            "raise": false,
            "new": true,
            "accountNumber": "98528840****4929",
            "currentCreditLimit": 200000,
            "availableAmount": 170000,
            "openReservation": true,
            "directDebit": false
        },
        "created": "2018-04-18T20:26:22+02:00",
        "amount": 30000,
        "currency": "SEK",
        "debitedAmount": 0,
        "creditedAmount": 0,
        "orderReference": "orderReferenceDefValue",
        "consumer": {
            "nationalId": "SE530516-9756",
            "name": {
                "firstName": "Algot",
                "lastName": "Henriksson"
            },
            "address": {
                "line1": "Alsike, Årby",
                "city": "Västerås",
                "zip": "724 62",
                "country": "SE"
            },
            "contactInfo": {
                "email": "jojo28@ecster.se",
                "cellular": {
                    "number": "0707333444"
                },
                "phone": {
                    "number": "018-038648"
                }
            }
        },
        "transactions": [
            {
                "id": "NH6n1W61YkemKZSpmMpd",
                "type": "ORIGINAL",
                "created": "2018-04-18T20:26:22+02:00",
                "amount": 30000,
                "rows": [
                    {
                        "name": "Test name def value",
                        "quantity": 1,
                        "unitAmount": 30000,
                        "vatRate": 2500,
                        "partNumber": "00012",
                        "description": "TestDescription",
                        "unit": "st",
                        "discountAmount": 0,
                        "serials": [],
                        "fee": false
                    }
                ],
                "message": "TestMessageDefValue",
                "merchantId": "65363601"
            }
        ],
        "tags": [
            "testTagType1:testTagMsg1",
            "testTagType2:testTagMsg2"
        ],
        "agreementPdfUrl": "https://labs.ft.ecster.se/rest/se/sv/agreement/pdf/Mw1",
        "localizedInfo": [
            {
                "id": "agreementPdfUrl",
                "text": "avtal pdf",
                "value": "https://labs.ft.ecster.se/rest/se/sv/agreement/pdf/MTUs20Nw1"
            },
            {
                "id": "debitConsentPdfUrl",
                "text": "debiteringsunderlag pdf",
                "value": "https://labs.ft.ecster.se/rest/se/sv/debitconsent/pdf/rSW0e"
            },
            {
                "id": "amount",
                "text": "belopp",
                "value": "300",
                "unit": "kr"
            },
            {
                "id": "startFee",
                "text": "uppläggningsavgift",
                "value": "250",
                "unit": "kr"
            },
            {
                "id": "adminFee",
                "text": "administrativ avgift",
                "value": "15",
                "unit": "kr"
            },
            {
                "id": "payments",
                "text": "antal betalningar",
                "value": "35"
            },
            {
                "id": "perMonth",
                "text": "betalning per månad",
                "value": "33",
                "unit": "kr"
            },
            {
                "id": "creditCost",
                "text": "kreditkostnad",
                "value": "851,5",
                "unit": "kr"
            },
            {
                "id": "method",
                "text": "betalningssätt",
                "value": "Delbetala"
            }
        ],
        "debitConsentPdfUrl": "https://labs.ft.ecster.se/rest/se/sv/debitconsent/pdf/rje",
        "debitConsentInfo": {
            "text": "debit consent info tezt",
            "localizedInfo": [
                {
                    "id": "date",
                    "text": "datum",
                    "value": "2018-04-18+02:00"
                },
                {
                    "id": "amount",
                    "text": "belopp",
                    "value": "300",
                    "unit": "kr"
                },
                {
                    "id": "orderReference",
                    "text": "orderreferens",
                    "value": "orderReferenceDefValue"
                },
                {
                    "id": "customerName",
                    "text": "namn kund",
                    "value": "Algot Henriksson"
                },
                {
                    "id": "accountNumber",
                    "text": "kontonummer",
                    "value": "98528840****4929"
                },
                {
                    "id": "paymentMethod",
                    "text": "betalningssätt",
                    "value": "Delbetala"
                }
            ]
        }
    }
}

Signing an agreement

This operations is only applicable when:

  1. Payment method PART_PAYMENT
  2. Used a weak identification
Operation enables merchant to:
  • Sign agreement with BankID or Mobile BankID

This can result in status PENDING_SIGNATURE when caling create/update order. For the order status to become READY the consumer have to sign the agreement.

When you sign an agremment you have to send in the below attributes and the orderID in url:

  • signatureType: “ACCOUNT_AGREEMENT”
  • identification:
    • method:
      • electronical: “SE_BANKID”, “SE_BANKID_MOBILE”

1. Initialize electronic signature

Call to begin consumer signature using an electronic id - BankID or mobile BankID.

POST /v1/orders/rSW0BZRvtwQ0ZZxj3jje/signatures

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

{
  "identification": {
    "method": "SE_BANKID_MOBILE"
  },
  "signatureType": "ACCOUNT_AGREEMENT"
}

The orderId have to be submittet in the url.

2. Handle the response

You can either get OK response, or an error.

The response contains following information:

  • id: identifier for this identification.
  • status: see here for statuses.
  • startURL: URL used to activate chosen eid client on consumer’s computer or mobile device. Only relevant when application and eid client reside on same device.
  • pollTime: time to wait until next poll, in milliseconds

Status: 201 created

{
    "id": "rSW0BZRvtwQ0ZZxj3jje",
    "status": "OUTSTANDING_TRANSACTION",
    "startURL": "bankid:///?autostarttoken=DUMMY-AUTOSTART",
    "pollTime": 5000
}

Here we got status OUTSTANDING_TRANSACTION and a poll time at 5000ms and that means we are going to make the collect call to check the status in 5000ms.

3. Collect electronic signature

You make the collect call with the id returned from Initialize electronic signature or Collect electronic signature.

Cal to collect status on the signature process.

GET /v1/orders/rSW0BZRvtwQ0ZZxj3jje/signatures/<signatureId>

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

All request parameters have to submittet in the url. No message body should be sent in.

4 Handle the response

You can either get OK response, or an error.

The response contains following information:

  • id: identifier for this identification.
  • status: see here for statuses.
  • startURL:
  • pollTime: time to wait until next poll, in milliseconds
  • name: will be supplied when status is COMPLETE.
  • nationalId: will be supplied when status is COMPLETE.

Status: 200 OK

{
    "id": "v5HjBADhxAcM4QnZR3wS",
    "status": "COMPLETE",
    "pollTime": 1500,
    "name": {
        "firstName": "Algot",
        "lastName": "Henriksson"
    },
    "nationalId": "SE530516-9756"
}
Request test account