API de Tránsito

TES-OUT-v1-tránsito.yaml

Request to create a digital card account

post

This method is used by TSH to request the creation of a digital card account to the TES. This request can come with a payment order which comprises a payment instrument and either the identifier of wallet card used or the wallet account used for the payment In this case, the TES is responsible for returning an order confirmation in the form of a purchase identifier in all cases where the user may be deducted money. The TES shall also create a new card account associated to a unique identifier. In case of stored value account, the card account identifier shall be the card iedntifier.

Parámetros de encabezado

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

HTTP header identifying the actor initiating the request.

Cuerpo

application/json

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

The Card Issuer Identifier. Unique for each card issuer.

walletProviderIdstringRequerido

The Wallet Provider Identifier.For example:APPLE_PAYHUAWEI_PAYXIAOMI_PAY

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

The Product Identifier. Unique for each product. It is used by TSH to find the right metadata (e.g. card arts) associated to the product.

opaqueServiceProviderDataobject · opaqueServiceProviderDataOpcional

This object gives additional service provider data captured by the wallet provider during a payment.The structure of this object is opaque to TSH.

Respuestas

200

createCardAccount response payload

application/json

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

The Card Account Identifier. Unique for each card account.

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

signaturestring · mín: 1 · máx: 1024Opcional

Signature covering the concatenation of the UTF-8 encoded bytes of orderId followed by purchaseId. It is a ECDSA signature in PKCS7 format.

500

Internal Server Error

post/createCardAccount

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/createCardAccount HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 463

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "issuerId": "text",
  "walletProviderId": "text",
  "productId": "text",
  "order": {
    "orderId": "text",
    "amount": 1,
    "currency": "text",
    "paymentInstrument": {
      "paymentData": "text",
      "type": "IN-APP_CRYPTO",
      "version": "EC_v1",
      "signature": "text",
      "header": {
        "ephemeralPublicKey": "text",
        "wrappedKey": "text",
        "transactionId": "text",
        "publicKeyHash": "text"
      }
    }
  },
  "opaqueServiceProviderData": {}
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "cardAccountId": "text",
  "purchaseId": "text",
  "signature": "text"
}

Request to check digital card account eligibility

post

This method is used by TSH to check that a card account is eligible for provisioning.

Parámetros de encabezado

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

HTTP header identifying the actor initiating the request.

Cuerpo

application/json

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.

walletProviderIdstringRequerido

The Wallet Provider Identifier.For example:APPLE_PAYHUAWEI_PAYXIAOMI_PAY

cardSourcestring · enumOpcionalValores posibles:

Respuestas

200

checkCardAccount response payload

application/json

productIdstring · mín: 1 · máx: 16Opcional

The Product Identifier. Unique for each product. It is used by TSH to find the right metadata (e.g. card arts) associated to the product.

cardArtManifeststring[] · mín: 2Opcional

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.

If this parameter is not specified, TSH will pick default assets linked to productId. Otherwise the specified assets will be retrieved using the getAsset API

500

Internal Server Error

post/checkCardAccount

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/checkCardAccount HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 314

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "issuerId": "text",
  "cardAccountId": "text",
  "walletProviderId": "text",
  "device": {
    "deviceId": "text",
    "deviceType": "PHONE",
    "language": "text",
    "phoneNumberLastDigits": "text",
    "deviceName": "text"
  },
  "cardSource": "ON-FILE"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "productId": "text",
  "cardArtManifest": [
    "text"
  ],
  "mobileApplicationInfo": {
    "associatedApplicationIdentifiers": [
      "text"
    ],
    "appLaunchURL": "text"
  }
}

Request to provision a digital card

post

This method is used by TSH to provision a digital card to user's device.

Parámetros de encabezado

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

HTTP header identifying the actor initiating the request.

Cuerpo

application/json

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.

walletCardIdstring · mín: 1 · máx: 64Requerido

