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.

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

Name	Data Type	Required	Description	Example
MerchantId	Integer	true	A unique ID that Greiðslumiðlun provides	4
Amount	Numeric	true	TotalAmount of purchase	9990
Reference	String	false	A reference in Order in the merchant's system	REF1566
ExpirationDate	DateTime	false	An expiration date for the order. Default is one day into the future	2018-07-31 13:33:33.337
SuccessReturnUrl	String	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	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	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: `{ "orderId" : "ZsZUibpv0WAe77sGvYrm1lu0AM52D23N". "purchaseId" : 966127, "mandateId" : "7gcuh8pMcFju1gNbjGEZ7sf0JazKNhIz" }`	http://someshop.com/Confirm
SequenceType	String	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	false	Payment card authentication id, only applies if SequenceType is Recurring otherwise the mandateId should be null.
Buyer	Buyer	true	Encapsulation of the buyers information. See documentation below.
Items[n].Name	String	true	Name of Item	Helicopter
Items[n].Code	String	false	A reference in Order in the merchant's system	SUB555
Items[n].Quantity	Numeric	false	Quantity of item	3000
Items[n].Unit	String	false	Measuring unit of item	Kg.
Items[n].UnitPrice	Numeric	false	Price of single item	1500
Items[n].Amount	Numeric	false	Total price of item	4500
Items[n].GroupName	String	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	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	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

Name	Data Type	Required	Description	Example
Buyer.Name	String	false	Name of buyer	John Johnson
Buyer.Ssn	String	false	Ssn of buyer	0102882849
Buyer.Email	String	false	Email of buyer	someemail@somedomain.com
Buyer.MobileNumber	String	false	Cellphone of buyer	1234567

SubscriptionOptions

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

Name	Data Type	Required	Description	Example

Name	Data Type	Required	Description	Example
SubscriptionOptions.StartDate	String	true	Subscription start date. Format: dd-mm-yyyy	28.6.2015
SubscriptionOptions.Frequency	String	true	'Week' for weekly subscriptions 'Month' for montly subscriptions	Week
SubscriptionOptions.FrequencyInterval	Integer	true	Number of weeks/months between due dates	5
SubscriptionOptions.Cycles	String	true	How many due dates there should be in the subscription	7

Example

Input

{
  "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

{
  "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

Get order

Used to get a specific Order.

GET /api/orders/ffmPoSnWFUjs0W9u45es0elUKBnpFRSf

Example

Output

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

Name	Data Type	Required	Description	Example
MerchantId	Integer	true	A unique ID that Greiðslumiðlun provides	55879
Amount	Numeric	true	TotalAmount of purchase	9990
Reference	String	false	A reference in Order in your own system	REF1566
PostbackUrl	String	false	A URL that the Order ID will be posted to when the Order becomes confirmed.	http://someshop.com/Confirm
Buyer	Buyer		Encapsulation of the buyers information. See documentation below.
Items[n].Name	String	true	Name of Item	Helicopter
Items[n].Code	String	false	Code for the item bought in Merchant system.	SUB555
Items[n].Quantity	Numeric	false	Quantity of item	3
Items[n].Unit	String	false	Mesuring unit of item	Kg.
Items[n].UnitPrice	Numeric	false	Price of single item	1500
Items[n].Amount	Numeric	false	Total price of item	4500

Buyer

Name	Data Type	Required	Description	Example

Name	Data Type	Required	Description	Example
Buyer.Name	String	true	Name of buyer	John Johnson
Buyer.Ssn	String	true	Ssn of buyer	0102882849
Buyer.Email	String	true	Email of buyer	someemail@somedomain.com
Buyer.MobileNumber	String	false	Cellphone of buyer	1234567