Token Management

Create Token

post

Important: Use this operation only when the end user is interacting with the merchant website or application and when a fast response time is important. It takes in average 2-3 seconds to obtain a token with this operation. For all other use cases, it is preferred to use the operation 'createAsyncToken'.

Create a network token from card details.

ETP contacts the Scheme TSP to get the network token.

Parámetros de encabezado

authorizationstring · mín: 1 · máx: 512Requerido

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · mín: 1 · máx: 36Requerido

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Cuerpo

application/json

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

Identifier of the merchant provided by Thales at on-boarding.

encryptedDatastring · mín: 1 · máx: 8196Requerido

The user and card information encrypted in a JWE structure (see security section in the documentation).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
fpan	The funding pan to tokenize. Value expected when 'source' parameter is 'MANUAL' or 'ON_FILE'.	C	Up to 19
exp	The expiry date in format MMYY. Value expected when 'source' parameter is 'MANUAL' or 'ON_FILE'. Optional when VCES feature is activated for VISA	C	4
token	Token number. Value expected when 'source' parameter is 'TOKEN'.	C	Up to 19
name	The card holder name in the format FIRSTNAME LASTNAME or as written on the card. MDES limits the length to 27 characters so ETP may truncate the provided value. This parameter is mandatory for Discover card tokenization.	O	256
cvv	The security code. It can help the issuer in the decision of approving the payment.	O	3 or 4
accountId	The card holder account identifier defined by the Merchant. It can help the issuer in the decision of approving the payment.	O	24
email	The card holder email. This parameter is mandatory for AMEX card tokenization.	O	128

Example: {"fpan":"5123456789012345", "exp":"0822", "name":"JOHN DOE", "cvv":"123", "accountId":"johndoe", "email":"[email protected]"}

sourcestring · enum · máx: 32Requerido

The card info entry mode.
'MANUAL' It can help the issuer in the decision of approving the payment.
'TOKEN' is allowed just for Visa, used by token per token feature

Valores posibles:

languagestring · mín: 2 · máx: 2Requerido

Card holder language in ISO-639-1 two-letter language code.

Default: enExample: en

countrystring · mín: 2 · máx: 2Requerido

Card holder country in ISO-3166-1 alpha-2 two-letter country code.

Example: US

Respuestas

201

Created

application/json

400

Bad request - Not Retryable

application/json

401

Unauthorized - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

post

/tokens

HTTPcURLJavaScriptPython

POST /tsh-cof/tokens HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 282

{
  "merchantId": "75bfc5f5-13c3-4797-b617-bfa039ceb60f",
  "encryptedData": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ...XFBoMYUZodetZdvTiFvSkQ",
  "source": "MANUAL",
  "language": "en",
  "country": "US",
  "risk": {
    "accountScore": 4
  },
  "device": {
    "ipAddress": "172.16.254",
    "location": "47.0880,2.3635"
  }
}

{
  "tokenId": "COFTG-M-ce464906-cf39-4990-b4a8-c160e67c603a",
  "cardBin": "554312",
  "cardLastDigits": "2366",
  "cardExpiryDate": "0426",
  "tokenLastDigits": "5589",
  "tokenExpiryDate": "1036",
  "tokenState": "ACTIVE",
  "par": "5001a9f027e5629d11e3949a0800a",
  "vProvisionedTokenId": "ctf-12354658979-55",
  "cardProduct": {
    "issuerName": "Bank Name",
    "cardType": "DEBIT",
    "scheme": "MASTERCARD",
    "cardDescription": "The card description.",
    "cardArts": {
      "foregroundColor": "7FB8C8",
      "backgroundColor": "7FB8C9",
      "cardBackgroundImageId": "2ee5c858-a6a4-43f1-a503-ffde6c41fad9",
      "issuerLogoId": "1fd8594c-5284-4aeb-bb73-6129c1d6cdb2",
      "brandLogoId": "623046b7-4a8f-4550-bca8-45b38c9498a3",
      "cobrandLogoId": "5548eb95-3aee-4bb8-9abf-38a7ab2c1cf3",
      "completeCardImageId": "15ac4371-dcb9-4310-867e-b12338970276",
      "cardIconId": "14e3044fa-949e-4900-800f-88b8fc6cc3d5"
    },
    "termsAndConditionsUrl": "https://bank.com/tncs.html",
    "privacyPolicyUrl": "https://bank.com/privacyPolicy.html"
  },
  "color": "GREEN",
  "creationTimestamp": "2025-11-10T09:08:24.479Z"
}

Create Async Token

post

Create a network token from card details.

