Transit API

TES-OUT-v1-transit.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.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the request.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

walletProviderIdstringRequired

The Wallet Provider Identifier.For example:APPLE_PAYHUAWEI_PAYXIAOMI_PAY

productIdstring · min: 1 · max: 16Required

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.

opaqueServiceProviderDataobjectOptional

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

Responses

200

createCardAccount response payload

application/json

cardAccountIdstring · min: 1 · max: 48Optional

The Card Account Identifier. Unique for each card account.

purchaseIdstring · min: 1 · max: 64Optional

signaturestring · min: 1 · max: 1024Optional

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-06-15T23:59:14.071Z"
  },
  "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-06-15T23:59:14.071Z",
    "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.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the request.

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.

walletProviderIdstringRequired

The Wallet Provider Identifier.For example:APPLE_PAYHUAWEI_PAYXIAOMI_PAY

cardSourcestring · enumOptionalPossible values:

Responses

200

checkCardAccount response payload

application/json

productIdstring · min: 1 · max: 16Optional

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[] · min: 2Optional

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-06-15T23:59:14.071Z"
  },
  "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-06-15T23:59:14.071Z",
    "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.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the request.

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.

walletCardIdstring · min: 1 · max: 64Required

The Wallet Card Identifier. Unique for each wallet card.

walletCardAccountIdstring · min: 1 · max: 64Required

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

walletAccountIdstring · min: 1 · max: 128Required

The Wallet Account Identifier. Unique for each wallet account.

cardLastDigitsstring · min: 4 · max: 5Optional

The Card last 4 or 5 digits.

Responses

200

provisionCard response payload

application/json

cardIdstring · min: 1 · max: 48Optional

The Card Identifier. Unique for each card.

displayCardNumberstring · min: 1 · max: 16Optional

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

cardArtManifeststring[] · min: 2Optional

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-06-15T23:59:14.071Z"
  },
  "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-06-15",
    "customerId": "text"
  },
  "cardLastDigits": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-15T23:59:14.071Z",
    "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.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the request.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

purchaseIdstring · min: 1 · max: 64Optional

cardAccountIdstring · min: 1 · max: 48Optional

The Card Account Identifier. Unique for each card account.

cardIdstring · min: 1 · max: 48Optional

The Card Identifier. Unique for each card.

isProvisioningbooleanRequired

Flag indicating whether this notification is about provisioning or not.

resultDataobjectOptional

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"        
}

statusCodenumberRequired

The status code.

statusMsgstringOptional

Optional additional status message

Responses

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-06-15T23:59:14.071Z"
  },
  "issuerId": "text",
  "purchaseId": "text",
  "cardAccountId": "text",
  "cardId": "text",
  "isProvisioning": true,
  "resultData": {},
  "statusCode": 1,
  "statusMsg": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-15T23:59:14.071Z",
    "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.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the request.

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.

opaqueServiceProviderDataobjectOptional

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

Responses

200

topUpCardAccount response payload

application/json

purchaseIdstring · min: 1 · max: 64Optional

signaturestring · min: 1 · max: 1024Optional

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-06-15T23:59:14.071Z"
  },
  "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-06-15T23:59:14.071Z",
    "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.

Header parameters

x-actor-idstring · max: 32Required

HTTP header identifying the actor initiating the 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.

newStatestring · enumRequired

The new state to apply on the card

Possible values:

Responses

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-06-15T23:59:14.071Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "newState": "DELETED"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-15T23:59:14.071Z",
    "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.

Body

application/json

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardAccountIdsstring[]Required

The list of card account identifiers

Responses

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-06-15T23:59:14.071Z"
  },
  "issuerId": "text",
  "cardAccountIds": [
    "text"
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-15T23:59:14.071Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "cardAccounts": [
    {
      "cardAccountId": "text",
      "cardAccountState": "text",
      "productsList": [
        {
          "identifier": "text",
          "value": 1,
          "lastUpdatedDate": "2026-06-15T23:59:14.071Z",
          "validFromDate": "2026-06-15T23:59:14.071Z",
          "validUntilDate": "2026-06-15T23:59:14.071Z"
        }
      ]
    }
  ]
}

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.

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.

appletDatastring · min: 1 · max: 8192Optional

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

associatedPlanIdentifierstring · min: 1 · max: 64Optional

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

Responses

200

getCardActions response payload

application/json

validUntilstring · date-timeOptional

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-06-15T23:59:14.071Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "appletData": "text",
  "associatedPlanIdentifier": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-15T23:59:14.071Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "cardActions": [
    {
      "identifier": "text",
      "planIdentifier": "text",
      "title": [
        {
          "label": "text",
          "value": "text",
          "language": "text"
        }
      ],
      "amount": 1,
      "currency": "text",
      "startDate": "2026-06-15T23:59:14.071Z",
      "expirationDate": "2026-06-15T23:59:14.071Z"
    }
  ],
  "validUntil": "2026-06-15T23:59:14.071Z"
}

Request to get asset from TES

post

This method is used by TSH to request asset to TES

Body

application/json

assetIdstring · max: 64Required

Unique identifier of the asset

Responses

200

getAsset response payload

application/json

contentTypestring · max: 32Required

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-06-15T23:59:14.071Z"
  },
  "assetId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-15T23:59:14.071Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "contentType": "text",
  "content": [
    {
      "mimeType": "text",
      "encodedData": "text",
      "width": 1,
      "height": 1
    }
  ]
}