Shopping Service API

The Paylogic Shopping Service API is a RESTful API that allows you to view events and products on sale in your application, link to Paylogic’s ticketshop, or directly place an order.

Getting started

Authentication

Authentication is done using Basic Access Authentication over HTTPS.

An example using curl

curl https://shopping-api.paylogic.com -u <username>:<password>

An example using jQuery

$.ajax
({
  type: "GET",
  url: "https://shopping-api.paylogic.com",
  dataType: 'json',
  async: false,
  headers: {
    "Authorization": "Basic " + btoa(USERNAME + ":" + PASSWORD)
  },
  success: function (data){
    alert(data);
  }
});

An example using Python (you will need the restnavigator package installed)

>>> import restnavigator
>>> N = restnavigator.Navigator.hal('https://shopping-api.paylogic.com')
>>> N.authenticate(('user', 'pass'))
>>> N.links()
{
  u'profile': HALNavigator(Shopping-APIPaylogic.https:.shopping-api-docs.paylogic.com.resources.root.html),
  u'shop:bill': PartialNavigator(Shopping-APIPaylogic.bill{?products,payment_method,shipping_method,country,external_purchase_amount}),
  u'shop:order': HALNavigator(Shopping-APIPaylogic.orders),
  u'help': HALNavigator(Shopping-APIPaylogic.https:.shopping-api-docs.paylogic.com),
  u'shop:ticket_transfer_approval': PartialNavigator(Shopping-APIPaylogic.ticket-transfer-approvals.{uid}),
  u'shop:tickets': PartialNavigator(Shopping-APIPaylogic.tickets?event={event}&code={barcode}),
  u'self': HALNavigator(Shopping-APIPaylogic),
  u'shop:event': PartialNavigator(Shopping-APIPaylogic.events{?merchant_name,title,subtitle,sale_start,sale_end,event_start,event_end,location_name,location_postal_code,location_city,location_country,genre,artist}),
  u'shop:ticket': PartialNavigator(Shopping-APIPaylogic.tickets.{uid}),
  u'shop:status': HALNavigator(Shopping-APIPaylogic.status)
}

Note

Important: Be careful to never hand out your username and password, or include it in any code that will be visible to other parties! This includes client side JavaScript code in your application.

Querying for events and products

A very common use case is to search for available Events and their Products. Let’s get a list of events.

[GET] https://shopping-api.paylogic.com/events
{
    "_links": {
        // ...
    },
    "item_count": 2,
    "_embedded": {
        "shop:event": [
            {
                "_links": {
                    "self": { "href": "https://shopping-api.paylogic.com/events/0c2019503cd666fb35c5a3dbd7bafe86" },
                    "curies": [{ "name": 'shop', "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html", "templated": true, "type": "text/html" }],
                    "profile": { "href": "https://shopping-api-docs.paylogic.com/documentation/event.html", "type": "text/html" },
                    "shop:products": { "href": "https://shopping-api.paylogic.com/products?event=https://shopping-api.paylogic.com/events/0c2019503cd666fb35c5a3dbd7bafe86" },
                    "shop:ticketshop": { "href": "https://frontoffice.paylogic.nl/?event_id=36890&point_of_sale_id=13996", "type": "text/html" }
                },
                "uid": "0c2019503cd666fb35c5a3dbd7bafe86",
                "merchant_name": "Ms. Christiana Lesch events",
                // ...
            }
        ]
    }
}

We can now use the shop:products link to get a list of Products for this specific Event.

[GET] https://shopping-api.paylogic.com/products?event=https://shopping-api.paylogic.com/events/0c2019503cd666fb35c5a3dbd7bafe86

Purchasing flow

Here is a quick overview of the flow of placing an order.

[GET] https://shopping-api.paylogic.com/events
[GET] https://shopping-api.paylogic.com/products/0c2019503cd666fb35c5a3dbd7bafe86

[GET] https://shopping-api.paylogic.com/products?event=/events/0c2019503cd666fb35c5a3dbd7bafe86
  • Store the products and quantities on the client side as a list.
[
    { "product": "https://shopping-api.paylogic.com/products/0c2019503cd666fb35c5a3dbd7bafe86", "quantity": 2 }
]
[GET] https://shopping-api.paylogic.com/bill?products=https://shopping-api.paylogic.com/products/0c2019503cd666fb35c5a3dbd7bafe86,2&country=NL
  • Select a payment and a shipping method method and compute the Bill.
