Token Provisioning and Management API

TSP-API-OUT-v2-Provisioning-Management-oas2.yaml

POST /tokens

post

This method is used by TSH to request the creation of a new token.

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

issuerCardRefIdstring · min: 1 · max: 64Optional

A unique identifier of the issuer that aims to identify the funding card.
This parameter is provided by the TSH unless it's not connected to Issuer.
This identifier might be updated by Issuer on card replacement/renewal flows.

walletCardRefIdstring · min: 1 · max: 64Required

A unique identifier of the wallet provider that aims to identify the funding card.
This parameter is provided by the TSH.
For ApplePay, it corresponds to the FPANID.
This identifier remains constant even on card replacement/renewal flows.

cipheredCardInfostring · min: 1 · max: 8196Optional

TSH sends card information as JSON encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:

The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.
The key encryption algorithm is either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.
The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new TSPs.
The encryption result is then encoded using base64.
The public key length in the certificate can be 2048-bit or 4096-bit.

Once deciphered, the card info contains the following information:

JSON field parameter name	description	MOC	Length
fpan	The funding pan to digitize	M	Up to 19
exp	The expiry date in the format MMYY	O	4
cvv	Depending of the OEM, this value is provided or not	O	3 or 4
additionalCardInfos	Optional JSON Open format, in order to add additional card info - project dependent	O	Up to 8177

Note: If not provided, the TSP must rely on the walletCardRefId provided to find the funding card to digitize from its token vault.

publicKeyIdentifierstring · min: 1 · max: 32Optional

Identifier of the key used to encrypt cipheredCardInfo.
Provided by TSP to Thales during onboarding.

tokenProductIdstring · min: 1 · max: 48Optional

ID of the token product (Identify token domain).

As the token products are mapped to Issuer card products, the values shall be defined at the begining of the project with the TSP.

tokenRequestorIdstring · min: 1 · max: 48Required

ID of the token requestor in the format expected by the TSP

tokenStorageIdstring · min: 1 · max: 64Required

Token storage unique identifier (also known as deviceId or applicationId).
Indicates the storage in which the token has been digitized.
For ApplePay, it corresponds to the device SEID.

reusedTokenIdstring · min: 1 · max: 48Optional

The tokenId provided in case the Wallet Provider wants to re-use an existing token.
This is applicable for Apple Pay only and needs to have an agreement on this process at the beginning of a project.

initialStatestring · enumOptional

Initial state of the token when created.
Default value is SUSPENDED

Example: SUSPENDEDPossible values:

Responses

200

createToken response payload

application/json

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 115, 163, 164, 166, 167, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

post

/tokens

POST /tsp/trapi/v2.0/tokens HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 625

{
  "issuerId": "ISSUER1234",
  "issuerCardRefId": "text",
  "walletCardRefId": "text",
  "cipheredCardInfo": "text",
  "publicKeyIdentifier": "text",
  "tokenProductId": "text",
  "tokenRequestorId": "text",
  "tokenStorageId": "text",
  "deviceInfo": {
    "deviceName": "text",
    "brand": "text",
    "model": "text",
    "type": "text",
    "language": "eng",
    "appletVersion": "1.22",
    "ecommerceCertificate": {
      "keyIdentifier": "f479b621893ad8506107bb10b03f8630",
      "certificate": "-----BEGIN CERTIFICATE-----nMIICtTCCAlugAwIBAgIINya88tUZW8swCgYIKoZIzj0EAwIwdTEvMC0GA1UEAwwmnVGVzdCBBcHBsZSBTeXN0ZW0gSW50ZWdyYXRpb24gQ0EgLSBFQ0MxIDAeBgNVB....."
    }
  },
  "reusedTokenId": "text",
  "initialState": "SUSPENDED"
}

{
  "tokenId": "text",
  "tokenInfo": {
    "exp": "1220",
    "last4": "1234"
  }
}

