Order Management API

Search order

Search order will return a paginated result.

Query parameter Description
orderReference (string, 0-1, size max 64) Merchant order reference
merchantId (string, 0-1) Merchant id
nationalId: (nationalid, 0-1) Consumer nationality
paymentMethod: (string, 0-1) “PARTPAYMENT”, “INVOICE”, “CARD”,  “SWISH”
status (string, 0-1) Status on order
from (timestamp, 0-1) Order created from this date
to (timestamp, 0-1) Order created to this date

Get request

To search order, send the above paramters orderReference, merchantId, nationalId, paymentMethod, status, from and to via a server-side call to our REST API. 

JSON example

Get /v1/orders/?orderReference=<orderReference>&merchantId=<merchantId>&nationalId=<nationalId>&paymentMethod=<paymentMethod>&status=<status>&from=<from>&to=<to>&tomerchantId=<merchantId>

Request

Headers

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

Query parameters

orderReference string

Merchant’s order reference

merchantId string

Id of merchant

nationalId string

Id on consumer

paymentMethod string

“PARTPAYMENT”, “INVOICE”, “CARD”, SWISH

status orderstatus

Status on order

from timestamp

Order created from this date

to timestamp

Order created to this date

Body

Response 200 OK

Body

[
    {
        "id": "nKQWQISJ8leTNmYolsNN",
        "merchantId": "62134339",
        "status": "READY",
        "properties": {
            "method": "PARTPAYMENT"
        },
        "created": "2019-01-15T09:25:23+01:00",
        "amount": 350000,
        "currency": "SEK",
        "debitedAmount": 0,
        "creditedAmount": 0,
        "orderReference": "Ref-458545",
        "consumer": {
            "nationalId": "SE830219-0536",
            "name": {
                "firstName": "David",
                "lastName": "Drottz"
            }
        }
    },
]

Data types

= Mandatory
= Optional

Get order

Get order will return the specific order.

Query parameter Description
orderId (string, 1) Ecsters internal order id

Get request

To get an order, send the above paramter orderId via a server-side call to our REST API. 

JSON example

Get /v1/orders/<orderId>

Request

Headers

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

Query parameters

orderId string

Ecsters internal order reference

Body

Response 200 OK

Body

{
    "id": "zburxHFw0xQmyOmVOrcq",
    "merchantId": "100646739",
    "status": "READY",
    "properties": {
        "method": "INVOICE",
        "submethod": "INVOICE_SE_1",
        "startFee": 2900,
        "directDebit": false,
        "dueDays": 14
    },
    "created": "2019-01-13T20:50:04+01:00",
    "amount": 32900,
    "currency": "SEK",
    "debitedAmount": 0,
    "creditedAmount": 0,
    "orderReference": "orderReferenceDefValue",
    "consumer": {
        "nationalId": "SE480502-4876",
        "name": {
            "firstName": "Claes",
            "lastName": "Kauppi"
        },
        "address": {
            "line1": "Vindög 4",
            "city": "Nymölla",
            "zip": "29513"
        },
        "contactInfo": {
            "email": "pada09@ecster.se",
            "cellular": {
                "number": "0707333444"
            },
            "phone": {}
        }
    },
    "transactions": [
        {
            "id": "n2XxuckFwp6qL8NQSGAU",
            "type": "ORIGINAL",
            "created": "2019-01-13T20:50:04+01:00",
            "amount": 32900,
            "rows": [
                {
                    "name": "Test name def value",
                    "quantity": 1,
                    "unitAmount": 28000,
                    "vatRate": 2500,
                    "partNumber": "00012",
                    "description": "TestDescription",
                    "unit": "st",
                    "discountAmount": 0,
                    "serials": [],
                    "fee": false
                },
                {
                    "name": "Test name def value",
                    "quantity": 1,
                    "unitAmount": 2000,
                    "vatRate": 1200,
                    "partNumber": "00013",
                    "description": "TestDescription",
                    "unit": "st",
                    "discountAmount": 0,
                    "serials": [],
                    "fee": false
                },
                {
                    "name": "Fakturaavgift",
                    "quantity": 1,
                    "unitAmount": 193,
                    "vatRate": 1200,
                    "serials": [],
                    "fee": true,
                    "provided": true
                },
                {
                    "name": "Fakturaavgift",
                    "quantity": 1,
                    "unitAmount": 2707,
                    "vatRate": 2500,
                    "serials": [],
                    "fee": true,
                    "provided": true
                }
            ],
            "message": "TestMessageDefValue",
            "merchantId": "100646739"
        }
    ],
    "tags": [
        "testTagType1:testTagMsg1",
        "testTagType2:testTagMsg2"
    ],
    "localizedInfo": [
        {
            "id": "dueDays",
            "text": "Antal förfallodagar",
            "value": "14"
        }
    ]
}