[GET] https://shopping-api.paylogic.com/bill?products=https://shopping-api.paylogic.com/products/0c2019503cd666fb35c5a3dbd7bafe86,2&country=NL&payment_method=ghr57d5h3gd162fb35c5a3db57ghrydg&shipping_method=87a5quvndhe162fb357alt872705zr2j
  • Place an order with the selected data.
[POST] https://shopping-api.paylogic.com/orders
{
    "products": [
        { "product": "https://shopping-api.paylogic.com/products/0c2019503cd666fb35c5a3dbd7bafe86", "quantity": 2 }
    ],
    "consumer": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1986-12-30",
        "email": "john.doe@paylogic.eu",
        "gender": "1",
        "address": "Nieuwe Boteringestraat 28",
        "postal_code": "9716 JJ",
        "city": "Groningen",
        "country": "NL",
        "ip": "192.168.1.1"
    },
    "payment_method": "ghr57d5h3gd162fb35c5a3db57ghrydg",
    "shipping_method": "87a5quvndhe162fb357alt872705zr2j"
}

Note

Depending on the type of application you are developing it could be that you cannot provide the consumer’s ip address (i.e. client side javascript), in these cases we will instead use the remote address.

  • The response contains the Orders for payment, fulfillment and other details.

Payment and redirect

When a purchasing flow is completed, you receive an Order. If the payment has to be processed by Paylogic, the Order will contain a payment_url.

"payment_url": { "href": "https://payments.paylogic.com?redirect=https://psp.paylogic.com/consumer/123" }

You should navigate users to this url to pay for their Order. When the payment is either successful or failed, users will be redirected to a url of your choice that has been set for your api key. At the moment this can only be configured by Paylogic for your app. This url will contain the below query parameters, which you can use to provide additional information to users.

Parameter Description
order The URI of the order.
order_state The state of the order. See: Order statuses.

Personalization

When an order is completed, and event tickets need to be personalized, you can submit consumer information for the purchased tickets via the Consumers resource.

Note

Information about retrieving tickets can be found here.

[POST] https://shopping-api.paylogic.com/consumers
{
    "consumers": [
        {
            "tickets": ["https://shopping-api.paylogic.com/tickets/5959f610ba0f4b61b30750d5382f228c"],
            "address": "Some other street 32",
            "city": "Some other city",
            "country": "UK",
            "date_of_birth": "1990-01-01",
            "email": "some.one@example.com",
            "first_name": "Some",
            "last_name": "One",
            "gender": 2,
            "phone_number": "555-55555",
            "postal_code": "1235"
        }
    ]
}

Re-issue

Paylogic allows for the possibility to re-issue an existing ticket to a new customer.

Note

Information about retrieving tickets can be found here. You will also need to provide the new consumer’s personal details.

[POST] https://shopping-api.paylogic.com/orders
{
    "tickets": [
            "https://shopping-api.paylogic.com/tickets/a2e37ee17474417a87259b02b674da9a",
            "https://shopping-api.paylogic.com/tickets/5959f610ba0f4b61b30750d5382f228c"
    ],
    "consumer": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1986-12-30",
        "email": "john.doe@paylogic.eu",
        "gender": "1",
        "address": "Nieuwe Boteringestraat 28",
        "postal_code": "9716 JJ",
        "city": "Groningen",
        "country": "NL",
        "ip": "192.168.1.1"
    },
}

Entities and concepts

The API operates on a number of entities and concepts which came to the surface while modelling the shopping for events domain. Often (but not always) these will map to a resource. It is however useful to look at them first at a conceptual level before moving on.

Entities

The main entities in the API are the events, products, consumers, baskets, bill and orders.

An Event is, as the name implies, an event that is organised by a merchant. It happens at a certain time on a certain location, and tickets can be sold for these events.

A Product is an item that is for sale in the API in the context of an event. It has a price and can either be available or not. This is the entity that can be sold.

A Ticket consumer is a person that owns a ticket.

An Order consumer is a person that is interested in buying one or more products. When placing an order via the API using payments processed by Paylogic, order consumer information is always required.

