API Overview

This section details the D1 Transit APIs, the Transit Issuer needs to implement and the different sections for backend to backend integration.

API Design

Data format

Data exchanged between D1 Transit and Transit Issuer servers will be formatted as a JSON data structure.

String encoding is UTF-8 unless specified otherwise.

Transport Protocol

The communication protocol used for all interfaces shall be HTTPS.

Error Management

All APIs responses should be returned with HTTP 200 status code and an applicative status code (see list below).

In case of unexpected server error (e.g. uncaught exception), HTTP 500 status code should be returned. In this case, the error is considered as non-retryable.

In case of server unavailability, HTTP 503 status code should be returned. In this case, the error is considered as retryable.

The table below lists all the status codes that can be used.

Status Code	Description	Applicable API
0	OK	All
111	Missing mandatory parameter	All
112	Bad parameter format	All
113	Unknown issuer	All
116	Unknown card account	cancelCardAccount manageDigitalCard getCardAccountInfo
117	Unknown device
118	Unknown session
119	Unknown digital card	manageDigitalCard getDigitalCardBundleData
120	Unknown purchase
158	Card expired	purchaseProducts getDigitalCardBundleCommands
159	Card suspended/inactive/blacklisted	purchaseProducts getDigitalCardBundleCommands
160	Card is deleted
162	Card has unsufficient balance	purchaseProducts getDigitalCardBundleCommands
163	Card account not eligible	getDigitalCardBundleData getDigitalCardBundleCommands
164	Provisioning count exceeded	getDigitalCardBundleData
166	Invalid card information
167	Card is already provisioned	getDigitalCardBundleCommands
169	Purchase order declined	purchaseProducts
170	Provisioning request rejected	getDigitalCardBundleData
171	Wallet account mismatch. The wallet account is already associated with a card under different customer name	getDigitalCardBundleData
172	unsupported system code	getDigitalCardBundleCommands
173	unsupported service	getDigitalCardBundleCommands
177	invalid area data	getDigitalCardBundleCommands
178	card status is in-station	getDigitalCardBundleCommands
192	Reader mode attempt exceeded allowed threshold	getDigitalCardBundleCommands
221	Device or wallet server not accessible
231	Device unexpected error
232	Device out of memory error
321	Operation already on-going for this device	manageDigitalCard
322	Time to live of the operation expired
419	PIN required	purchaseProducts
420	PIN incorrect	purchaseProducts
421	PIN locked	purchaseProducts
431	Invalid perso data
432	Operation is not allowed with current card state	manageDigitalCard
911	Operation failed	All
921	Unexpected server error	All

The applicable status codes are described on each API method with best effort.

Backward Compatibility Rules

This section defines backward-compatibility rules applied by Thales to ensure compatibility with API evolution.

• Thales may add optional parameters (in HTTP header, URL and body) in API requests and/or responses. Transit Issuer must not perform strict validation.

'Strict Validation' is a configuration which restricts or limits API calls with unwanted parameters which are not defined in the API Specification at a point of time.

• API error message strings can evolve with new releases without any impact. These error messages are for troubleshooting purposes and issuer must not expect pre-defined and fixed format.
• HTTP request or response parameters sent by D1 Transit solution to Transit Issuer system could change from optional to mandatory.
• HTTP request or response parameters sent by Transit Issuer system to D1 Transit Solution could change from mandatory to optional.
• Order of API parameters is not fixed.
• Thales may add new values in existing enumeration parameters.
• Thales may extend the API by adding new operations (HTTP methods, URL, resources).
• Thales may extend the responses by adding new HTTP status response code.

API Parameter/Operation End of Life

Thales will inform the Transit Issuer no later than nine (9) months before the end of life, the deprecation period, of any API parameter or API operation (HTTP methods, URL, resources).

For sake of clarity, after deprecation period, deprecated API parameter(s) and API operation(s) must be no more used anymore by any Transit Issuer system in Production and non Production.

Thales may shorten the deprecation period, without limitation to the following conditions: (i) a significant security risk; (ii) a substantial economic or material technical impact; (iii) as may be required by Applicable Law or Digital wallets.

Backend Integration

To call the D1 Transit APIs, the following setup is required:

1. Connectivity
2. Data encryption

Transit APIs

Please find below the list of available APIs

• Inbound API
• Notification Inbound API
• Outbound API

All the updates and evolutions made on the transit APIs will be reflected in the Release Notes

Data Preparation

The Data preparation section below provides information about the required data to be provided by Transit Issuer to D1 Transit in order to prepare the digital card bundles.