logo
Documentation Powered by ReDoc

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:
Bearer Auth
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:
Bearer Auth
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:
Bearer Auth
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:
Bearer Auth
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:
Bearer Auth
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:
Bearer Auth
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
{
  • "serviceId": "ABC-1234-7654-8945",
  • "ticketId": "KJj43nejhbTxhr897287",
  • "validityStart": "2020-03-03T00:00:00",
  • "validityEnd": "2020-03-04T23:59:59",
  • "active": true
}

Get barcode

After a ticket has been created and (if required) activated a UIC918-3 compliant aztec barcode can be retrieved using this endpoint.

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

A unique 20-character alphanumeric id for a ticket.

header Parameters
accept
string
Enum: "application/octet-stream" "image/png"

Request the response as raw bytes or as a png image.

Responses

Cancel ticket

Cancels the ticket with the given id, with the given cancellation reason.

Authorizations:
Bearer Auth
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
{
  • "serviceId": "ABC-1234-7654-8945",
  • "ticketId": "KJj43nejhbTxhr897287",
  • "blocked": true,
  • "cancelledAt": "2020-03-03T13:43:12"
}

Fraud detected

Marks a ticket as fraudulent. If a ticket is marked as fraud it is added to the deny list until the ticket has expired, the ticket cannot be used for travelling at this point. It is also included in fraud related reporting.

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

A unique 20-character alphanumeric id for a ticket.

Request Body schema: application/json
automatic
required
boolean
Default: false

Whether the ticket is marked as fraudulent manually (e.g. by customer service using the UI) or automatically (e.g. by the fraud detection system). Please only use false unless you are an automatic fraud detection system.

Responses

Request samples

Content type
application/json
{
  • "automatic": false
}

Response samples

Content type
application/json
{
  • "serviceId": "ABC-1234-7654-8945",
  • "ticketId": "KJj43nejhbTxhr897287",
  • "blocked": true,
  • "fraudDetected": true
}

Bind barcode

Binds an external barcode to a ticket in order to be able to travel with it instead of a barcode generated by Tapcheck

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

A unique 20-character alphanumeric id for a ticket.

Request Body schema: application/json
barcodeToBind
required
Encoded base 64 bytes of barcode

Encoded Base 64 (RFC4648) string of the bytes representing a barcode to be bound to a ticket with a max size of 2KB

Responses

Request samples

Content type
application/json
{
  • "barcodeToBind": "RW5jb2RlZCBNZXNzYWdl"
}

Export data

Export data that can be used to generate reports about issued tickets and related information

Get issuing report data

Provides a list of issued tickets data from a specific day that can be used to build ticket related reports

Authorizations:
Bearer Auth
path Parameters
day
required
date
Example: 2020-03-23

A date formatted string that indicates the day of which ticket data is being requested

Responses

Response samples

Content type
application/json
[
  • {
    }
]