railcards-eapi

Page Content

• Terminology
• Validate a Railcard
• Validity Changes
• Valid Railcard Types

Terminology

The following are key terms used throughout this documentation:

Validate a Railcard

Resource: /railcards/{railcardNumber}/expiry

This resource will allow the consumers to check whether the Railcard is stored within the Railcard system by matching the requested details and checking the Railcard status. If the Railcard search conditions are met, the system will return the confirmed expiry date of the Railcard. It is the responsibility of the consumers to check whether that Railcard can be used for the selected journey based on relevant business rules.

Both Station Issued and Retailer Issued Railcards can be validated.

In order to check a Railcards validity the system will check:

• Railcard Type is supported
• Railcard details match those stored
• Status of the stored Railcard is classed as "valid"

If the received Railcards details meet the above criteria the system will return the Railcard expiry date, otherwise a "not found" error will be returned.

Railcard Type

Not all Railcards can be validated by the system, for example, Regional Railcards are not stored within the system and therefore can’t be validated. The system will check whether the Railcard Type can be processed and return an error if the Railcard is not supported.

For a list of valid Railcard Type see section "Reference Data" below

Railcard Details

Railcard holders last name must be present in the request.

If the Railcard details do not meet the required criteria the system will return a "not found" response.

Railcard Status

The system will check the status to ensure this is valid. If the status is invalid a "not found" response will be returned.

Validity Changes

Resource: /railcards/validityChanges

This resource allows consumers to check whether railcards have changed their validity status. Under normal circumstances a railcard will be valid from its time of issue until it expires. However, there are times when a railcard may become invalid for other reasons, such as it being hotlisted. For those consumers who provide account based services, where they may use RVS to validate a railcard and then store that railcard against the user's account, this endpoint allows them to check whether any previously validated railcards have subsequently become invalid, and if so to remove or disable them from the account.

This endpoint works by allowing the users to specify a time window, for example the past 24 hours, and it will return any cards whose validity have changed within that time window. A typical use case would be executing this query once per day for the previous 24 hours, and updating customer account records to reflect any railcards which have become invalid within the last day.

Optional filters can be specified in the request to limit the response by railcard types (see below) or by validity transistions (valid to invalid, invalid to valid)

Note: Whilst the API also has an includeExpired option this capability is not currently enabled in the back office and will have no effect on the results. Consumers are expected to store the expiry date of railcards and automatically remove/disable them once they have expired without needing to request that information from RDG. If, in the future, there is a reason to include expired cards within scope then this will be switched on in the background and these pages updated.

All railcard types are in scope of the Validity Change endpoint, However, initially station sold railcards will not show any validity changes as this data isn't currently captured. When this data does start to be captured it will be added to the validity change endpoint results with no changes needed to the API.

Reference Data

Valid Railcard Types

The following table contains the valid Railcard Types accepted by the service:

Last update: 23-Jul-2025 14.28: ASSIST API Documentation Maintenance: railcards-eapi | Version: v2 | Page: Home | Revision: A.

To request updates to this text please contact Neil Barkham.