Our API for orders includes the following functions:

Submit orders: Create an order, and get an orderId for it
Get orders by date: Get all orders on a specific date for a specific merchant
Get order: Get a specific order with an orderId
Purchase an order for a buyer: Create an order and confirm it. The merchant is required to have purchase access for the buyer used. More details in Purchase Access.

Table of Contents

minLevel	1
maxLevel	1

To use this API you have to authenticate. See our Authentication document for instructions on how authentication works.

This API is a REST service. Further documentation can be found at api.pei.is.

Workflow

The most common Orders flow is:

Authenticate user to get bearer token, see Authentication
Create an order to get the orderId using POST: https://api.pei.is/api/orders
Redirect customer to https://gattin.pei.is/orderId
Get a callback object sent as POST to the PostbackUrl when the buyer confirms the order
1. This object includes OrderId, PurchaseId and MandateId when it is applicable

Environments

Demo

Use merchantId: 4 and URL endpoint https://externalapistaging.pei.is/api/orders

Production

Contact customer support for information about he production environment.

https://api.pei.is/api/orders

Submit order

Used to submit a pending order.

POST /api/orders

Schema

Order

Name

Data Type

Required

Description

Example

MerchantId

Integer

Status

colour	Green
title	true

A unique ID that Greiðslumiðlun provides

4

Amount

Numeric

Status

colour	Green
title	true

TotalAmount of purchase

9990

Reference

String

Status

title	false

A reference in Order in the merchant's system

REF1566

ExpirationDate

DateTime

Status

title	false

An expiration date for the order. Default is one day into the future

2018-07-31 13:33:33.337

SuccessReturnUrl

String

Status

title	false

A URL that the buyer will be redirected to when he finishes the purchase. If no URL is provided then the buyer will be redirected to a receipt page.

http://someshop.com/Success

CancelReturnUrl

String

Status

title	false

A URL that the buyer will be redirected to if he cancels the purchase. If there is no URL provided then the cancel button will not be displayed to the buyer.

http://someshop.com/Cancel

PostbackUrl

String

Status

title	false

A URL that the Order ID and more will be posted to when the Order becomes confirmed.

Here’s an example of the object that gets sent to this URL looks like this:

Code Block

language	json

{
  "orderId" : "ZsZUibpv0WAe77sGvYrm1lu0AM52D23N". 
  "purchaseId" : 966127, 
  "mandateId" : "7gcuh8pMcFju1gNbjGEZ7sf0JazKNhIz"
}

http://someshop.com/Confirm

SequenceType

String

Status

colour	Green
title	true

Sequence type of order:

OneOff (0) implies that the order is, in reality, not a part of a sequence of recurring orders but rather a stand-alone order
First (1) implies that the order is the first in a sequence of recurring orders and will need to be manually paid for by going to the payment gateway which is the CheckoutUrl property in the response
Recurring (2) implies that the order is a non-first order in a sequence of recurring orders and will be automatically charged

OneOff

MandateId

String

Status

title	false

Payment card authentication id, only applies if SequenceType is Recurring otherwise the mandateId should be null.

Buyer

Status

colour	Green
title	true

Encapsulation of the buyers information. See documentation below.

Items[n].Name

String

Status

colour	Green
title	true

Name of Item

Helicopter

Items[n].Code

String

Status

title	false

A reference in Order in the merchant's system

SUB555

Items[n].Quantity

Numeric

Status

title	false

Quantity of item

3000

Items[n].Unit

String

Status

title	false

Measuring unit of item

Kg.

Items[n].UnitPrice

Numeric

Status

title	false

Price of single item

1500

Items[n].Amount

Numeric

Status

title	false

Total price of item

4500

Items[n].GroupName

String

Status

title	false

Optional group name, for when certain items need to be grouped together and only one of them selected by the buyer.

Flying vehicles

Items[n].IsOptional

Boolean

Status

title	false

When set to true the item becomes optional, default not optional. This has no effect on items with group names.

false

Items[n].IsDefaultSelected

Boolean

Status

title	false

When set to true, group items and optional items become selected when the order is created. Only one group item can be default selected.

true

Buyer

Name

Data Type

Required

Description

Example

Buyer.Name

String

Status

title	false

Name of buyer

John Johnson

Buyer.Ssn

String

Status

title	false

Ssn of buyer

0102882849

Buyer.Email

String

Status

title	false

Email of buyer

someemail@somedomain.com

Buyer.MobileNumber

String

Status

title	false

Cellphone of buyer

1234567

SubscriptionOptions

Only required if Order is a subscription, this is rarely used.

Name

Data Type

Required

Description

Example

SubscriptionOptions.StartDate

String

Status

colour	Green
title	true

Subscription start date. Format: dd-mm-yyyy

28.6.2015

SubscriptionOptions.Frequency

String

Status

colour	Green
title	true

'Week' for weekly subscriptions 'Month' for montly subscriptions

Week

SubscriptionOptions.FrequencyInterval

Integer

Status

colour	Green
title	true

Number of weeks/months between due dates

5

SubscriptionOptions.Cycles

String

Status

colour	Green
title	true

How many due dates there should be in the subscription

7

Example

Input

Code Block

language	json

{
  "merchantId": 4,
  "buyer": {
    "name": "John Johnson",
    "ssn": "0000000009",
    "email": "example@example.com",
    "mobileNumber": "1234567"
  },
  "amount": 15000,
  "reference": "REF155", 
  "expirationDate": "2018-05-13T12:33:48.008Z",
  "subscriptionOptions": {
    "startDate": "2016-05-12",
    "frequencyInterval": 2,
    "frequency": "Week",
    "cycles": 5
  },
  "sequenceType": "OneOff",
  "successReturnUrl": "http://www.zombo.com",
  "cancelReturnUrl": "http://www.google.com",
  "postbackUrl": "http://www.msn.com/",
  "items": [
    {
      "code": "SUB555",
      "name": "TV subscription",
      "quantity": 1,
      "unit": "stk.",
      "unitPrice": 5000,
      "amount": 5000
    }
  ]
}

