> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/transit-digitization/integrate-d1-transit-api/api-overview.md).
# 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.
{% hint style="info" %}
'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.
{% endhint %}
* 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.payments.thalescloud.io/transit-digitization/integrate-d1-transit-api/api-overview.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.