Transit API

TES-IN-v1-transit.yaml

Request to send personalization data to a digital card

post

This method is used by TES to submit the perso data used for personalizing a digital card. This request is sent after TES approves a previous provisionCard call and after finishing to prepare the required data.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · min: 1 · max: 48Required

The Card Identifier. Unique for each card.

Responses

200

submitCardPersoData response payload

application/json

500

Internal Server Error

post

/submitCardPersoData

HTTPcURLJavaScriptPython

POST /tsh/transitapi/1/0/submitCardPersoData HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 206

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "cardPersoData": [
    {
      "name": "text",
      "value": "text",
      "keyIndex": "text"
    }
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Request to update the state of a digital card

post

This method is used by TES to request to update the state of a digital card.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · min: 1 · max: 48Required

The Card Identifier. Unique for each card.

actionstring · enumRequired

The LCM action to apply on the card.Possible values are:

• DELETE
• SUSPEND
• RESUME
• ERASE (used in the Rights of Individuals context) All personal data are physically removed from TSH server

Possible values:

Responses

200

updateCardState response payload

application/json

500

Internal Server Error

post

/updateCardState

HTTPcURLJavaScriptPython

POST /tsh/transitapi/1/0/updateCardState HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 157

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "action": "DELETE"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Request to update the metadata of a card

post

This method is used by TES to request to update the metadata of a digital card:

• either commute plans metadata

• or card arts

It's not possible to update them both in a single request.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · min: 1 · max: 48Required

The Card Identifier. Unique for each card.

cardArtManifeststring[]Optional

Array of asset identifiers required to build card arts. Both cardBackground and icon asset identifiers shall be provided.

Asset identifier can be up to 64 characters.

When this parameter is provided, a request will be sent to wallet provider for updating the card arts deployed with the ones specified

Responses

200

updateCardMetadata response payload

application/json

500

Internal Server Error

post

/updateCardMetadata

HTTPcURLJavaScriptPython

POST /tsh/transitapi/1/0/updateCardMetadata HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 473

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "commutePlans": [
    {
      "identifier": "text",
      "title": [
        {
          "label": "text",
          "value": "text",
          "language": "text"
        }
      ],
      "usage": {
        "label": "Usage",
        "value": [
          {
            "text": "text",
            "language": "text"
          }
        ]
      },
      "validityPeriod": {
        "startDate": "2026-06-12T20:01:20.101Z",
        "expiryDate": "2026-06-12T20:01:20.101Z",
        "dateStyle": "SHORT",
        "timeStyle": "SHORT"
      }
    }
  ],
  "cardArtManifest": [
    "text"
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Request to initiate a session for a digital card

post

This method is used by TES to request TSH to initiate a session for a digital card. This request is sent when TES needs to exchange commands with targeted device (during a topup for example).

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · min: 1 · max: 48Required

The Card Identifier. Unique for each card.

operationstring · enumOptional

The operation to be initiated

Possible values:

Responses

200

initiateCardSession response payload

application/json

500

Internal Server Error

post

/initiateCardSession

HTTPcURLJavaScriptPython

POST /tsh/transitapi/1/0/initiateCardSession HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "operation": "READ_BALANCE"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Request to get the list of cards details associated to a card account

post

This method is used by TES to request TSH to return the list of cards associated to the specified card account.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardAccountIdstring · min: 1 · max: 48Required

The Card Account Identifier. Unique for each card account.

Responses

200

getCards response payload

application/json

walletCardAccountIdstring · min: 1 · max: 64Optional

The Wallet Card Account Identifier. Unique for each wallet card account.

walletAccountIdstring · min: 1 · max: 128Optional

The Wallet Account Identifier. Unique for each wallet account.

cardAccountStatestring · enumOptionalPossible values:

500

Internal Server Error

post

/getCards

HTTPcURLJavaScriptPython

POST /tsh/transitapi/1/0/getCards HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 146

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z"
  },
  "issuerId": "text",
  "cardAccountId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "walletCardAccountId": "text",
  "walletAccountId": "text",
  "cardAccountState": "ACTIVE",
  "cards": [
    {
      "cardId": "text",
      "walletCardId": "text",
      "cardState": "CREATED"
    }
  ]
}

Request to refund a card account

post

This method is used by TES to notify TSH that a card account has been refunded.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardAccountIdstring · min: 1 · max: 48Required

The Card Account Identifier. Unique for each card account.

Responses

200

refundCardAccount response payload

application/json

500

Internal Server Error

post

/refundCardAccount

HTTPcURLJavaScriptPython

POST /tsh/transitapi/1/0/refundCardAccount HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 146

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z"
  },
  "issuerId": "text",
  "cardAccountId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Get request status

post

This method is used by TES to check the status of an asynchronous request previously submitted.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

targetRequestIdstring · min: 1 · max: 48Required

Unique request identifier

Responses

200

getRequestStatus response payload

application/json

requestStatusstring · enumOptional

The status of the request.

Possible values:

500

Internal Server Error

post

/getRequestStatus

HTTPcURLJavaScriptPython

POST /tsh/transitapi/1/0/getRequestStatus HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 148

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z"
  },
  "issuerId": "text",
  "targetRequestId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-12T20:01:20.101Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "requestStatus": "PROCESSING"
}