PUT /tokens/{tokenId}/cardInfo

put

This method is used by TSH to request the update of funding pan information of the token

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

newCipheredCardInfostring · min: 1 · max: 8196Required

TSH sends new card information as JSON encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:

The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.
The key encryption algorithm is either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.
The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new TSPs.
The encryption result is then encoded using base64.
The public key length in the certificate can be 2048-bit or 4096-bit.

Once deciphered, the card info contains the following information:

JSON field parameter name	description	MOC	Length
newFpan	The new funding pan value to update	O	Up to 19
newExp	The new expiry date in the format MMYY	O	4
newAdditionalCardInfos	Optional JSON Open format, in order add/update/delete additional card info - project dependent	O	Up to 8177

Note: At least one of the three JSON fields needs to be provided.

publicKeyIdentifierstring · min: 1 · max: 32Optional

Identifier of the key used to encrypt newCipheredCardInfo.
Provided by TSP to Thales during onboarding.

newIssuerCardRefIdstring · min: 1 · max: 64Optional

New unique identifier of the issuer that aims to identify the funding card.

Responses

204

successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 163, 166, 432, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

put

/tokens/{tokenId}/cardInfo

PUT /tsp/trapi/v2.0/tokens/{tokenId}/cardInfo HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "issuerId": "ISSUER1234",
  "newCipheredCardInfo": "text",
  "publicKeyIdentifier": "text",
  "newIssuerCardRefId": "text"
}

No content

PUT /tokens/{tokenId}/state

put

This method is used by TSH to request the update of token state

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

newStatestring · enumRequired

state of the token

Possible values:

reasonstring · min: 1 · max: 16Optional

The reason of the state update

Possible values are:

reason code	description
11001	Activation from user interaction
21001	Activation initiated by the issuer
21002	Deletion initiated by the issuer
11002	Deletion initiated by the user
21003	Suspension initiated by the issuer
11003	Suspension initiated by the user
21004	Resumption initiated by the issuer
11004	Resumption initiated by the user

Responses

204

successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 432, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

put

/tokens/{tokenId}/state

PUT /tsp/trapi/v2.0/tokens/{tokenId}/state HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "issuerId": "ISSUER1234",
  "newState": "SUSPENDED",
  "reason": "text"
}

No content

POST /tokens/{tokenId}/replenishment

post

This method is used by TSH, in case of HCE, to request replenishment of payment credentials in the mobile wallet. This API only applies to TSH Pay solution (Issuer HCE wallet).

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

atcstring · min: 4 · max: 4Required

Value of the application transaction counter that will be used in the next payment transaction. The ATC is encoded as an hexa string on 4 digits.

lastRepCounterstring · max: 5Required

Value of the replenishment counter for the last replenishment.

schemeTranRecordsstring · max: 2000Optional

Transaction records for the last transactions as specified by the payment scheme. The transaction records data is encoded in base 64.

schemeTranRecSigstring · max: 200Optional

Signature of the transaction records computed according to the scheme specifications and encoded in hexa.

Responses

200

requestReplenishment response payload

application/json

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 119, 432, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

post

/tokens/{tokenId}/replenishment

POST /tsp/trapi/v2.0/tokens/{tokenId}/replenishment HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 390

{
  "issuerId": "ISSUER1234",
  "atc": "text",
  "usageLimitsStatus": {
    "paymentCredRemaining": 1,
    "paymentRemaining": 1,
    "expiryDate": "text"
  },
  "paymentCredsStatus": [
    {
      "sukStatus": "USED_FOR_CONTACTLESS",
      "diversifier": "text",
      "timestamp": "text",
      "paymentCredAttr": {
        "type": "SUK",
        "code": "SUK_IDN",
        "channel": "CONTACTLESS",
        "dki": "text"
      }
    }
  ],
  "lastRepCounter": "text",
  "schemeTranRecords": "text",
  "schemeTranRecSig": "text"
}