Data types

= Mandatory
= Optional

Response

In the response you will recieve the following:

Response parameters Description
id (string, 1) Ecsters internal order reference.
status (orderstatus, 1) Status on order.
properties (orderSubtypeProperties, 1) Payment information, only returned on successful payment. See details here.
created (timestamp, 1) Date when order was created.
amount (amount, 1) Total amount of the order.
currency (currency, 1) Currency of the order.
debitedAmount (amount, 1) Debited amount of the order.
creditedAmount (amount, 1) Credited amount of the order.
orderReference (string, 0-1) Merchant order reference.
 consumer  
  nationalId (nationalid, 0-1) Id on consumer.
  name (name, 0-1)  
    firstName (string, 1)  
    lastName (string, 1)  
    title (string, 0-1)  
  address (address, 0-1) Object describing the consumer address. The address object has the following fields:
    line1 (string, 0-1) Street name and number. Applicable for all addresses except German("DE") and Austria("AT").
    streetName (string, 0-1) Applicable for addresses in German("DE") and Austria("AT").
    streetNumber (string, 0-1) Applicable for addresses in German("DE") and Austria("AT").
    line2 (string, 0-1) C/O address, Company address field. Applicable for all addresses.
    city (string, 0-1)  
    zip (string, 0-1)  
    province (string, 0-1) Used when applicable for e.g. Region, State, Province. Mandatory for United States ("US").
    country (string, 0-1) ISO 3166-1 alpha-2 format.
contactInfo (contactInfo, 0-1) Contact information for consumer.
  email (string, 0-1)  
  cellular (object, 0-1) Cellular phone number with country code.
    country (string, 1) Country code for cellular. Specify country code with “+”, e.g. “+46” or “0046” for Sweden.
    number (string, 1) Cellular phone number. Specify number including area code but without country code.
  phone (object, 0-1) Cellular phone number with country code. Specify number including area code but without country code.
    country (string, 1) Country code for cellular. Specify country code with “+”, e.g. “+46” or “0046” for Sweden.
    number (string, 1) Phone number. Specify number including area code but without country code.
recipient Object describing a 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 .
  name  
    firstName  
    lastName  
    title  
  adress Object describing the address.
    line1 Street name and number. Applicable for all addresses except German("DE") and Austria("AT").
    streetName Applicable for addresses in German("DE") and Austria("AT").
    streetNumber Applicable for addresses in German("DE") and Austria("AT").
    line2 C/O address, Company address field. Applicable for all addresses.
    city  
    zip  
    province Used when applicable for e.g. Region, State, Province. Mandatory for United States ("US").
    country ISO 3166-1 alpha-2 format.
  contactInfo  Object describing contact information for consumer. At least one of email/cellular must be provided.
    email  
    cellular Object decsribing cellular phone number with country code
      country  Country code for cellular. Specify country code with “+”, e.g. “+46” or “0046” for Sweden
      number  Cellular phone number. Specify number including area code but without country code.
    phone  Object describing phone number with country code.
      country Country code for phone. Specify country code with “+”, e.g. “+46” or “0046” for Sweden.
      number Phone number. Specify number including area code but without country code.
tags Provide tags for statistics purposes.
salesPerson Object describing sales person contact information. Mandatory if inPersonset to true when creating ticket.    
  reference  Salesperson identifier, if provided can be used for tracking.
  nationalId National id of sales person.
  name   
    firstName  
    lastName  
    title  
  contactInfo  Object describing contact information for consumer. At least one of email/cellular must be provided.   
    email  
    cellular Object decsribing cellular phone number with country code.
      country  Country code for cellular. Specify country code with “+”, e.g. “+46” or “0046” for Sweden.
      number  Cellular phone number. Specify number including area code but without country code.
    phone  Object describing phone number with country code.
      country  Country code for phone. Specify country code with “+”, e.g. “+46” or “0046” for Sweden.
      number  Phone number. Specify number including area code but without country code.
