Documentation

Using the TapConnect TOMP API →

# Issuing Tickets

After defining a product it is time to sell it. Please check that the sales catalog is live for the sales channel and date you want to sell tickets.

# Showing the available products

To list the products that are available to a sales channel, the sales channel can use its API key to access the product endpoints.

# Creating/Issuing a ticket

A ticket is the combination of a product definition with the selected options and information of the traveler. When issuing a ticket, TapConnect responds with the unique ticket id, and something to present to the user that can be used to link to the ticket. This is usually a barcode and/or a service id. Please find these fields in the create ticket endpoint description of the API.

Please note that for most if not all operators, a ticket represents a travel right, and therefore monetary value. It is important to protect your API key and make sure that created tickets can be linked to a (financial) transaction.

To create a ticket, call the /v6/tickets/create endpoint with a payload which matches the product and travel rights you want to produce a ticket for. For regular UIC tickets, a typical json payload could look like this:

{
  "salesChannelId": "197492442",
  "ticketLanguage": "NL",
  "productCode": "A2B4",
  "barcodeType": "uic",
  "withBarcode": "image/png",
  "validityStart": "2020-03-03",
  "validityStartTime": "10:30",
  "startStation": "amsterdam-cs",
  "endStation": "amsterdam/metrostation-zuid",
  "numberOfChildren": 0,
  "numberOfAdults": 1,
  "withActivation": true,
  "reference": "REF1234"
}

Note that in this example, the vdvFields, cargoType and maasTravelerId and sceId elements are left out because they either have sensible defaults or are specific to VDV barcodes which are mainly used in Germany. Please refer to the CreateTicketRequest schema in the API documentation for more specific information about these fields.

In the example above, the withBarcode is set to image/png. This means that if the product is a fixed validity product for which the ticket can be immediately activated, the system will activate the ticket and return a PNG image containing a 2D Aztec barcode containing the ticket. For raw/binary ticket data application/octet-stream can be used.

# Activating a ticket and getting a barcode

After a ticket is issued by TapConnect and depending on the product definition, it may need to be activated before a barcode can be created for it. The response to the create ticket API call will contain information on whether the ticket is activated or not. If the ticket is not activated, please use the activate endpoint to activate the ticket.

To fetch a UIC918-3 compliant aztec barcode or mobileplus token for the ticket, the barcode endpoint can be used.

Please note that for some products the barcodes expire and need to be regularly refreshed. This is a fraud protection mechanism to prevent people from traveling with copies of barcodes. To the client or webshop this process is almost transparent, as long as REST response cache headers (opens new window) are properly respected.

# Binding your own barcode to a ticket

When you have a barcode which is generated by another system (a ferry service, or a museum ticket), it is possible to bind that barcode to a TapConnect barcode. If the validators of the Transport Operator are able to send the external barcode to TapConnect as-is, TapConnect will find the Ticket that was bound to that barcode and will treat it as if the original TapConnect barcode was tapped. To do this:

  • Create a Ticket with the v6/tickets/create endpoint.
  • Bind your own barcode to the ticketId with the /v6/tickets/{ticketId}/bind endpoint.

From that moment on, if the barcode is sent to the validation API through the v1/tap endpoint, TapConnect will be able to find the attached ticket and use that information to validate it.

IMPORTANT: Barcodes which are bound to a Ticket in TapConnect must be unique. A barcode cannot be bound to a second ticket, even if the first ticket was blocked.

# Finding out if a Ticket has been used to travel with

In some cases it is required to know if a ticket was used to travel with. For instance, if a refund is requested and the traveler claims the ticket has not been used, it might be good to check this. To know what has happened to a ticket, the system provides a /v6/tickets/{ticketId}/info endpoint which gives the caller information about the ticket and its usage. The response looks somewhat like this:

{
  "ticket": {
    "serviceId": "ABC-1234-7654-8945",
    "ticketId": "KJj43nejhbTxhr897287",
    "productName": "24 uurs dagkaart",
    "modalities": [      "BUS"    ],
    "priceInCents": 750,
    "issuedAt": "2020-03-21T13:41:12",
    "language": "NL",
    "salesChannelId": "197492442",
    "salesChannelName": "Coffee & Tickets to go.",
    "barcodeType": "uic",
    "validityStart": "2020-03-03T00:00:00",
    "validityEnd": "2020-03-04T23:59:59",
    "activatedAt": "2020-03-03T00:00:00",
    "blocked": false,
    "startStation": "1336",
    "endStation": "1336",
    "numberOfChildren": 0,
    "numberOfAdults": 2,
    "operators": [
      {
        "id": "PTOID",
        "name": "Bus Company"
      }
    ],
    "travelRights": [
      {
        "order": 1,
        "operator": "GVB",
        "from": "1336",
        "to": "1336",
        "validFrom": "2022-12-27T16:02:05+07:00",
        "validTo": "2022-12-27T16:02:05+07:00",
        "active": true
      }
    ],
    "validInConcessionId": "AB123",
    "validOnLineIds": [
      "16A"
    ],
    "reference": "TEST 123",
    "validityScheduleName": "weekend ticket"
  },
  "events": [
    {
      "occurredAt": "2020-03-03T00:00:00",
      "operatorId": "OPTID",
      "location": "string",
      "action": "CREATE_TICKET",
      "result": "VALIDITY_STARTED"
    }
  ]
}

In this response, there are 3 main sections:

  • The information about the ticket itself: service id, product id, product name, modalities etc.
  • Information about travel rights: A ticket can have multiple travel rights, for instance when a ticket is an interoperable ticket to enable the traveler to travel by train and bus between two operators.
  • Events: Every action on a ticket is registered as an event. Binding a barcode to a ticket is an event, but also tapping the ticket in a bus is an event. When a traveler has traveled with a ticket, the info will contain NOTIFY events. For a list of all event types, please see the schema information of the v6/tickets/{ticketId}/info endpoint.

IMPORTANT: Please note that your API key can have different roles. The SALES role enables you to call the v6/tickets/{ticketId}/info endpoint. However, if you would like to call the v6/tickets/{ticketId}/full-info, your API key needs to have the INSPECT role. For sending TAP events, you need an API key with the VALIDATION role, or enroll your validator as a Websocket device with your operator.

Using the TapConnect TOMP API →