ETP contacts the Scheme TSP to get the network token.

The process is asynchronous. It takes few seconds to get the callback except for VISA where it takes from 10 minutes to several hours.

A notification 'notifyTokenCreation' is sent to the Merchant/PSP to complete the token creation process.

The notification shares the same 'x-correlation-id' as in the create token request.

Parámetros de encabezado

authorizationstring · mín: 1 · máx: 512Requerido

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · mín: 1 · máx: 36Requerido

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Cuerpo

application/json

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

Identifier of the merchant provided by Thales at on-boarding.

encryptedDatastring · mín: 1 · máx: 8196Requerido

The user and card information encrypted in a JWE structure (see security section in the documentation).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
fpan	The funding pan to tokenize.	M	Up to 19
exp	The expiry date in the format MMYY. Optional when VCES feature is activated for VISA	C	4
name	The card holder name in the format FIRSTNAME LASTNAME or as written on the card. MDES limits the length to 27 characters so ETP may truncate the provided value. This parameter is mandatory for Discover card tokenization.	O	256
cvv	The security code. It can help the issuer in the decision of approving the payment.	O	3 or 4
accountId	The card holder account identifier defined by the Merchant. It can help the issuer in the decision of approving the payment.	O	24
email	The card holder email. This parameter is mandatory for AMEX card tokenization.	O	128

Example: {"fpan":"5123456789012345", "exp":"0822", "name":"JOHN DOE", "cvv":"123", "accountId":"johndoe", "email":"[email protected]"}

sourcestring · enum · máx: 32Requerido

The card info entry mode.
'MANUAL' It can help the issuer in the decision of approving the payment.

Valores posibles:

languagestring · mín: 2 · máx: 2Requerido

Card holder language in ISO-639-1 two-letter language code.

Default: enExample: en

countrystring · mín: 2 · máx: 2Requerido

Card holder country in ISO-3166-1 alpha-2 two-letter country code.

Example: US

Respuestas

202

Accepted

400

Bad request - Not Retryable

application/json

401

Unauthorized - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

post

/async-tokens

HTTPcURLJavaScriptPython

POST /tsh-cof/async-tokens HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 282

{
  "merchantId": "75bfc5f5-13c3-4797-b617-bfa039ceb60f",
  "encryptedData": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ...XFBoMYUZodetZdvTiFvSkQ",
  "source": "MANUAL",
  "language": "en",
  "country": "US",
  "risk": {
    "accountScore": 4
  },
  "device": {
    "ipAddress": "172.16.254",
    "location": "47.0880,2.3635"
  }
}

Sin contenido

Create PCI Token

post

Create a PCI token from card details.

The Scheme TSP is not involved in the creation of the token.

ETP stores securely the card details and returns a token identifier to the Merchant/PSP.

In case of successful response, the Merchant/PSP can directly request for a transaction. No notification is sent (contrary to network tokens).

Parámetros de encabezado

authorizationstring · mín: 1 · máx: 512Requerido

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · mín: 1 · máx: 36Requerido

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Cuerpo

application/json

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

Identifier of the merchant provided by Thales at on-boarding.

encryptedDatastring · mín: 1 · máx: 8196Requerido

The user and card information encrypted in a JWE structure (see security section in the documentation).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
fpan	The funding pan to tokenize.	M	Up to 19
exp	The expiry date in the format MMYY.	M	4

Example: {"fpan":"5123456789012345", "exp":"0822"}

Respuestas

201

Created

application/json

400

Bad request - Not Retryable

application/json

401

Unauthorized - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

post

/pci-tokens

HTTPcURLJavaScriptPython

POST /tsh-cof/pci-tokens HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 143

{
  "merchantId": "75bfc5f5-13c3-4797-b617-bfa039ceb60f",
  "encryptedData": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ...XFBoMYUZodetZdvTiFvSkQ"
}

{
  "tokenId": "COFTG-G-75b0cc63-01bc-4b23-8fd6-26434a052098",
  "cardLastDigits": "2366",
  "cardExpiryDate": "0426",
  "tokenState": "ACTIVE",
  "creationTimestamp": "2025-11-10T09:08:24.479Z",
  "cardProduct": {
    "scheme": "MASTERCARD"
  }
}

Create Push Token

post

Create a network token from information provided by the Issuer to the Merchant application in a push provisioning use case (Visa and Mastercard only).

Parámetros de encabezado

authorizationstring · mín: 1 · máx: 512Requerido

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · mín: 1 · máx: 36Requerido

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Cuerpo

application/json

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

Identifier of the merchant provided by Thales at on-boarding.

