TapCheck Issuing API (1.0.4)

Download OpenAPI specification:Download

Introduction

Welcome to the TapCheck Issuing API documentation. These pages describe the endpoints available within TapCheck.

Product related endpoints return information about products that are available to you as a sales partner and the details of each of these products.

Ticket related endpoints allow you to manage tickets throughout their lifecycle. Such as creation, retrieveing ticket information, or retrieving the barcode for a ticket.

An api key is required to access this api. Please contact tapcheck@ximedes.com or your Public Transport Operator to get yours!

TapCheck Validation API

If you are looking for the TapCheck Validation API description please visit: https://tapcheck.io/developers-validation.html

Authentication

Bearer Auth

Authentication and authorization is based on a pre-shared API key. The API key is to be included in every API call in the Authorization header using the Bearer method.

Example:

curl --location --request POST 'https://issuing.tapcheck.io/v1/tickets/create' --header 'Authorization: Bearer z6QkOERZsWbQC4QcwIdexgEWZHJP4VNF8CfQogaZmXV=' --header 'Content-Type: application/json' --data-raw '{ "salesChannelId": "1", "ticketLanguage": "NL", "productCode": "0001", "validityStart":"2020-12-03" }'

Note: z6QkOERZsWbQC4QcwIdexgEWZHJP4VNF8CfQogaZmXV= is not a real API key, just shown for illustration purposes.

Access to specific endpoints is dependent on the agreements made with public transport operator you are connecting to. So not every endpoint might be available to you even though the endpoint is described in this documentation.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Product endpoints

Product related endpoints can be used to retrieve information about the products that are currently available for purchase.

List Products

Returns a list of products for the given salesChannelId.

Authorizations:
path Parameters
salesChannelId
string (SalesChannelId) ^[1-9][0-9]{0,9}$
Example: 197492442

A unique identifier for this Sales Channel (also known as sales partner).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Product Details

Returns the details of the selected product.

Authorizations:
path Parameters
salesChannelId
string (SalesChannelId) ^[1-9][0-9]{0,9}$
Example: 197492442

A unique identifier for this Sales Channel (also known as sales partner).

productCode
string (ProductCode) ^[A-Za-z0-9]{1,4}$
Example: A2B4

A unique identifier for this product type.

Responses

Response samples

Content type
application/json
{
  • "salesChannelId": 197492442,
  • "productNameNL": "24 uurs dagkaart",
  • "productNameEN": "24 hour dayticket",
  • "productDescriptionNL": "Een kaart om 24 uur in Amsterdam mee te reizen",
  • "productDescriptionEN": "A ticket for traveling in Amsterdam for 24 hours",
  • "productCode": "A2B4",
  • "selectableUsageRangeStart": "2020-03-01",
  • "selectableUsageRangeEnd": "2020-03-28",
  • "usableAfter": "2020-03-02",
  • "usableBefore": "2020-03-20",
  • "validityDuration": 1440,
  • "validityUnit": "minutes",
  • "priceInCents": 750,
  • "modalities": "BUS",
  • "termsAndConditionsNL": "http://tapcheck.io/nl/",
  • "termsAndConditionsEN": "http://tapcheck.io/en/",
  • "productType": "TIME_BASED"
}

Ticket endpoints

Ticket related endpoints are used to handle ticket related actions. Tickets can be bought, activated, information can be retrieved about sold tickets, barcodes can be requested for a sold ticket, and a ticket can be blocked or cancelled. Based on your authorization level you have access to some (or all) of these endpoints.

Create ticket

Creates a ticket for traveling, based on the selected product.

Authorizations:
Request Body schema: application/json
salesChannelId
required
string (SalesChannelId) ^[1-9][0-9]{0,9}$

A unique identifier for this Sales Channel (also known as sales partner).

ticketLanguage
required
string (Language)
Enum: "NL" "EN"

Language, default language is EN unless NL is specified.

productCode
required
string (ProductCode) ^[A-Za-z0-9]{1,4}$

A unique identifier for this product type.

validityStart
string <date>

Required for products that require the customer to pick a starting date for their ticket. It is the date on which the validity of that ticket will start, as chosen by the customer. For products that are activated on first use, this field can be omitted. Mandatory for tickets with Stop to Stop products

startStation
string

In case of a stop-to-stop product, this field contains the identifier of the first station in the trip where the ticket should be used.

endStation
string

In case of a stop-to-stop product, this field contains the identifier of the last station in the trip where the ticket should be used.

childTicket
boolean

Indication when the issued ticket is a child ticket

Responses

Request samples

Content type
application/json
{
  • "salesChannelId": 197492442,
  • "ticketLanguage": "NL",
  • "productCode": "A2B4",
  • "validityStart": "2020-03-03",
  • "startStation": "amsterdam-cs",
  • "endStation": "amsterdam/metrostation-zuid",
  • "childTicket": true
}

Response samples

Content type
application/json
{
  • "serviceId": "ABC-1234-7654-8945",
  • "ticketId": "KJj43nejhbTxhr897287",
  • "productName": "24 uurs dagkaart",
  • "issuedAt": "2020-03-01T00:00:00",
  • "lifespanStart": "2020-03-01",
  • "lifespanEnd": "2020-03-28",
  • "validityStart": "2020-03-03T00:00:00",
  • "validityEnd": "2020-03-04T23:59:59",
  • "active": true,
  • "startStation": "1336",
  • "endStation": "1336",
  • "childTicket": true
}

Get ticket info

Provides information and events related to a ticket. This endpoint is aimed towards Sales Channel customer support or information shown to a traveller.

Authorizations:
path Parameters
ticketId
string (TicketId) ^[A-Za-z0-9]{20}$
Example: KJj43nejhbTxhr897287

A unique 20-character alphanumeric id for a ticket.

Responses

Response samples

Content type
application/json
{
  • "ticket": {
    },
  • "events": [
    ]
}

Get full ticket info

Provides the full information and events related to a ticket. This endpoint is dedicated for PTO customer service channels to provide all available information.

Authorizations:
path Parameters
ticketId
string (TicketId) ^[A-Za-z0-9]{20}$
Example: KJj43nejhbTxhr897287

A unique 20-character alphanumeric id for a ticket.

Responses

Response samples

Content type
application/json
{
  • "ticket": {
    },
  • "events": [
    ]
}

Activate ticket

For tickets with a sliding validity, this endpoint can be used to indicate the activation (first use) of the ticket.

Authorizations:
path Parameters
ticketId
string (TicketId) ^[A-Za-z0-9]{20}$
Example: KJj43nejhbTxhr897287

A unique 20-character alphanumeric id for a ticket.

Responses

Response samples

Content type
application/json
{