{
  "repCounter": "text",
  "usageLimits": {
    "maxPayments": 1,
    "expiryDate": "text"
  },
  "paymentCredsData": [
    {
      "encPaymentCredData": {
        "encData": "text",
        "encType": "RAW",
        "rawEncParams": {
          "algo": "3DES",
          "mode": "ECB",
          "padding": "ISO_7816",
          "iv": "text",
          "aeadNonce": "text",
          "aeadMac": "text",
          "keyId": "text"
        }
      },
      "paymentCredAttr": {
        "type": "SUK",
        "code": "SUK_IDN",
        "channel": "CONTACTLESS",
        "dki": "text"
      },
      "diversifiers": [
        "text"
      ]
    }
  ]
}

PUT /tokens/{tokenId}/replenishment/status

put

This method is used by TSH, in case of HCE, to notify the TSP the replenishment of payment credentials has been completed in the mobile wallet. This API only applies to TSH Pay solution (Issuer HCE wallet).

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

repCounterstring · max: 5Required

Value of the replenishment counter for the last replenishment.

diversifiersstring[]Optional

Payment credential diversifier:

For an SUK, this is an ATC which is a string of 4 hexa digits.
For an LUK, this is an "YHHHHCC" Visa CBP diversifier which is a string of 7 digits.

Responses

204

successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 119, 432, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

put

/tokens/{tokenId}/replenishment/status

PUT /tsp/trapi/v2.0/tokens/{tokenId}/replenishment/status HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "issuerId": "ISSUER0123",
  "repCounter": "33",
  "diversifiers": [
    "0025",
    "0026",
    "0027",
    "0028"
  ]
}

No content

PUT /tokens/{tokenId}/newData/status

put

This method is used by TSH to inform the TSP about the token re-personalization result in case of token renewal.

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

statusstring · enumRequiredPossible values:

Responses

204

successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

put

/tokens/{tokenId}/newData/status

PUT /tsp/trapi/v2.0/tokens/{tokenId}/newData/status HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "issuerId": "ISSUER0123",
  "status": "SUCCESS"
}

No content

GET /healthCheck

get

This method is used by TSH to monitor TSP health. It should be used every 30 seconds in production environment.

Header parameters

x-request-idstring · min: 1 · max: 64Required

Unique identifier of the request

Responses

204

successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 911, 921

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

get

/healthCheck