A Consumer either ticket consumer or order consumer or both. Can be referenced in an order for purchases or as a ticket owner for visiting an event.

A Bill is an overview of what has to be paid for a given collection of products (be it just a provided collection or a basket containing such a collection). It displays the total for all the products provided, but also the service, shipment and payment costs. Based on the bill, an order consumer can select a payment method and a shipping method.

An Order is a container for products for which a checkout process has started (where usually a payment is involved as well) or has been completed. An order is created from a list of products, which can either come from a basket or by providing the products.

Concepts

Shipment is the process of getting the product to the customer using a certain shipping method. For physical products this will be with some kind of postal service, and for digital products emails are usually used. Another term for this is fulfillment.

Payment is a financial transaction that will allow an order consumer to obtain one or more products. A payment is processed using a certain payment method. Which payment method can be used depends on a number of factors, amongst which the total amount of the order, the country of the client and the configuration of an event by a merchant.

Combo product is a product coupled with one or more products and is automatically selected when any of these products are selected. For example, if Product B is a combo product of Product A, then if one selects Product A, Product B will automatically be part of the product selection. A real life example would be that one gets a free parking ticket when selecting a regular ticket for a concert.

API conventions

Media type

For our media type we use hal+json. A short overview of conventions:

  • Links are located in a “_links” element. A link can be either one link, or a list of links. There will always be a self link. The self link will point to the same URL that you used to access the current representation (including the query parameters).
  • Embedded resources can be found in an “_embedded” element.
  • Properties of a resource are represented like regular json.
  • Every resource will have a “profile” link relation for documentation purposes.
  • We use CURIES (Compact URIs) to namespace custom link relations. As such, every resource will have a “curies” link relation. For example:
{
    "_links": {
        "curies": [{ "name": "shop", "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html", "templated": true, "type": "text/html" }],
        "self": { "href": "https://shopping-api.paylogic.com/orders/87a2195h3gd162fb35c5a3dbd7bapo1l" },
        "profile": { "href": "https://shopping-api-docs.paylogic.com/documentation/order.html", "type": "text/html" },
        "payment": { "href": "https://payments.paylogic.com?redirect=https://psp.paylogic.com/consumer/123", "type": "text/html" },
        "shop:etickets": { "href": "https://download.paylogic.com/eticket/sdfsdf235r245wsdgfw5235", "type": "text/html" },
        "shop:ordercancellation": { "href": "https://shopping-api.paylogic.com/ordercancellation", "type": "text/html" }
    },
}

In this case the shop:etickets and shop:ordercancellation references can be used to discover the documentation for these relationships by filling their values, etickets and ordercancellation, into the CURIE link. This will result in https://shopping-api-docs.paylogic.com/documentation/etickets.html and https://shopping-api-docs.paylogic.com/documentation/ordercancellation.html respectively.

URLs

We don’t see the need to burden you when building a client with constructing URLs (or even inspecting them), so we use absolute URLs wherever possible. This means that there will be no need to do anything with URLs themselves; you can simply follow the link relations.

Contextual documentation

Documentation of the resources themselves is accessible by following the “profile” link relation on the resource. These profiles describe the data of the resource, the method it accepts, which query parameters are permitted, and so on.

In addition, on the root resource a link with the relation “help” can be found. This link points to the root of the documentation for the API.

Roles and Permissions

Depending on how your access credentials are configured you either have access to or are disallowed access to certain properties or resources through roles. The role your application has depends on your use case and implementation details. The role is determined by us and can be based on the type of contract you have to use the API.

In the rest of the documentation we’ll indicate differences for the roles in a note like this:

Note

I am a note.

The system has the following roles available:

Role name Resources you have access to Notes
default event, product  
spa-sales event, product, bill, create order Consumer IP will always use the remote address.
sales event, product, bill, order (including create order)  
merchant event, product (including availability), bill order (including create order)  

Searching in collections via query parameters

When searching in collections, all specified query parameters (from the documentation or from the templated link in the representation) can be searched on for exact matches. In addition, it is often also possible to do more complicated queries.

The syntax for this is best explained by example:

Query parameter Description
/orders?total=20 All orders with as total exactly 20.
/orders?total__gte=20 All orders with as total greater than or equal to 20.
/orders?created__lt=2014-05-01 All orders created before the 1st of May 2014.
/orders?consumer.firstname__startswith=tom All orders for any consumer with a first name starting with “tom”.