transactions (transaction, 1-*) List of tranasctions associated to order.
  id (string, 1, read-only)  
  transactionReference (string, 0-1)  
  type (transactiontype, 1)  Type of transaction.
  created (timestamp, 1, read-only)  Timestamp when transaction was created.
   amount (amount, 0-1)  Amount on transaction.
   rows (row, 0-*)  Rows on this transaction.
    name (string, 1)  Name of row.
    quantity (double, 1)  
    unitAmount (amount, 1) (Unit amount is including vat amount)
    vatRate (percent, 1) Vat rate, sent as integer including two decimals, i.e. 6,75% is represented by 675
    partNumber (string, 0-1) Part number on row.
    description (string, 0-1)  
    unit (string, 0-1)  
    discountAmount (amount, 0-1) Discount on this row. Must fulfill 0 = discountAmount = (quantity * unitAmount)
    serials (string, 0-*)  
    fee (boolean, 0-1) true if this row is a fee. Default false.
    provided (boolean, 1, read-only) true if row has been added by Ecster. Will be set to true when invoice fee has been added automatically, else false.
localizedInfo (object, 0-*) Formatted and localized headings and values for presentation pusposes. See section Localized info/terms for usage. See below for valid values for id
  id (string, 1)  
  text (string, 1)  
  value (string, 1)  
  unit (string, 0-1)  
agreementPdfUrl (string, 0-1) url to agreement for order. Only returned for payment method PART_PAYMENT having order status READY, PARTIALLY_DELIVERED and FULLY_DELIVERED.
signUrl (string, 0-1) url to signature dialogue. Only returned for payment method PART_PAYMENT having order status PENDING_SIGNATURE.
debitConsentPdfUrl   url to debit consent document. Will only be returned for order with status READY, PARTIALLY_DELIVERED and FULLY_DELIVERED.
debitConsentInfo (object, 0-1)   Will only be returned for order with status READY, PARTIALLY_DELIVERED and FULLY_DELIVERED.
   text (string, 1) A formatted text containing sufficient debit consent information. Can be used to be presented on a slip.
  localizedInfo (object, 0-*) Formatted and localized headings and values for presentation pusposes. See section Localized info/terms for usage.
    id (string, 1)  
    text (string, 1)  
    value (string, 1)  
    unit (string, 0-1)  
merchantId (string, 1) Id of merchant who created order.
platform (object, 0-1) E-Commerce Platform information.
  reference (string, 1) Reference provided by Ecster.
  info (string, 0-1) Platform name and version.

Debit order

Debit a specific transaction

Query parameters Description
orderId (string, 1) Ecsters internal order id
Request parameters Description
type Type of transaction DEBIT
amount (amount, 1) Amount on transaction, in order currency. If transaction type is debit and amount is equal to residual order amount, order will be closed implicitly
transactionReference (string, 0-1, size max 64) Merchant’s transaction reference. If supplied, will be returned as transactionReference when requesting balance transactions
closeDebit (boolean, 0-1) True to close order for more debit transactions. Default false
  rows Object describing a row in a cart or on an order.
    name (string, 1) name of row
    quantity (double, 1)  
    unitAmount (amount, 1) unit amount is including vat amount
    vatRate (percent, 1) vat rate, sent as integer including two decimals, i.e. 6,75% is represented by 675
    partNumber (string, 0-1) part number on row
    description (string, 0-1) description on row
    unit (string, 0-1) e.g st, kg 
    discountAmount (amount, 0-1) discount on this row. Can not be negative for the total row amount (quantity * unitAmount)
    serials (string, 0-*)  
    fee (boolean, 0-1) true if this row is a fee. Default false
    provided (boolean, 1, read-only) true if row has been added by Ecster. Will be set to true when invoice fee has been added automatically, else false
