Page Content

• Terminology
• Railcard Validation
• Simplified Railcard Validation
• Validity Changes
• Valid Railcard Types

---

Terminology

The following are key terms used throughout this documentation:

Term	Description
Station Issued Railcards	These Railcards have been issued at a Station these have a short character Railcard Number (~5 characters)
Retailer Issued Railcards	These Railcards have been issued via a Retailer and have a longer Railcard Number (~15-16 characters)

---

Railcard Validation

Resource: /railcards/{railcardNumber}/expiry

This resource will allow the consumers to check whether the Railcard is known to the Railcard Validation Service by matching the requested details. 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 an error will be returned.

Notes

• 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 Types see "Reference Data" below
• Railcard holders last name must be present in the request. this is to help identify station sold railcards which do not have unique railcard numbers

---

Simplified Railcard validation

Resource: /railcards/tbc

This resource is a simplified version of the above endpoint, allowing consumers to check for the existence and validity of a railcard by matching on just the railcard number and type. If a matching railcard is found the expiry date of the card will be returned. If a matching railcard isn't found an appropriate error will be returned.

Because station sold railcards can not be uniquely identified by just railcard number and type, using this endpoint may result in 'duplicate railcard' errors, which the consumer may then need to check using the above endpoint, with more details to find a unique match, or implement another strategy to validate the railcard (e.g. ask the customer to use an attended TIS to purchase their ticket where their railcard can be visually checked by staff)

---

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)

All supported 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.

---

Valid Railcard Types

Resource: /railcards/tbc

This resource allows consumers to obtain a list of railcard types in scope of RVS, and can be used to determine whether to make an RVS check or not based on the railcard type.

As reference data which changes very infrequently this should only need to be accessed once every 24 hours and cached locally.

Reference Data

Valid Railcard Types

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

Railcard Type	Description	LTOT (Capri) codes
2TR	Two Together Railcard	ZMO, ZMT
DIS/DIC	Disabled Persons Railcard	ZMM, ZNH, ZNU, ZNJ, ZNV
FAM	Family & Friends Railcard	ZCS, ZNS, ZMK, ZCB
NEW	Network Railcard	ZMU, ZCD
SRN	Senior Railcard	ZCC, ZNR, ZCR, ZME
TST	26-30 Railcard	ZZB, ZZC
TSU	16-17 Saver	ZAG, ZAH
VET	Veterans Railcard	ZAT, ZAU, ZAV, ZAW
YNG	16-25 Railcard	ZCA, ZCT, ZNT, ZMA

---

Whilst every effort will be made to capture all errors which may be returned for these API resources on this page, if you are returned an error not recorded here, please provide details to RDG, including the request which generated the error and the error message itself, and we will investigate and add to this page.

---

Platform Error Format

The Developer Portal will return an error if submitted requests do not comply with one or more of an API's policies. A common example of this is the security policy, which requires a valid JWT in every request. If the request doesn't include a valid JWT then the Portal will reject the request immediately and make no attempt to process it. Rejected requests of this nature will result in a platform error, which has the following simple format (See Platform Error Object data type):

{
    "error" : "error message"
}

RDG Error format

If a request passes the policy checks it will be submitted to the relevant RDG API which may then result in an RDG specific error as opposed to a generic platform error. APIs on the RDG Developer Portal use the following common error format to contain and return these errors to consumers (See RDG Error Object data type):

{
    "errors": [
        {
            "code": "error_code",
            "message": "error message",
            "timestamp": "YYYY-MM-DDTHH:MM:SS",
            "context":
            {
                "{key}": "value"
            }
        }
    ]
}

The context object is an unspecified list of key value pairs, allowing new context information to be provided without requiring a schema change. There are currently no context fields added to Railcard Errors.

Known Error Cases

General

Code	Message	Comment
GBR-AUTH-2000	Security Error	When RDG fails to process request due to client side or server side security failure
GBR-AUTH-2001	Unauthorised User	When user’s token is invalid
GBR-AUTH-2002	Security validation: precondition failed	-
GBR-AUTH-2003	Security validation: Bad request	When request payload has failed to process
GBR_EXCEPTION_0000	Unknown Error	Catch all for any unknown errors
GBR_EXCEPTION_0001	Undefined error by 3rd party system	Unknown error from 3rd party APIs
GBR_EXCEPTION_3000	Invalid schema/ Invalid payload	Bad request due to payload not conforming to the json/xml schema definition
GBR_EXCEPTION_3001	Internal Error	Unable to complete operation
GBR_EXCEPTION_3006	Resource not found	When API resource request is not found or not defined in the specification
GBR_EXCEPTION_3007	Method not allowed	When API resource request doesn’t conform to the API specfication e.g. method GET is expected for a resource but POST or PUT call is made
GBR_EXCEPTION_3009	Unsupported media type	When API resource request media type (e.g. application/json) doesn’t conform to the expected media type
GBR_EXCEPTION_3010	HTTP too many requests	Rate-limit exceeded
GBR_EXCEPTION_3011	AWS S3 bad request error	When AWS S3 throws error due to processing error of the request
GBR_EXCEPTION_3012	Invalid schema/ Invalid payload	Bad request due to payload not conforming to the json/xml schema definition
GBR_EXCEPTION_3013	Invalid schema/ Invalid payload	Bad request due to payload not conforming to the json/xml schema definition
GBR_EXCEPTION_3014	Forbidden Error	When source system doesn’t allow access to a particular resource for a specfic client
GBR_EXCEPTION_3015	Validation Error [Email is valid]	The structural conformation of email is checked and throws error if doesn’t match the built in REGEX pattern
GBR_EXCEPTION_3063	Expression error	When any form of REGEX failed to excute due to incorrect inputs
GBR_EXCEPTION_3065	Retry exhausted, Redelivery Exhausted	Retry component reaches the threshold number with respect to HTTP requests made
GBR_EXCEPTION_3066	Connectivity issue or service is not available	When cannot reach the resource URL or underneath service doesn’t respond
GBR_EXCEPTION_3067	HTTP time out	When the HTTP request gets timed out

Railcards

Code	Message	Comment
GBR_RAILCARDS_6100	Requested Railcard type is not supported	The requested Railcard Type is not stored within the system and cannot be validated
GBR_RAILCARDS_6101	Requested Railcard details not valid	The necessary validation criteria has not been met
GBR_RAILCARDS_6102	Internal error occurred - unable to validate railcard	Whilst validating a Railcard there has been an internal error which means the Railcard could not be validated, the Railcard may be valid

To request access to this API, please log a ticket with the Railcard ServiceDesk via portal or email

• Web Portal: https://serviceportal.nationalrail.co.uk/rdg
• Email: service.desk@nationalrail.co.uk

Providing details of your organisation, the API you are requesting access to and the reason for your requested access.

Your request will then be assessed to ensure you have sufficient justification and need to access and use this API.