Output

Code Block

language	json

{
  "orderId": "fdfQQ33gdgWfgGoP642"
}

Get orders by date

Used to get all orders on a specific date for a merchant.

GET /api/orders?merchantId=1&date=2016-01-20

Example

Output

Code Block

language	json

[
  {
    "orderId": "adf153j1kjkjgdg",
    "merchantId": 4,
    "buyer": {
      "name": "John",
      "ssn": "0000000001",
      "email": "example@example.com",
      "mobileNumber": "1234567"
    },
    "amount": 10000,
    "reference": "abc123",
    "expirationDate": "2016-06-22T12:33:48.008Z",
    "subscriptionOptions": {
      "startDate": "2016-06-21",
      "frequencyInterval": 1,
      "frequency": "Week",
      "cycles": 5
    },
    "successReturnUrl": "http://www.example.com",
    "cancelReturnUrl": "http://www.example.com",
    "postbackUrl": "http://www.example.com",
    "items": [
      {
        "code": "123abc",
        "name": "Some Item",
        "quantity": 1,
        "unit": "KG",
        "unitPrice": 300,
        "amount": 1000
      }
    ],
    "isConfirmed": true
  }
]

Get order

Used to get a specific Order.

GET /api/orders/ffmPoSnWFUjs0W9u45es0elUKBnpFRSf

Example

Output

Code Block

language	json

{
  "orderId": "adf153j1kjkjgdg",
  "merchantId": 4,
  "buyer": {
    "name": "John",
    "ssn": "0000000001",
    "email": "example@example.com",
    "mobileNumber": "1234567"
  },
  "amount": 10000,
  "reference": "abc123",
  "expirationDate": "2016-06-22T12:33:48.008Z"
  "subscriptionOptions": {
    "startDate": "2016-06-21",
    "frequencyInterval": 1,
    "frequency": "Week",
    "cycles": 5
  },
  "successReturnUrl": "http://www.example.com",
  "cancelReturnUrl": "http://www.example.com",
  "postbackUrl": "http://www.example.com",
  "items": [
    {
      "code": "123abc",
      "name": "Some Item",
      "quantity": 1,
      "unit": "KG",
      "unitPrice": 300,
      "amount": 1000
    }
  ],
  "isConfirmed": true
}

Purchase an order for a buyer

To make purchases like this, you need access to do it for each buyer, see Purchase Access for more details.

POST /api/orders/pay

Schema

Orders/Pay

Name

Data Type

Required

Description

Example

MerchantId

Integer

Status

colour	Green
title	true

A unique ID that Greiðslumiðlun provides

55879

Amount

Numeric

Status

colour	Green
title	true

TotalAmount of purchase

9990

Reference

String

Status

title	false

A reference in Order in your own system

REF1566

PostbackUrl

String

Status

title	false

A URL that the Order ID will be posted to when the Order becomes confirmed.

http://someshop.com/Confirm

Buyer

Encapsulation of the buyers information. See documentation below.

Items[n].Name

String

Status

colour	Green
title	true

Name of Item

Helicopter

Items[n].Code

String

Status

title	false

Code for the item bought in Merchant system.

SUB555

Items[n].Quantity

Numeric

Status

title	false

Quantity of item

3

Items[n].Unit

String

Status

title	false

Mesuring unit of item

Kg.

Items[n].UnitPrice

Numeric

Status

title	false

Price of single item

1500

Items[n].Amount

Numeric

Status

title	false

Total price of item

4500

Buyer

Name

Data Type

Required

Description

Example

Buyer.Name

String

Status

colour	Green
title	true

Name of buyer

John Johnson

Buyer.Ssn

String

Status

colour	Green
title	true

Ssn of buyer

0102882849

Buyer.Email

String

Status

colour	Green
title	true

Email of buyer

someemail@somedomain.com

Buyer.MobileNumber

String

Status

title	false

Cellphone of buyer

1234567

Example

Input

Code Block

language	json

{
  "merchantId": 4,
  "buyer": {
    "name": "John Johnson",
    "ssn": "0000000009",
    "email": "example@example.com",
    "mobileNumber": "1234567"
  },
  "amount": 15000,
  "reference": "REF155",
  "postbackUrl": "http://www.msn.com/",
  "items": [
    {
      "code": "SUB555",
      "name": "TV subscription",
      "quantity": 1,
      "unit": "stk.",
      "unitPrice": 5000,
      "amount": 5000
    }
  ]
}

Output

Code Block

language	json

{
  "orderId": "fdfQQ33gdgWfgGoP642"
}

Versions Compared

Old Version 13

New Version Current

Key

Workflow

Environments

Demo

Production

Submit order

Schema

Order

Buyer

SubscriptionOptions

Example

Input

Output

Get orders by date

Example

Output

Get order

Example

Output

Purchase an order for a buyer

Schema

Orders/Pay

Buyer

Example

Input

Output

Page Comparison

Versions Compared

Old Version 13

New Version Current

Key

Workflow

Environments

Demo

Production

Submit order

Schema

Order

Buyer

SubscriptionOptions

Example

Input

Output

Get orders by date

Example

Output

Get order

Example

Output

Purchase an order for a buyer

Schema

Orders/Pay

Buyer

Example

Input

Output