pushProvisioningPayloadstring · mín: 1 · máx: 8196Requerido

The push provisioning payload provided by the Issuer to the merchant application.

For Mastercard, it corresponds to the 'pushAccountReceipt'.

For Visa, it corresponds to the 'encPaymentInstrument'.

schemestring · enum · máx: 32Requerido

The card primary scheme.

Example: MASTERCARDValores posibles:

encryptedDatastring · mín: 1 · máx: 8196Opcional

The user information encrypted in a JWE structure (see security section in the documentation).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
accountId	The card holder account identifier defined by the Merchant.	O	24
email	The card holder email.	O	128

Example: {"accountId:"johndoe", "email":"[email protected]"}

languagestring · mín: 2 · máx: 2Requerido

Card holder language in ISO-639-1 two-letter language code.

Default: enExample: en

countrystring · mín: 2 · máx: 2Requerido

Card holder country in ISO-3166-1 alpha-2 two-letter country code.

Example: US

Respuestas

201

Created

application/json

400

Bad request - Not Retryable

application/json

401

Unauthorized - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

post

/push-tokens

HTTPcURLJavaScriptPython

POST /tsh-cof/push-tokens HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 386

{
  "merchantId": "75bfc5f5-13c3-4797-b617-bfa039ceb60f",
  "pushProvisioningPayload": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ...XFBoMYUZodetZdvTiFvSkQ",
  "scheme": "MASTERCARD",
  "language": "en",
  "country": "US",
  "device": {
    "ipAddress": "172.16.254",
    "location": "47.0880,2.3635"
  },
  "encryptedData": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ...XFBoMYUZodetZdvTiFvSkQ",
  "risk": {
    "accountScore": 5
  }
}

{
  "tokenId": "COFTG-M-caa5f86b-787e-4698-971c-dc217d6dbcf5",
  "cardLastDigits": "2366",
  "cardExpiryDate": "0426",
  "tokenLastDigits": "5589",
  "tokenExpiryDate": "1036",
  "tokenState": "PENDING",
  "par": "5001a9f027e5629d11e3949a0800a",
  "cardProduct": {
    "cardType": "DEBIT",
    "scheme": "MASTERCARD",
    "issuerName": "Bank Name",
    "cardDescription": "The card description.",
    "cardArts": {
      "foregroundColor": "7FB8C8",
      "backgroundColor": "7FB8C9",
      "cardBackgroundImageId": "2ee5c858-a6a4-43f1-a503-ffde6c41fad9",
      "issuerLogoId": "1fd8594c-5284-4aeb-bb73-6129c1d6cdb2",
      "brandLogoId": "623046b7-4a8f-4550-bca8-45b38c9498a3",
      "cobrandLogoId": "5548eb95-3aee-4bb8-9abf-38a7ab2c1cf3",
      "completeCardImageId": "15ac4371-dcb9-4310-867e-b12338970276",
      "cardIconId": "14e3044fa-949e-4900-800f-88b8fc6cc3d5"
    },
    "termsAndConditionsUrl": "https://bank.com/tncs.html",
    "privacyPolicyUrl": "https://bank.com/privacyPolicy.html"
  },
  "encryptedData": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ...XFBoMYUZodetZdvTiFvSkQ",
  "creationTimestamp": "2025-11-10T09:08:24.479Z"
}

Get Token

get

Retrieve information about a token.

For EMV Tokens, the information provided depends on what the Issuer has declared in the Scheme TSP.

For PCI Tokens, only "basic" information related to the card is provided:

• Card last digits.

• Card expiry date.

• Card Scheme if recognized.

Parámetros de ruta

tokenIdstring · máx: 128Requerido

The token identifier.

Parámetros de encabezado

authorizationstring · mín: 1 · máx: 512Requerido

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · mín: 1 · máx: 36Requerido

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Respuestas

200

OK

application/json

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

Identifier of the merchant provided by Thales at on-boarding.

cardBinstring · mín: 6 · máx: 8Opcional

The card bin returned by the scheme, just available for VISA and Mastercard SCOF.

Example: 453421

cardLastDigitsstring · máx: 5Opcional

The card last digits.

Example: 2366

cardExpiryDatestring · máx: 4Opcional

The card expiry date in format MMYY.

Example: 0420

tokenStatestring · enum · máx: 64Requerido

Token state.
PCI token state can only be 'ACTIVE' or 'DELETED'.

Example: ACTIVEValores posibles:

tokenLastDigitsstring · máx: 5Opcional

The token last digits.

Example: 5589

tokenExpiryDatestring · máx: 4Opcional

The token expiry date in format MMYY. This information can be missing. It is intended for display only at this step.
Rely on token expiry date in create transaction response for storage.

Example: 1022

parstring · máx: 29Opcional

Payment Account Reference returned by the Scheme TSP.

Example: 5001a9f027e5629d11e3949a0800a

vProvisionedTokenIdstring · mín: 1 · máx: 36Opcional

Specific to Visa. Another token identifier that shall be used only with Visa Cloud Token Framework.

deviceBindingsstring[]Opcional

The list of device identifiers bound to the token.

creationTimestampstring · máx: 64Requerido

Token creation timestamp compliant with ISO 8601.

Example: 2025-11-10T09:08:24.479Z

lastUpdateTimestampstring · máx: 64Opcional

Token last update timestamp compliant with ISO 8601. Provided only in case the token was updated after its creation.

Example: 2025-11-13T11:012:41.165Z

400

Bad request - Not Retryable

401

Unauthorized - Not Retryable

404

Not Found - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

get

/tokens/{tokenId}

HTTPcURLJavaScriptPython

GET /tsh-cof/tokens/{tokenId} HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Accept: */*

{
  "tokenState": "ACTIVE",
  "creationTimestamp": "2025-11-10T09:08:24.479Z",
  "merchantId": "30088894-9c92-41fb-83b0-46a514c9f3c0",
  "cardBin": "554312",
  "cardLastDigits": "2366",
  "cardExpiryDate": "0426",
  "tokenLastDigits": "5589",
  "tokenExpiryDate": "1036",
  "par": "5001a9f027e5629d11e3949a0800a",
  "vProvisionedTokenId": "ctf-12354658979-55",
  "cardProduct": {
    "cardType": "DEBIT",
    "scheme": "MASTERCARD",
    "issuerName": "Bank Name",
    "cardDescription": "The card description.",
    "cardArts": {
      "foregroundColor": "7FB8C8",
      "backgroundColor": "7FB8C9",
      "cardBackgroundImageId": "2ee5c858-a6a4-43f1-a503-ffde6c41fad9",
      "issuerLogoId": "1fd8594c-5284-4aeb-bb73-6129c1d6cdb2",
      "brandLogoId": "623046b7-4a8f-4550-bca8-45b38c9498a3",
      "cobrandLogoId": "5548eb95-3aee-4bb8-9abf-38a7ab2c1cf3",
      "completeCardImageId": "15ac4371-dcb9-4310-867e-b12338970276",
      "cardIconId": "14e3044fa-949e-4900-800f-88b8fc6cc3d5"
    },
    "termsAndConditionsUrl": "https://bank.com/tncs.html",
    "privacyPolicyUrl": "https://bank.com/privacyPolicy.html"
  },
  "lastUpdateTimestamp": "2025-11-13T09:09:52.254Z"
}

Delete Token

delete

Delete a token.

Parámetros de ruta

tokenIdstring · máx: 128Requerido

The token identifier.

Parámetros de encabezado

authorizationstring · mín: 1 · máx: 512Requerido

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · mín: 1 · máx: 36Requerido

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Respuestas

204

No Content

400

Bad request - Not Retryable

401

Unauthorized - Not Retryable

404

Not Found - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

delete

/tokens/{tokenId}

HTTPcURLJavaScriptPython

DELETE /tsh-cof/tokens/{tokenId} HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Accept: */*

Sin contenido

Get Asset

get

Returns an asset ressource (image, text). The assetId associated to an asset never changes so the response can be cached by the API consumer.

Parámetros de ruta

assetIdstring · máx: 128Requerido

The unique asset identifier.

Parámetros de encabezado

authorizationstring · mín: 1 · máx: 512Requerido

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

Respuestas

200

OK

application/json

mediaTypestring · enum · máx: 64Requerido

The media type of the asset.

Valores posibles:

encodedDatastringRequerido

The asset encoded in base64.

heightstring · máx: 10Opcional

The asset height specified in pixels.

widthstring · máx: 10Opcional

The asset width specified in pixels.

400

Bad request - Not Retryable

401

Unauthorized - Not Retryable

404

Not Found - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

get

/assets/{assetId}

HTTPcURLJavaScriptPython

GET /tsh-cof/assets/{assetId} HTTP/1.1
Host: thales.api.com
authorization: text
Accept: */*

{
  "mediaType": "image/png",
  "encodedData": "4Q3iRXhpZgAATU0AKgAAAAgABwESAAMAAAAB....TBIiw3Yu73+edWQ1+TquKs2wJdir//2Q=="
}