The Wallet Card Identifier. Unique for each wallet card.

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

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

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

The Wallet Account Identifier. Unique for each wallet account.

cardLastDigitsstring · mín: 4 · máx: 5Opcional

The Card last 4 or 5 digits.

Respuestas

200

provisionCard response payload

application/json

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

The Card Identifier. Unique for each card.

displayCardNumberstring · mín: 1 · máx: 16Opcional

The card number to be displayed on the wallet.If it's not provided, the last 16 characters of cardAccountId will be used.

cardArtManifeststring[] · mín: 2Opcional

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.

If this parameter is not specified, TSH will pick default assets linked to productId. Otherwise the specified assets will be retrieved using the getAsset API

500

Internal Server Error

post/provisionCard

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/provisionCard HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 540

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "issuerId": "text",
  "cardAccountId": "text",
  "walletCardId": "text",
  "walletCardAccountId": "text",
  "walletAccountId": "text",
  "device": {
    "deviceId": "text",
    "deviceType": "PHONE",
    "language": "text",
    "phoneNumberLastDigits": "text",
    "deviceName": "text"
  },
  "walletScoring": {
    "color": "GREEN",
    "deviceScore": 1,
    "accountScore": 1,
    "phoneNumberScore": 1,
    "reasonCodes": [
      "text"
    ]
  },
  "customerData": {
    "dateOfBirth": "2026-07-11",
    "customerId": "text"
  },
  "cardLastDigits": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "cardId": "text",
  "displayCardNumber": "text",
  "cardholderName": [
    {
      "value": "text",
      "language": "text"
    }
  ],
  "cardData": {
    "balanceAmount": 1
  },
  "cardArtManifest": [
    "text"
  ]
}

Operation result notification.

post

This method is used by TSH to notify the result of an operation identified by a sessionId. It can be the result of a provisioning or a state update.

Parámetros de encabezado

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

HTTP header identifying the actor initiating the request.

Cuerpo

application/json

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

The Card Issuer Identifier. Unique for each card issuer.

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

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

The Card Account Identifier. Unique for each card account.

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

The Card Identifier. Unique for each card.

isProvisioningbooleanRequerido

Flag indicating whether this notification is about provisioning or not.

resultDataobject · resultDataOpcional

This object gives additional information about the operation result. For Calypso, the following will be provided:

"resultData": {
	"csn" : "1122334455667788"        
}

For EMV, the following will be provided:

"resultData": {
	"pan" : "$encrypted_value"        
}

statusCodenumberRequerido

The status code.

statusMsgstringOpcional

Optional additional status message

Respuestas

200

notifyOperationResult response payload

application/json

500

Internal Server Error

post/notifyOperationResult

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/notifyOperationResult HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 254

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "issuerId": "text",
  "purchaseId": "text",
  "cardAccountId": "text",
  "cardId": "text",
  "isProvisioning": true,
  "resultData": {},
  "statusCode": 1,
  "statusMsg": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Request to top up a digital card account

post

This method is used by TSH to request the top up of a card account to the TES. This request can come with a payment order which comprises a payment instrument. It is initiated from OEM Wallet. In this case, the TES is responsible for returning an order confirmation in the form of a purchase identifier in all cases where the user may be deducted money.

Parámetros de encabezado

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

HTTP header identifying the actor initiating the request.

Cuerpo

application/json

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.

opaqueServiceProviderDataobject · opaqueServiceProviderDataOpcional

This object gives additional service provider data captured by the wallet provider during a payment.The structure of this object is opaque to TSH.

Respuestas

200

topUpCardAccount response payload

application/json

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

signaturestring · mín: 1 · máx: 1024Opcional

Signature covering the concatenation of the UTF-8 encoded bytes of orderId followed by purchaseId. It is a ECDSA signature in PKCS7 format.

500

Internal Server Error