message (string, 0-1, size max 256  message to consumer

Post request

To debit an order, send the above paramters orderId, type, amount, transactionReference, closeDebit, rows and message via a server-side call to our REST API. 

JSON example

Post /v1/orders/<orderId>/transactions

Request

Headers

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

Query parameters

orderId string

Ecsters internal order reference

Body

{
  "type":"DEBIT",
  "amount":15000,
  "transactionReference":"transRef100",
  "message":"TestMessageDefValue",
  "rows":[
    {
      "name":"Test name def value",
      "quantity":1.0,  
      "unitAmount":15000,
      "vatRate":2500,
      "partNumber":"00012",
      "description":"TestDescription",
      "unit":"st",
      "discountAmount":0,
      "serials":[],
      "fee":false,
      "provided":false
    }
  ]
}

Response 201 Created

Body

{
    "orderStatus": "FULLY_DELIVERED",
    "transaction": {
        "id": "5HKT3r1XdgyjPoLhGYvF",
        "transactionReference": "transRef100",
        "type": "DEBIT",
        "created": "2019-02-14T11:50:16+01:00",
        "amount": 15000,
        "rows": [
            {
                "name": "Test name def value",
                "quantity": 1,
                "unitAmount": 15000,
                "vatRate": 2500,
                "partNumber": "00012",
                "description": "TestDescription",
                "unit": "st",
                "discountAmount": 0,
                "serials": [],
                "fee": false
            }
        ],
        "message": "TestMessageDefValue",
        "merchantId": "56684964"
    }
}

Data types

= Mandatory
= Optional
type transactiontype

Type of transaction

amount amount

Amount on transaction

transactionReference string
closeDebit boolean

true to close order for more debit transactions. Default false

message string

message to consumer

row

Object describing a row in a cart or on an order. The row object has the following fields

name string

Name of row

quantity double
unitAmount amount

Unit amount is including vat amount

vatRate percent

Vat rate, sent as integer including two decimals, i.e. 6,75% is represented by 675

partNumber string

Part number on row

description string
unit string
discountAmount amount

Discount on this row. Must fulfill 0 = discountAmount = (quantity * unitAmount)

serials string
fee boolean

True if this row is a fee. Default false

provided boolean (read-only)

True if row has been added by Ecster. Will be set to true when invoice fee has been added automatically, else false

Response

In the response you will recieve the following:

Response parameters Description
orderStatus (orderstatus, 1) status on order, after transaction has been created
transaction (transaction, 1) created transaction
  id (string, 1, read-only)  
  transactionReference (string, 0-1)  
  type (transactiontype, 1) type of transaction
  created (timestamp, 1, read-only) timestamp when transaction was created
  amount (amount, 0-1) amount on transaction
  rows Object describing a row in a cart or on an order.
    name  name of row
    quantity  
    unitAmount  unit amount is including vat amount
    vatRate vat rate, sent as integer including two decimals, i.e. 6,75% is represented by 675
    partNumber  part number on row
    description description on row
    unit e.g st, kg 
    discountAmount  discount on this row. Can not be negative for the total row amount (quantity * unitAmount)
    serials  
    fee true if this row is a fee. Default false.
    provided true if row has been added by Ecster. Will be set to true when invoice fee has been added automatically, else false.
message (string, 0-1) message to consumer
properties (transactionSubtypeProperties, 1, read-only) Object describing transactionSubtypeProperties
  PARTPAYMENT_SE_1  
  INVOICE_SE_1  
   
 dueDate (date, 1)  
     ocr (string, 1)  
    invoiceNumber (string, 1)  
  CARD_1  
billPdfUrl (string, 0-1, read-only) url to bill for transaction
 debitTransactionId (string, 0-1) Object describing phone number with country code
merchantId (string, 1)   id of merchant who created the transaction

Credit order

Credit a specific transaction

Query parameters Description
orderId (string, 1) Ecsters internal order id
Request parameters Description
type Type of transaction CREDIT
amount (amount, 1) Amount on transaction, in order currency. If transaction type is debit and amount is equal to residual order amount, order will be closed implicitly
transactionReference (string, 0-1, size max 64) Merchant’s transaction reference. If supplied, will be returned as transactionReference when requesting balance transactions
debitTransaction (string, 1) Reference to associated debit transaction (id on custom object transaction)
closeDebit (boolean, 0-1) True to close order for more debit transactions. Default false
  rows Object describing a row in a cart or on an order.
    name (string, 1) name of row
    quantity (double, 1)  
    unitAmount (amount, 1) unit amount is including vat amount
    vatRate (percent, 1) vat rate, sent as integer including two decimals, i.e. 6,75% is represented by 675
    partNumber (string, 0-1) part number on row
    description (string, 0-1) description on row
    unit (string, 0-1) e.g st, kg 
    discountAmount (amount, 0-1) discount on this row. Can not be negative for the total row amount (quantity * unitAmount)
    serials (string, 0-*)  
    fee (boolean, 0-1) true if this row is a fee. Default false
    provided (boolean, 1, read-only) true if row has been added by Ecster. Will be set to true when invoice fee has been added automatically, else false
message (string, 0-1, size max 256  message to consumer

Post request

To credit an order, send the above paramters orderId, type, amount, transactionReference, debitTransaction, closeDebit, rows and message via a server-side call to our REST API. 

JSON example

Post /v1/orders/<orderId>/transactions

Request

Headers

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

Query parameters

orderId string

Ecsters internal order reference

Body

{
  "type":"CREDIT",
  "amount":15000,
  "transactionReference":"transRef100",
  "debitTransaction": "5HKT3r1XdgyjPoLhGYvF",
  "message":"TestMessageDefValue",
  "rows":[
    {
      "name":"Test name def value",
      "quantity":1.0,  
      "unitAmount":15000,
      "vatRate":2500,
      "partNumber":"00012",
      "description":"TestDescription",
      "unit":"st",
      "discountAmount":0,
      "serials":[],
      "fee":false,
      "provided":false
    }
  ]
}

Response 201 Created

Body

{
    "orderStatus": "FULLY_DELIVERED",
    "transaction": {
        "id": "UnbFrK9wjMeacWTIDVee",
        "transactionReference": "transRef100",
        "type": "CREDIT",
        "created": "2019-02-14T11:57:13+01:00",
        "amount": 15000,
        "rows": [
            {
                "name": "Test name def value",
                "quantity": 1,
                "unitAmount": 15000,
                "vatRate": 2500,
                "partNumber": "00012",
                "description": "TestDescription",
                "unit": "st",
                "discountAmount": 0,
                "serials": [],
                "fee": false
            }
        ],
        "message": "TestMessageDefValue",
        "merchantId": "56684964"
    }
}

Data types

= Mandatory
= Optional

Response

In the response you will recieve the following:

Response parameters Description
orderStatus (orderstatus, 1) status on order, after transaction has been created
transaction (transaction, 1) created transaction
  id (string, 1, read-only)  
  transactionReference (string, 0-1)  
  type (transactiontype, 1) type of transaction
  created (timestamp, 1, read-only) timestamp when transaction was created
  amount (amount, 0-1) amount on transaction
  rows Object describing a row in a cart or on an order.
    name  name of row
    quantity  
    unitAmount  unit amount is including vat amount
    vatRate vat rate, sent as integer including two decimals, i.e. 6,75% is represented by 675
    partNumber  part number on row
    description description on row
    unit e.g st, kg 
    discountAmount  discount on this row. Can not be negative for the total row amount (quantity * unitAmount)
    serials  
    fee true if this row is a fee. Default false.
    provided true if row has been added by Ecster. Will be set to true when invoice fee has been added automatically, else false.
message (string, 0-1) message to consumer
properties (transactionSubtypeProperties, 1, read-only) Object describing transactionSubtypeProperties
  PARTPAYMENT_SE_1  
  INVOICE_SE_1  
   
 dueDate (date, 1)  
     ocr (string, 1)  
    invoiceNumber (string, 1)  
  CARD_1  
billPdfUrl (string, 0-1, read-only) url to bill for transaction
 debitTransactionId (string, 0-1) Object describing phone number with country code
merchantId (string, 1)   id of merchant who created the transaction

Annul order

Annul a specific transaction

Query parameters Description
orderId (string, 1) Ecsters internal order id
Request parameters Description
type Type of transaction ANNUL
amount (amount, 1) Amount on transaction, in order currency. If transaction type is debit and amount is equal to residual order amount, order will be closed implicitly
transactionReference (string, 0-1, size max 64) Merchant’s transaction reference. If supplied, will be returned as transactionReference when requesting balance transactions
closeDebit (boolean, 0-1) True to close order for more debit transactions. Default false
  rows Object describing a row in a cart or on an order.
    name (string, 1) name of row
    quantity (double, 1)  
    unitAmount (amount, 1) unit amount is including vat amount
    vatRate (percent, 1) vat rate, sent as integer including two decimals, i.e. 6,75% is represented by 675
    partNumber (string, 0-1) part number on row
    description (string, 0-1) description on row
    unit (string, 0-1) e.g st, kg 
    discountAmount (amount, 0-1) discount on this row. Can not be negative for the total row amount (quantity * unitAmount)
    serials (string, 0-*)  
    fee (boolean, 0-1) true if this row is a fee. Default false
    provided (boolean, 1, read-only) true if row has been added by Ecster. Will be set to true when invoice fee has been added automatically, else false
message (string, 0-1, size max 256  message to consumer

Post request

To annul an order, send the above paramters orderId, type, amount, transactionReference, rows and message via a server-side call to our REST API. 

JSON example

Post /v1/orders/<orderId>/transactions

Request

Headers

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

Query parameters

orderId string

Ecsters internal order reference

Body

{
  "type":"ANNUL",
  "amount":300000,
  "transactionReference":"transRef100",
  "message":"TestMessageDefValue",
  "rows":[
    {
      "name":"Test name def value",
      "quantity":1.0,  
      "unitAmount":300000,
      "vatRate":2500,
      "partNumber":"00012",
      "description":"TestDescription",
      "unit":"st",
      "discountAmount":0,
      "serials":[],
      "fee":false,
      "provided":false
    }
  ]
}

Response 201 Created

Body

{
    "orderStatus": "ANNULLED",
    "transaction": {
        "id": "FpZxSYBZ8OGI7FsRNHxP",
        "transactionReference": "transRef100",
        "type": "ANNUL",
        "created": "2019-02-14T11:59:27+01:00",
        "amount": 0,
        "rows": [
            {
                "name": "Test name def value",
                "quantity": 1,
                "unitAmount": 300000,
                "vatRate": 2500,
                "partNumber": "00012",
                "description": "TestDescription",
                "unit": "st",
                "discountAmount": 0,
                "serials": [],
                "fee": false
            }
        ],
        "message": "TestMessageDefValue",
        "merchantId": "56684964"
    }
}

Data types

= Mandatory
= Optional

Response

In the response you will recieve the following:

Response parameters Description
orderStatus (orderstatus, 1) status on order, after transaction has been created
transaction (transaction, 1) created transaction
  id (string, 1, read-only)  
  transactionReference (string, 0-1)  
  type (transactiontype, 1) type of transaction
  created (timestamp, 1, read-only) timestamp when transaction was created
  amount (amount, 0-1) amount on transaction
  rows Object describing a row in a cart or on an order.
    name  name of row
    quantity  
    unitAmount  unit amount is including vat amount
    vatRate vat rate, sent as integer including two decimals, i.e. 6,75% is represented by 675
    partNumber  part number on row
    description description on row
    unit e.g st, kg 
    discountAmount  discount on this row. Can not be negative for the total row amount (quantity * unitAmount)
    serials  
    fee true if this row is a fee. Default false.
    provided true if row has been added by Ecster. Will be set to true when invoice fee has been added automatically, else false.
message (string, 0-1) message to consumer
properties (transactionSubtypeProperties, 1, read-only) Object describing transactionSubtypeProperties
  PARTPAYMENT_SE_1  
  INVOICE_SE_1  
   
 dueDate (date, 1)  
     ocr (string, 1)  
    invoiceNumber (string, 1)  
  CARD_1  
billPdfUrl (string, 0-1, read-only) url to bill for transaction
 debitTransactionId (string, 0-1) Object describing phone number with country code
merchantId (string, 1)   id of merchant who created the transaction

Request test account