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.

Header parameters

authorizationstring · min: 1 · max: 512Required

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 · min: 1 · max: 36Required

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.

Body

merchantIdstring · min: 1 · max: 128Required

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

encryptedDatastring · min: 1 · max: 8196Required

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":"john@doe.com"}

sourcestring · enum · max: 32Required

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

Possible values:

languagestring · min: 2 · max: 2Required

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

Default: enExample: en

countrystring · min: 2 · max: 2Required

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

Example: US

Responses

201

Created

application/json

tokenIdstring · min: 1 · max: 128Required

The token identifier.

Pattern: ^[a-zA-Z0-9_-]+$

cardBinstring · min: 6 · max: 8Optional

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

Example: 453421

cardLastDigitsstring · max: 5Optional

The card last digits.

Example: 2366

cardExpiryDatestring · max: 4Optional

The card expiry date in format MMYY.

Example: 0420

tokenLastDigitsstring · max: 5Optional

The token last digits.

Example: 5589

tokenExpiryDatestring · max: 4Optional

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

tokenStatestring · enum · max: 64Required

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

Example: ACTIVEPossible values:

parstring · max: 29Optional

Payment Account Reference returned by the Scheme TSP.

Example: 5001a9f027e5629d11e3949a0800a

vProvisionedTokenIdstring · min: 1 · max: 36Optional

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

colorstring · enum · max: 32Optional

Deprecated.

Example: GREENPossible values:

creationTimestampstring · max: 64Required

Token creation timestamp compliant with ISO 8601.

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

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

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.

Header parameters

authorizationstring · min: 1 · max: 512Required

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

Body

merchantIdstring · min: 1 · max: 128Required

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

encryptedDatastring · min: 1 · max: 8196Required

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":"john@doe.com"}

sourcestring · enum · max: 32Required

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

Possible values:

languagestring · min: 2 · max: 2Required

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

Default: enExample: en

countrystring · min: 2 · max: 2Required

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

Example: US

Responses

202

Accepted

No content

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

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

No content

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).

Header parameters

authorizationstring · min: 1 · max: 512Required

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

Body

merchantIdstring · min: 1 · max: 128Required

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

encryptedDatastring · min: 1 · max: 8196Required

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

Responses

201

Created

application/json

tokenIdstring · min: 1 · max: 128Required

The token identifier.

Pattern: ^[a-zA-Z0-9_-]+$

cardLastDigitsstring · max: 5Required

The card last digits.

Example: 2366

cardExpiryDatestring · max: 4Required

The card expiry date in format MMYY.

Example: 0420

tokenStatestring · enum · max: 64Required

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

Example: ACTIVEPossible values:

creationTimestampstring · max: 64Required

Token creation timestamp compliant with ISO 8601.

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

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

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).

Header parameters

authorizationstring · min: 1 · max: 512Required

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

Body

merchantIdstring · min: 1 · max: 128Required

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

pushProvisioningPayloadstring · min: 1 · max: 8196Required

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 · max: 32Required

The card primary scheme.

Example: MASTERCARDPossible values:

encryptedDatastring · min: 1 · max: 8196Optional

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":"john@doe.com"}

languagestring · min: 2 · max: 2Required

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

Default: enExample: en

countrystring · min: 2 · max: 2Required

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

Example: US

Responses

201

Created

application/json

tokenIdstring · min: 1 · max: 128Required

The token identifier.

Pattern: ^[a-zA-Z0-9_-]+$

cardLastDigitsstring · max: 5Optional

The card last digits.

Example: 2366

cardExpiryDatestring · max: 4Optional

The card expiry date in format MMYY.

Example: 0420

tokenLastDigitsstring · max: 5Optional

The token last digits.

Example: 5589

tokenExpiryDatestring · max: 4Optional

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

tokenStatestring · enum · max: 64Required

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

Example: ACTIVEPossible values:

parstring · max: 29Optional

Payment Account Reference returned by the Scheme TSP.

Example: 5001a9f027e5629d11e3949a0800a

encryptedDatastring · max: 8196Optional

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
name	The card holder name in format FIRSTNAME LASTNAME.	O	256
address.line1	The card holder address.	O	256
address.line2	The card holder address.	O	256
address.city	The card holder address.	O	256
address.countrySubdivision	The card holder address.	O	32
address.postalCode	The card holder address.	O	32
address.country	The Card holder country in ISO-3166-1 alpha-2 two-letter country code.	O	2
email	The card holder email.	O	128
phoneNumber	The card holder phone number.	O	128
personalId	A card holder personal identifier that may be required in some regions.	O	128

returnUriTypestring · enum · max: 32Optional

Issuer application/website URI type depending on the device. This parameter could be returned only for VISA.

Example: WEBPossible values:

returnUristring · max: 512Optional

Issuer application/website URI. This parameter could be returned only for VISA.

Example: https://bank.com/pushprovisioning.html

creationTimestampstring · max: 64Required

Token creation timestamp compliant with ISO 8601.

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

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

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.

Path parameters

tokenIdstring · max: 128Required

The token identifier.

Header parameters

authorizationstring · min: 1 · max: 512Required

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

Responses

200

application/json

merchantIdstring · min: 1 · max: 128Optional

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

cardBinstring · min: 6 · max: 8Optional

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

Example: 453421

cardLastDigitsstring · max: 5Optional

The card last digits.

Example: 2366

cardExpiryDatestring · max: 4Optional

The card expiry date in format MMYY.

Example: 0420

tokenStatestring · enum · max: 64Required

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

Example: ACTIVEPossible values:

tokenLastDigitsstring · max: 5Optional

The token last digits.

Example: 5589

tokenExpiryDatestring · max: 4Optional

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 · max: 29Optional

Payment Account Reference returned by the Scheme TSP.

Example: 5001a9f027e5629d11e3949a0800a

vProvisionedTokenIdstring · min: 1 · max: 36Optional

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

deviceBindingsstring[]Optional

The list of device identifiers bound to the token.

creationTimestampstring · max: 64Required

Token creation timestamp compliant with ISO 8601.

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

lastUpdateTimestampstring · max: 64Optional

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}

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.

Path parameters

tokenIdstring · max: 128Required

The token identifier.

Header parameters

authorizationstring · min: 1 · max: 512Required

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

Responses

204

No Content

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}

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

No content

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.

Path parameters

assetIdstring · max: 128Required

The unique asset identifier.

Header parameters

authorizationstring · min: 1 · max: 512Required

Responses

200

application/json

mediaTypestring · enum · max: 64Required

The media type of the asset.

Possible values:

encodedDatastringRequired

The asset encoded in base64.

heightstring · max: 10Optional

The asset height specified in pixels.

widthstring · max: 10Optional

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}

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

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

PreviousMerchant Onboarding NextToken Migration

Last updated 21 days ago

Was this helpful?