GET /tsp/trapi/v2.0/healthCheck HTTP/1.1
x-request-id: text
Accept: */*

No content

POST /tokens/{tokenId}/reperso

post

This request is triggered when TSH has to repersonalize a token and requires all the data elements associated.

After this request, TSP shall recover all the existing elements and submit it to the TSH through Submit New Token Data.

TSH will callback TSP through the Notify Token Reperso Result to notify the profile has been pushed to the device with success. At this moment, TSP shall set the ATC to zero to sync with the ATC personalized in the device.

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Optional

Unique Identifier of Issuer

Example: ISSUER1234

Responses

204

successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 321, 432, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

post

/tokens/{tokenId}/reperso

POST /tsp/trapi/v2.0/tokens/{tokenId}/reperso HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "issuerId": "ISSUER1234"
}

No content

POST /tokens/{tokenId}/appletUpdate

post

For ApplePay only. This notification informs the TSP that the applet version was updated by Apple.

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

appletVersionstring · min: 1 · max: 32Required

Only for ApplePay. Applet version as provided by the Wallet Provider.

Example: 1.22

Responses

204

successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 119, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

post

/tokens/{tokenId}/appletUpdate

POST /tsp/trapi/v2.0/tokens/{tokenId}/appletUpdate HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "issuerId": "ISSUER1234",
  "appletVersion": "1.22"
}

No content

POST /listTokens

post

This method is used by TSH to request the list of tokens associated to either a funding PAN, a card reference ID or a token PAN. In case of a search by token PAN, the list returned by TSP shall contain 1 element at most.

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

cipheredCardInfostring · min: 1 · max: 8196Optional

TSH sends card information as JSON encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:

The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.
The key encryption algorithm is either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.
The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new TSPs.
The encryption result is then encoded using base64.
The public key length in the certificate can be 2048-bit or 4096-bit.

Once deciphered, the card info contains the following information:

JSON field parameter name	description	MOC	Length
fpan	The funding pan	M	Up to 19

cipheredTokenInfostring · min: 1 · max: 8196Optional

TSH sends token information as JSON encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:

The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.
The key encryption algorithm is either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.
The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new TSPs.
The encryption result is then encoded using base64.
The public key length in the certificate can be 2048-bit or 4096-bit.

Once deciphered, the card info contains the following information:

JSON field parameter name	description	MOC	Length
dpan	The token PAN	M	Up to 19

issuerCardRefIdstring · min: 1 · max: 64Optional

publicKeyIdentifierstring · min: 1 · max: 32Optional

Identifier of the key used to encrypt cipheredCardInfo.
Provided by TSP to Thales during onboarding.

Responses

200

listTokens response payload

application/json

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 166, 911, 921

application/json

500Error

503Error

post

/listTokens

POST /tsp/trapi/v2.0/listTokens HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "issuerId": "ISSUER1234",
  "cipheredCardInfo": "text",
  "cipheredTokenInfo": "text",
  "issuerCardRefId": "text",
  "publicKeyIdentifier": "text"
}

{
  "tokenList": [
    {
      "tokenId": "text",
      "exp": "1220",
      "last4": "1234",
      "state": "SUSPENDED",
      "tokenStorageId": "text",
      "tokenRequestorId": "text",
      "deviceInfo": {
        "deviceName": "text",
        "brand": "text",
        "model": "text",
        "type": "text",
        "language": "eng",
        "appletVersion": "1.22",
        "ecommerceCertificate": {
          "keyIdentifier": "f479b621893ad8506107bb10b03f8630",
          "certificate": "-----BEGIN CERTIFICATE-----nMIICtTCCAlugAwIBAgIINya88tUZW8swCgYIKoZIzj0EAwIwdTEvMC0GA1UEAwwmnVGVzdCBBcHBsZSBTeXN0ZW0gSW50ZWdyYXRpb24gQ0EgLSBFQ0MxIDAeBgNVB....."
        }
      },
      "creationDate": "2026-06-12T15:54:43.611Z"
    }
  ]
}

POST /tokens/{tokenId}/replenish

post

This request is triggered when TSH has to replenish a token. This API only applies to Google Pay solution.

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Optional

Unique Identifier of Issuer

Example: ISSUER1234

Responses

200

replenishToken response payload

application/json

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 321, 432, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

post

/tokens/{tokenId}/replenish

POST /tsp/trapi/v2.0/tokens/{tokenId}/replenish HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "issuerId": "ISSUER1234"
}

{
  "kekLabel": "text",
  "kekKcv": "text",
  "paymentKeys": "text"
}

PUT /tokens/{tokenId}/replenish/done

put

This method is used by TSH to inform the TSP that the token replenishment has been done. This API only applies to Google Pay solution.

Path parameters

tokenIdstring · min: 1 · max: 48Required

Identifier of the token to update

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier used to trace function calls across systems

Body

issuerIdstring · min: 10 · max: 10Required

Unique Identifier of Issuer

Example: ISSUER1234

Responses

204

successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 911, 921

application/json

500

Internal Server Error Retry possible

503

Service Unavailable Retry possible

put

/tokens/{tokenId}/replenish/done

PUT /tsp/trapi/v2.0/tokens/{tokenId}/replenish/done HTTP/1.1
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "issuerId": "ISSUER0124"
}

No content

PreviousOutgoing operations (to TSP)NextIncoming operations (from TSP)

Last updated 18 days ago

Was this helpful?