API de tránsito

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.

Parámetros de encabezado

x-actor-idstring · máx: 32Opcional

HTTP header identifying the wallet provider that holds the digital card.

Cuerpo

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · mín: 1 · máx: 48Requerido

The Card Identifier. Unique for each card.

Respuestas

200

submitCardPersoData response payload

application/json

500

Internal Server Error

post/submitCardPersoData

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "cardPersoData": [
    {
      "name": "text",
      "value": "text",
      "keyIndex": "text"
    }
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z",
    "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.

Parámetros de encabezado

x-actor-idstring · máx: 32Opcional

HTTP header identifying the wallet provider that holds the digital card.

Cuerpo

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · mín: 1 · máx: 48Requerido

The Card Identifier. Unique for each card.

actionstring · enumRequerido

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

Valores posibles:

Respuestas

200

updateCardState response payload

application/json

500

Internal Server Error

post/updateCardState

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "action": "DELETE"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z",
    "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.

Parámetros de encabezado

x-actor-idstring · máx: 32Opcional

HTTP header identifying the wallet provider that holds the digital card.

Cuerpo

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · mín: 1 · máx: 48Requerido

The Card Identifier. Unique for each card.

cardArtManifeststring[]Opcional

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

Respuestas

200

updateCardMetadata response payload

application/json

500

Internal Server Error

post/updateCardMetadata

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z"
  },
  "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-01-01T00:00:00.000Z",
        "expiryDate": "2026-01-01T00:00:00.000Z",
        "dateStyle": "SHORT",
        "timeStyle": "SHORT"
      }
    }
  ],
  "cardArtManifest": [
    "text"
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z",
    "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).

Parámetros de encabezado

x-actor-idstring · máx: 32Opcional

HTTP header identifying the wallet provider that holds the digital card.

Cuerpo

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · mín: 1 · máx: 48Requerido

The Card Identifier. Unique for each card.

operationstring · enumOpcional

The operation to be initiated

Valores posibles:

Respuestas

200

initiateCardSession response payload

application/json

500

Internal Server Error

post/initiateCardSession

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "operation": "READ_BALANCE"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z",
    "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.

Parámetros de encabezado

x-actor-idstring · máx: 32Opcional

HTTP header identifying the wallet provider that holds the digital card.

Cuerpo

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

cardAccountIdstring · mín: 1 · máx: 48Requerido

The Card Account Identifier. Unique for each card account.

Respuestas

200

getCards response payload

application/json

walletCardAccountIdstring · mín: 1 · máx: 64Opcional

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

walletAccountIdstring · mín: 1 · máx: 128Opcional

The Wallet Account Identifier. Unique for each wallet account.

cardAccountStatestring · enumOpcionalValores posibles:

500

Internal Server Error

post/getCards

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z"
  },
  "issuerId": "text",
  "cardAccountId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z",
    "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.

Parámetros de encabezado

x-actor-idstring · máx: 32Opcional

HTTP header identifying the wallet provider that holds the digital card.

Cuerpo

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

cardAccountIdstring · mín: 1 · máx: 48Requerido

The Card Account Identifier. Unique for each card account.

Respuestas

200

refundCardAccount response payload

application/json

500

Internal Server Error

post/refundCardAccount

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z"
  },
  "issuerId": "text",
  "cardAccountId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Get request status

post

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

Parámetros de encabezado

x-actor-idstring · máx: 32Opcional

HTTP header identifying the wallet provider that holds the digital card.

Cuerpo

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

targetRequestIdstring · mín: 1 · máx: 48Requerido

Unique request identifier

Respuestas

200

getRequestStatus response payload

application/json

requestStatusstring · enumOpcional

The status of the request.

Valores posibles:

500

Internal Server Error

post/getRequestStatus

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z"
  },
  "issuerId": "text",
  "targetRequestId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-01-01T00:00:00.000Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "requestStatus": "PROCESSING"
}