post/topUpCardAccount

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/topUpCardAccount HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 441

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "issuerId": "text",
  "cardAccountId": "text",
  "order": {
    "orderId": "text",
    "amount": 1,
    "currency": "text",
    "paymentInstrument": {
      "paymentData": "text",
      "type": "IN-APP_CRYPTO",
      "version": "EC_v1",
      "signature": "text",
      "header": {
        "ephemeralPublicKey": "text",
        "wrappedKey": "text",
        "transactionId": "text",
        "publicKeyHash": "text"
      }
    }
  },
  "opaqueServiceProviderData": {}
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "purchaseId": "text",
  "signature": "text"
}

Request to update digital card state

post

This method is used by TSH to indicate the update of a digital card to the TES. It is usually initiated from OEM Wallet.

Parámetros de encabezado

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

HTTP header identifying the actor initiating the request.

Cuerpo

application/json

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.

newStatestring · enumRequerido

The new state to apply on the card

Valores posibles:

Respuestas

200

updateCardState response payload

application/json

500

Internal Server Error

post/updateCardState

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/updateCardState HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "newState": "DELETED"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Request to get the metadata of card accounts for the given list of card account IDs

post

This method is used by TSH to request TES to return the metadata of card accounts for the given list of card account IDs.

Cuerpo

application/json

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

The Card Issuer Identifier. Unique for each card issuer.

cardAccountIdsstring[]Requerido

The list of card account identifiers

Respuestas

200

getCardAccountsMetadata response payload

application/json

500

Internal Server Error

post/getCardAccountsMetadata

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/getCardAccountsMetadata HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "issuerId": "text",
  "cardAccountIds": [
    "text"
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "cardAccounts": [
    {
      "cardAccountId": "text",
      "cardAccountState": "text",
      "productsList": [
        {
          "identifier": "text",
          "value": 1,
          "lastUpdatedDate": "2026-07-11T15:33:11.446Z",
          "validFromDate": "2026-07-11T15:33:11.446Z",
          "validUntilDate": "2026-07-11T15:33:11.446Z"
        }
      ]
    }
  ]
}

Request to get the list of available actions for the given card

post

This method is used by TSH to request TES to return the list of available actions for a given card.

Cuerpo

application/json

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.

appletDatastring · mín: 1 · máx: 8192Opcional

Data from device representing card image, for filtering allowed actions.Base64 encoded string.

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

Identifier for the plan to retrieve actions for.If not present, all valid actions shall be returned.

Respuestas

200

getCardActions response payload

application/json

validUntilstring · date-timeOpcional

Configuration valid until the specified time.RFC3339 format. Example 2018-12-24T17:32:28Z

500

Internal Server Error

post/getCardActions

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/getCardActions HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 193

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "appletData": "text",
  "associatedPlanIdentifier": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "cardActions": [
    {
      "identifier": "text",
      "planIdentifier": "text",
      "title": [
        {
          "label": "text",
          "value": "text",
          "language": "text"
        }
      ],
      "amount": 1,
      "currency": "text",
      "startDate": "2026-07-11T15:33:11.446Z",
      "expirationDate": "2026-07-11T15:33:11.446Z"
    }
  ],
  "validUntil": "2026-07-11T15:33:11.446Z"
}

Request to get asset from TES

post

This method is used by TSH to request asset to TES

Cuerpo

application/json

assetIdstring · máx: 64Requerido

Unique identifier of the asset

Respuestas

200

getAsset response payload

application/json

contentTypestring · máx: 32Requerido

The asset type.Possible values are:iconcardBackgroundCombined

500

Internal Server Error

post/getAsset

HTTPcURLJavaScriptPython

POST /tes/transitapi/1/0/getAsset HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 122

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z"
  },
  "assetId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-07-11T15:33:11.446Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "contentType": "text",
  "content": [
    {
      "mimeType": "text",
      "encodedData": "text",
      "width": 1,
      "height": 1
    }
  ]
}