The following options are only available for amounts, numbers, and date and time fields.

Condition Description
__gt Greater than (or after)
__lte Less than or equal
__gte Greater than or equal

The following options are only available for strings:

Condition Description
__startswith The string starts with the provided string.

Internationalization

Any values that are internationalized in our system (such as the name of an event) will return all languages and translations in a dictionary.

{
    "seat_name": {
        "en": "Seat",
        "nl": "Stoel",
        "de": "Sitzplatz",
        "fr": "Siège",
        "es": "Asiento",
        "pt": "Assento",
        "tr": "Sandalye",
        "pl": "Miejsce",
        "ru": "сиденья"
    }
}

At the time of writing, we support English, Dutch, German, French, Spanish, Portuguese, Turkish, Polish and Russian. All of these will be included.

Dates and time

The format of our dates and times follows ISO 8601, specifically in the format “YYYY-MM-DD hh:mm:ssZ” for datetimes, and “YYYY-MM-DD” for dates. All times are communicated in UTC (as shown by a trailing Z).

{
    "sale_start": "2014-01-28T20:25:00Z",
    "sale_end": "2014-06-09T17:25:00Z",
    "date_of_birth": "1986-12-30"
}

Amounts and currencies

All fields with type amount are included using a JSON object. They have two attributes, namely “currency” and “amount”. For “currency”, we use the ISO 4217 alphabetic currency codes, and for amount we use a number, always with a decimal part.

{
    "price": {
        "currency": "EUR",
        "amount": 10.30
    }
}

Country and state codes

To communicate country codes we use the country codes as specified in ISO 3166-1, specifically the two-letter country codes from ISO 3166-1 alpha-2. For states and other subdivisions, we use the codes as specified in ISO 3166-2.

{
    "country_of_residence": "NL",
    "shipment_country": "DE",
    "state": "US-AL"
}

Empty values for properties

If for a regular string field no value is known in our system, we will return an empty string (so merely “”). For multilingual fields, all languages will be included but those with no value will also have the empty string. A list field with no items will be displayed in the response as an empty list.

For objects and integer fields, we will display the value “null”. This was chosen over just removing the key, to be more explicit and to always specify all fields, so no confusion can arise over fields having to be there or not.

{
    "title": {
        "en": "",
        "nl": "",
        "de": "",
        "fr": "",
        "es": "",
        "pt": "",
        "tr": "",
        "ru": ""
    },
    "image_url": "",
    "minimum_age": null,
    "price": null,
    "genres": [
        // ...
    ]
}

HTTP verbs

We support GET, POST, PUT and DELETE (when each method is supported and makes sense, of course). We don’t use PATCH.

OPTIONS can be used to show the accepted methods and link you to an HTML page with further documentation.

# Request
OPTIONS /bill HTTP/1.1
Host: https://shopping-api.paylogic.com

# Response
HTTP/1.1 200 OK
Allow: OPTIONS, GET, POST
Link: <https://shopping-api-docs.paylogic.com/documentation/bill.html>; type=text/html; rel=help

Error handling

Errors usually simply return the corresponding HTTP status codes. If more information is required, we will provide more details in the response body. As mediatype for the error response body we use hal+json. The value of “logref” will be a UID.

Note

Please note that if you check only the properties of the response, for example the _links property you will not see the actual error message but only the help link.

{
    "logref": "<UID>",
    "message": "A payment method is needed for the creation of an order. Please retrieve a bill for the selected products to see which payment methods are available.",
    "type": "BAD_REQUEST",
    "_links": {
        "help": {
            "href": "http://shopping-api-docs.paylogic.com/documentation/orders.html",
            "type": "text/html"
        }
    },
    "details": null
}

Deprecation Policy

If we make changes to the API the existing field will have a deprecation warning attached, with a reference to the new field that should be used. It is up to the calling application to check for any deprecation warnings and use the new field instead. After a certain period, usually two weeks, the old field will be removed and applications using it will no longer work.

Note

Please note that due to a bug in the restnavigator package the deprecation warning might not be shown. If you run into any problems please feel free to contact us.

Representation objects

The following representation objects (or complex types, if you will) can be found in the representation of certain resources: