Kultswap API

This document describes how to use the Kultswap API.

Overview

API Endpoint

https://swap.kultlab.nl/api/v1

Headers

All requests should be sent with a Content-Type: application/json header.

Authentication

All requests require a basic authentication header. To generate this header:

Authorization: Basic ZnJlZDpmcmVk

Responses

Responses will be in the JSON format. Possible status codes are:

Status code Description
200 Success
401 Authentication failed
500 Error, specified in response data

GET /events

Get all events for current account.

Request attributes

Attribute Type Required Description

Example response

[
    {
        "uid": "znc6QfUsgQEHhY3G",
        "description": "My example event",
        "fee": 8
    },
    ...
]

Response attributes

Attribute Type Description
uid string Event UID
description string Description of the event
fee float Buyer's fee percentage

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect

GET /events/{uid}/products

Get all available products for a specific event.

Request attributes

Attribute Type Required Description
uid string Yes Event UID

Example response

[
    {
        "uid": "beZFLF3NZ66Q2277",
        "description": "My example product",
        "service": 0.1,
        "available": 1,
        "min": 10,
        "max": 12.5
    },
    ...
]

Response attributes

Attribute Type Description
uid string Product UID
description string Description of the product
service float Service fee
available int Number of available products of this type
min float Lowest price for product, null if none available
max float Highest price for product, null if none available

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match event
500 EVENT_NOT_FOUND Event was not found

GET /products/{uid}

Retreive product status.

Request attributes

Attribute Type Required Description
uid string Yes Product UID

Example response

{
    "uid": "beZFLF3NZ66Q2277",
    "description": "My example product",
    "service": 0.1,
    "available": 3,
    "min": 10,
    "max": 12.5,
    "prices": [10, 11.75, 12.5],
    "event": {
        "uid": "znc6QfUsgQEHhY3G",
        "description": "My example event",
        "fee": 8
    }
}

Response attributes

Attribute Type Description
uid string Product UID
description string Description of the product
service float Service fee
available int Number of available products of this type
min float Lowest price for product, null if none available
max float Highest price for product, null if none available
prices array<float> List of available prices, low to high
event.uid string Event UID
event.description string Event UID
event.fee float Buyer's fee percentage

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match product
500 PRODUCT_NOT_FOUND Product was not found

POST /products/{uid}/enter

Enter a product for swap.

Request attributes

Attribute Type Required Description
uid string Yes Product UID
code string Yes Product ticket barcode number
price float Yes Offer price, excluding service fee

Example response

{
    "uid": "P2qcL2oIT2Mq3Gch",
    "price": 10
}

Response attributes

Attribute Type Description
uid string Ticket UID
price float Offer price, excluding service fee

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match product
500 PRODUCT_NOT_FOUND Product was not found
500 INPUT_VALIDATION_ERROR Specified input attributes incorrect
500 TICKET_EXISTS Ticket already on offer or sold
500 WRONG_PRODUCT Product type incorrect
500 THIRD_PARTY_API_ERROR API provider API error

POST /products/{uid}/withdraw

Withdraw a product from swap.

Request attributes

Attribute Type Required Description
uid string Yes Product UID
code string Yes Product ticket barcode number

Example response

{
    "uid": "P2qcL2oIT2Mq3Gch",
    "price": 10
}

Response attributes

Attribute Type Description
uid string Ticket UID
price float Offer price, excluding service fee

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match product
500 PRODUCT_NOT_FOUND Product was not found
500 INPUT_VALIDATION_ERROR Specified input attributes incorrect
500 TICKET_DOESNT_EXISTS Ticket not on offer
500 TICKET_IS_RESERVED Ticket is reserved for sale
500 TICKET_IS_PENDING Ticket order is pending
500 TICKET_IS_SOLD Ticket is sold

POST /products/{uid}/reserve

Reserve a product for a specific price, creates an order.

Request attributes

Attribute Type Required Description
uid string Yes Product UID
price float Yes Ticket price, excluding service fee

Example response

{
    "uid": "7LXW8t78NmoMmblo",
    "status": "completed",
    "reference": null,
    "download": null
}

Response attributes

Attribute Type Description
uid string Order UID
status string Order status
reference string Provider reference, null when status not completed
download string Download URL, null when status not completed

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match product
500 PRODUCT_NOT_FOUND Product was not found
500 INPUT_VALIDATION_ERROR Specified input attributes incorrect
500 PRODUCT_SOLD_OUT Product sold out for specified price

GET /products/{uid}/{code}

Look up product with order price.

Attribute Type Required Description
uid string Yes Product UID
code string Yes Ticket barcode number

Example response

{
    "product": {
        "uid": "beZFLF3NZ66Q2277",
        "description": "My example product",
        "service": 0.1
    },
    "price": 10
}

Response attributes

Attribute Type Description
product.uid string Product UID
product.description string Description of the product
product.service float Service fee
price float Price paid for product, excluding service fee

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match product
500 PRODUCT_NOT_FOUND Product was not found
500 THIRD_PARTY_API_ERROR API provider API error

GET /orders/{uid}

Retreive order status.

Attribute Type Required Description
uid string Yes Order UID

Example response

{
    "uid": "7LXW8t78NmoMmblo",
    "status": "completed",
    "reference": null,
    "download": null
}

Response attributes

Attribute Type Description
uid string Order UID
status string Order status
reference string Provider reference, null when status not completed
download string Download URL, null when status not completed

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match order
500 ORDER_NOT_FOUND Order was not found

POST /orders/{uid}/bill

Create bill for order.

Attribute Type Required Description
uid string Yes Order UID
country string Yes Customer ISO 3166-1 alpha-2 country code
payment string No Provider payment ID
shipping string No Provider shipping ID

Example response

{
    "ticket": {
        "uid": "P2qcL2oIT2Mq3Gch",
        "price": 10
    },
    "provider": "paylogic",
    "country": "NL",
    "price": {
        "subtotal": 10,
        "service": 0.1,
        "order": 0.1,
        "fee": 0.2,
        "payment": 0,
        "shipping": 0,
        "total": 10.4
    },
    "payment": [
        {
            "uid": "55bb6f5bc4924ba18f2f7e9f38b280ee",
            "description": "iDEAL",
            "image": "https://cdn.ideal.nl/logo.jpg"
        },
        ...
    ],
    "shipping": [
        {
            "uid": "bbc1d3a23a4a431885951a5a22cfc190",
            "description": "E-ticket"
        },
        ...
    ],
    "payment_method": "iDEAL",
    "shipping_method": "E-ticket"
}

Response attributes

Attribute Type Description
ticket.uid string Ticket UID
ticket.description string Description of the ticket
provider string Ticket provider
country string Customer ISO 3166-1 alpha-2 country code
price.subtotal float Product price, excluding service fee
price.service float Service fee
price.order float Order fee
price.fee float Buyer's fee
price.payment float Payment fee, only returned if payment request attribute is given
price.shipping float Shipping fee, only returned if shipping request attribute is given
price.total float Total price for order
payment.uid string Payment option ID
payment.description string Payment option description
payment.image string Payment option logo URL
shipping.uid string Shipping option ID
shipping.description string Shipping option description
payment_method string Selected payment option description, only returned if payment request attribute is given
shipping_method string Selected shipping option description, only returned if shipping request attribute is given

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match order
500 ORDER_NOT_FOUND Order was not found
500 INPUT_VALIDATION_ERROR Specified input attributes incorrect
500 THIRD_PARTY_API_ERROR API provider API error

POST /orders/{uid}/pay

Create bill for order.

Attribute Type Required Description
uid string Yes Order UID
first_name string Yes Customer first name
last_name string Yes Customer last name
date_of_birth string Yes Customer date of birth (YYYY-MM-DD)
email string Yes Customer email address
gender string Yes Customer gender (m for male, f for female, o for other
address string Yes Customer address
postal_code string Yes Customer postal code
city string Yes Customer city
country string Yes Customer ISO 3166-1 alpha-2 country code
phone_number string Yes Customer phone number
payment string Yes Provider payment ID
shipping string Yes Provider shipping ID
redirect string No Redirect URL

Example response

{
    "uid": "7LXW8t78NmoMmblo",
    "status": "pending",
    "redirect": "https://website.com",
    "ticket": {
        "uid": "P2qcL2oIT2Mq3Gch",
        "price": 10
    },
    "consumer": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1986-01-03",
        "email": "john.doe@gmail.com",
        "gender": "m",
        "address": "Street 1",
        "postal_code": "1234 AB",
        "city": "Amersfoort",
        "country": "NL",
        "phone_number": "0612345678"
    },
    "provider": "paylogic",
    "payment": [
        "uid": "55bb6f5bc4924ba18f2f7e9f38b280ee",
        "description": "iDEAL"
    ],
    "shipping": [
        "uid": "bbc1d3a23a4a431885951a5a22cfc190",
        "description": "E-ticket"
    ],
    "url": "https://payment.provider.com"
}

Response attributes

Attribute Type Description
uid string Order UID
status string Order status
redirect string Redirect URL, only returned if redirect request attribute is given
ticket.uid string Ticket UID
ticket.description string Description of the ticket
consumer.first_name string Customer first name
consumer.last_name string Customer last name
consumer.date_of_birth string Customer date of birth (YYYY-MM-DD)
consumer.email string Customer email address
consumer.gender string Customer gender (m for male, f for female, o for other
consumer.address string Customer address
consumer.postal_code string Customer postal code
consumer.city string Customer city
consumer.country string Customer ISO 3166-1 alpha-2 country code
consumer.phone_number string Customer phone number
provider string Ticket provider
payment.uid string Selected payment option ID
payment.description string Selected payment option description
shipping.uid string Selected shipping option ID
shipping.description string Selected shipping option description
url string Payment URL

Possible errors

Status code Error code Description
401 AUTHENTICATION_FAILED Provided authentication headers incorrect
500 AUTHENTICATION_FAILED Provided authentication does not match order
500 ORDER_NOT_FOUND Order was not found
500 INPUT_VALIDATION_ERROR Specified input attributes incorrect
500 THIRD_PARTY_API_ERROR API provider API error