> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/merchant-tokenization/ja/bakkuendo/apis/client-api/token-management.md).
# Token Management
## Notify Token Creation
> Notify the token requestor about a token creation.\
> \
> The notification shares the same 'x-correlation-id' as in the create token request.\
> \
> If the tokenization failed, the notification only contains information about the error. No token data is provided.\
> \
> In case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff.
```json
{"openapi":"3.1.1","info":{"title":"Thales COF Client API","version":"1.42"},"tags":[{"name":"Token Management"}],"servers":[{"url":"/tsh-cof"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"tokenId":{"type":"string","description":"The token identifier.","minLength":1,"maxLength":128},"merchantId":{"type":"string","description":"Identifier of the merchant provided by Thales at on-boarding.","minLength":1,"maxLength":128},"cardBin":{"type":"string","description":"The card bin returned by the scheme, just available for VISA and Mastercard SCOF.","minLength":6,"maxLength":8},"cardLastDigits":{"type":"string","maxLength":5,"description":"The card last digits."},"cardExpiryDate":{"type":"string","maxLength":4,"description":"The card expiry date in format MMYY."},"tokenLastDigits":{"type":"string","maxLength":5,"description":"The token last digits."},"tokenExpiryDate":{"type":"string","maxLength":4,"description":"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."},"par":{"type":"string","maxLength":29,"description":"Payment Account Reference returned by the Scheme TSP."},"vProvisionedTokenId":{"type":"string","description":"Specific to Visa. Another token identifier that shall be used only with Visa Cloud Token Framework.","minLength":1,"maxLength":36},"cardProduct":{"type":"object","description":"Information about the card product.","required":["cardType","scheme"],"properties":{"issuerName":{"$ref":"#/components/schemas/issuerName"},"cardType":{"$ref":"#/components/schemas/cardType"},"scheme":{"$ref":"#/components/schemas/scheme"},"supportVisaCTF":{"$ref":"#/components/schemas/supportVisaCTF"},"cardDescription":{"$ref":"#/components/schemas/cardDescription"},"cardArts":{"$ref":"#/components/schemas/cardArts"},"termsAndConditionsUrl":{"$ref":"#/components/schemas/termsAndConditionsUrl"},"privacyPolicyUrl":{"$ref":"#/components/schemas/privacyPolicyUrl"}}},"issuerName":{"type":"string","maxLength":128,"description":"The card issuer name."},"cardType":{"type":"string","description":"The card type.","maxLength":32,"enum":["CREDIT","DEBIT","PREPAID","UNKNOWN"]},"scheme":{"type":"string","description":"The card primary scheme.","maxLength":32,"enum":["MASTERCARD","VISA","AMEX","DISCOVER","ELO"]},"supportVisaCTF":{"type":"boolean","description":"Indicate if Visa Cloud Token Framework is available."},"cardDescription":{"type":"string","maxLength":256,"description":"The card description."},"cardArts":{"type":"object","properties":{"foregroundColor":{"type":"string","maxLength":6,"description":"Color used for the text displayed on the card (last digits, expiry date). Hexadecimal RGB color format."},"backgroundColor":{"type":"string","maxLength":6,"description":"Color used for card background. Hexadecimal RGB color format."},"cardBackgroundImageId":{"type":"string","maxLength":128,"description":"Asset identifier of the card background image. It doesn't contain the issuer/brand/co-brand logo."},"issuerLogoId":{"type":"string","maxLength":128,"description":"Asset identifier of the issuer logo."},"brandLogoId":{"type":"string","maxLength":128,"description":"Asset identifier of the primary brand logo."},"cobrandLogoId":{"type":"string","maxLength":128,"description":"Asset identifier of the cobrand logo."},"completeCardImageId":{"type":"string","maxLength":128,"description":"Asset identifier of the complete card image. Shall be preferred over the other assets when present."},"cardIconId":{"type":"string","maxLength":128,"description":"Asset identifier of the card icon."},"cardImageUrl":{"type":"string","maxLength":512,"description":"HTTP location of the card image. If present, no other identifier is provided and getAsset operation is not needed."}}},"termsAndConditionsUrl":{"type":"string","maxLength":512,"description":"Card issuer terms and conditions URL."},"privacyPolicyUrl":{"type":"string","maxLength":512,"description":"Card issuer privacy policy URL."},"error":{"type":"object","description":"Information about the error in case the token is not created.","properties":{"errorCode":{"type":"string","maxLength":128,"description":"The error code as specified in below table.\n\n-----------------\n|Error Code|Description|\n|-------|-------|\n|NON_RETRYABLE_ERROR|Generic code for all non retryable errors returned by the TMG.|\n|RETRYABLE_ERROR|Generic code for all retryable errors returned by the TMG.|\n|TSP_NON_RETRYABLE_ERROR|Generic code for all non retryable errors returned by the TSP.|\n|TSP_RETRYABLE_ERROR|Generic code for all retryable errors returned by the TSP.|\n|TSP_ABORTED|The TSP aborted the token creation process.|\n|INVALID_PAN_DATA|The PAN data is invalid.|\n|PAN_NOT_ELIGIBLE|The Issuer considers the PAN as not eligible for tokenization.|\n|ISSUER_DECLINED|The Issuer declined the tokenization.|\n|EXPIRED|The session timeout expired.|\n-----------------"},"errorDetails":{"type":"string","maxLength":256,"description":"Additional information about the error. This optional parameter has no specific format as it depends on the different TSP API. It is sent for logging and troubleshooting purpose."}},"required":["errorCode"]},"creationTimestamp":{"type":"string","maxLength":64,"description":"Token or binding creation timestamp compliant with ISO 8601."}}},"paths":{"/notify-token-creation":{"post":{"description":"Notify the token requestor about a token creation.\n\nThe notification shares the same 'x-correlation-id' as in the create token request.\n\nIf the tokenization failed, the notification only contains information about the error. No token data is provided.\n\nIn case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff. ","operationId":"notifyTokenCreation","parameters":[{"schema":{},"$ref":"#/parameters/authorization"},{"schema":{},"$ref":"#/parameters/xCorrelationId"}],"responses":{"204":{"$ref":"#/responses/204"},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"404":{"$ref":"#/responses/404"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}},"tags":["Token Management"],"summary":"Notify Token Creation","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["merchantId"],"properties":{"tokenId":{"$ref":"#/components/schemas/tokenId"},"merchantId":{"$ref":"#/components/schemas/merchantId"},"cardBin":{"$ref":"#/components/schemas/cardBin"},"cardLastDigits":{"$ref":"#/components/schemas/cardLastDigits"},"cardExpiryDate":{"$ref":"#/components/schemas/cardExpiryDate"},"tokenLastDigits":{"$ref":"#/components/schemas/tokenLastDigits"},"tokenExpiryDate":{"$ref":"#/components/schemas/tokenExpiryDate"},"par":{"$ref":"#/components/schemas/par"},"vProvisionedTokenId":{"$ref":"#/components/schemas/vProvisionedTokenId"},"cardProduct":{"$ref":"#/components/schemas/cardProduct"},"error":{"$ref":"#/components/schemas/error"},"creationTimestamp":{"$ref":"#/components/schemas/creationTimestamp"}}}}}}}}},"parameters":{"authorization":{"in":"header","description":"Technical identifier pre-defined at on-boarding that identifies the API\nconsumer.\nFormat shall be the string 'APIKEY' followed by a space and the\napi key value.\n Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b\n","name":"authorization","required":true,"type":"string","minLength":1,"maxLength":512},"xCorrelationId":{"in":"header","description":"A unique message identifier. It eventually correlates the notification with a request if any. The goal is to help on customer support when needed. ","name":"x-correlation-id","required":true,"type":"string","minLength":1,"maxLength":36}},"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request - Not Retryable"},"401":{"description":"Unauthorized - Not Retryable"},"404":{"description":"Not Found - Not Retryable"},"429":{"description":"Too Many Requests - Retryable"},"500":{"description":"Internal Server Error - Retryable"},"503":{"description":"Service Unavailable - Retryable"}}}
```
## Notify Token Update
> Notify the token requestor about a network token update. \
> \
> In case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff. \
> \
> In case of error and retry, all the notifications regarding a token may not be sent in correct order. The parameter 'lastUpdateTimestamp' shall be used to discard obsolete notifications.\
> \
> Most of the time, the TMG sends all the information it has for the token. But there are some edge error cases for which only the 'tokenId' and the 'tokenState' are sent.
```json
{"openapi":"3.1.1","info":{"title":"Thales COF Client API","version":"1.42"},"tags":[{"name":"Token Management"}],"servers":[{"url":"/tsh-cof"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"tokenId":{"type":"string","description":"The token identifier.","minLength":1,"maxLength":128},"merchantId":{"type":"string","description":"Identifier of the merchant provided by Thales at on-boarding.","minLength":1,"maxLength":128},"tokenState":{"type":"string","maxLength":64,"description":"Token state.PCI token state can only be 'ACTIVE' or 'DELETED'.","enum":["ACTIVE","SUSPENDED","DELETED"]},"cardBin":{"type":"string","description":"The card bin returned by the scheme, just available for VISA and Mastercard SCOF.","minLength":6,"maxLength":8},"cardLastDigits":{"type":"string","maxLength":5,"description":"The card last digits."},"cardExpiryDate":{"type":"string","maxLength":4,"description":"The card expiry date in format MMYY."},"tokenLastDigits":{"type":"string","maxLength":5,"description":"The token last digits."},"tokenExpiryDate":{"type":"string","maxLength":4,"description":"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."},"par":{"type":"string","maxLength":29,"description":"Payment Account Reference returned by the Scheme TSP."},"vProvisionedTokenId":{"type":"string","description":"Specific to Visa. Another token identifier that shall be used only with Visa Cloud Token Framework.","minLength":1,"maxLength":36},"deviceBindings":{"type":"array","description":"The list of device identifiers bound to the token as per Visa Cloud Token Framework.","items":{"$ref":"#/components/schemas/deviceId"},"uniqueItems":true},"deviceId":{"type":"string","description":"The unique device identifier.","minLength":1,"maxLength":24},"discardCryptogram":{"type":"boolean","description":"If present and set to 'true', all pre-fetched cryptograms linked to the token shall be discarded as they are no more valid due to the token update.","default":false},"cardProduct":{"type":"object","description":"Information about the card product.","required":["cardType","scheme"],"properties":{"issuerName":{"$ref":"#/components/schemas/issuerName"},"cardType":{"$ref":"#/components/schemas/cardType"},"scheme":{"$ref":"#/components/schemas/scheme"},"supportVisaCTF":{"$ref":"#/components/schemas/supportVisaCTF"},"cardDescription":{"$ref":"#/components/schemas/cardDescription"},"cardArts":{"$ref":"#/components/schemas/cardArts"},"termsAndConditionsUrl":{"$ref":"#/components/schemas/termsAndConditionsUrl"},"privacyPolicyUrl":{"$ref":"#/components/schemas/privacyPolicyUrl"}}},"issuerName":{"type":"string","maxLength":128,"description":"The card issuer name."},"cardType":{"type":"string","description":"The card type.","maxLength":32,"enum":["CREDIT","DEBIT","PREPAID","UNKNOWN"]},"scheme":{"type":"string","description":"The card primary scheme.","maxLength":32,"enum":["MASTERCARD","VISA","AMEX","DISCOVER","ELO"]},"supportVisaCTF":{"type":"boolean","description":"Indicate if Visa Cloud Token Framework is available."},"cardDescription":{"type":"string","maxLength":256,"description":"The card description."},"cardArts":{"type":"object","properties":{"foregroundColor":{"type":"string","maxLength":6,"description":"Color used for the text displayed on the card (last digits, expiry date). Hexadecimal RGB color format."},"backgroundColor":{"type":"string","maxLength":6,"description":"Color used for card background. Hexadecimal RGB color format."},"cardBackgroundImageId":{"type":"string","maxLength":128,"description":"Asset identifier of the card background image. It doesn't contain the issuer/brand/co-brand logo."},"issuerLogoId":{"type":"string","maxLength":128,"description":"Asset identifier of the issuer logo."},"brandLogoId":{"type":"string","maxLength":128,"description":"Asset identifier of the primary brand logo."},"cobrandLogoId":{"type":"string","maxLength":128,"description":"Asset identifier of the cobrand logo."},"completeCardImageId":{"type":"string","maxLength":128,"description":"Asset identifier of the complete card image. Shall be preferred over the other assets when present."},"cardIconId":{"type":"string","maxLength":128,"description":"Asset identifier of the card icon."},"cardImageUrl":{"type":"string","maxLength":512,"description":"HTTP location of the card image. If present, no other identifier is provided and getAsset operation is not needed."}}},"termsAndConditionsUrl":{"type":"string","maxLength":512,"description":"Card issuer terms and conditions URL."},"privacyPolicyUrl":{"type":"string","maxLength":512,"description":"Card issuer privacy policy URL."},"creationTimestamp":{"type":"string","maxLength":64,"description":"Token or binding creation timestamp compliant with ISO 8601."},"lastUpdateTimestamp":{"type":"string","maxLength":64,"description":"Token or binding last update timestamp compliant with ISO 8601."}}},"paths":{"/notify-token-update":{"post":{"description":"Notify the token requestor about a network token update. \n\nIn case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff. \n\nIn case of error and retry, all the notifications regarding a token may not be sent in correct order. The parameter 'lastUpdateTimestamp' shall be used to discard obsolete notifications.\n\nMost of the time, the TMG sends all the information it has for the token. But there are some edge error cases for which only the 'tokenId' and the 'tokenState' are sent.","operationId":"notifyTokenUpdate","parameters":[{"schema":{},"$ref":"#/parameters/authorization"},{"schema":{},"$ref":"#/parameters/xCorrelationId"}],"responses":{"204":{"$ref":"#/responses/204"},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"404":{"$ref":"#/responses/404"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}},"tags":["Token Management"],"summary":"Notify Token Update","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tokenId","merchantId"],"properties":{"tokenId":{"$ref":"#/components/schemas/tokenId"},"merchantId":{"$ref":"#/components/schemas/merchantId"},"tokenState":{"$ref":"#/components/schemas/tokenState"},"cardBin":{"$ref":"#/components/schemas/cardBin"},"cardLastDigits":{"$ref":"#/components/schemas/cardLastDigits"},"cardExpiryDate":{"$ref":"#/components/schemas/cardExpiryDate"},"tokenLastDigits":{"$ref":"#/components/schemas/tokenLastDigits"},"tokenExpiryDate":{"$ref":"#/components/schemas/tokenExpiryDate"},"par":{"$ref":"#/components/schemas/par"},"vProvisionedTokenId":{"$ref":"#/components/schemas/vProvisionedTokenId"},"deviceBindings":{"$ref":"#/components/schemas/deviceBindings"},"discardCryptogram":{"$ref":"#/components/schemas/discardCryptogram"},"cardProduct":{"$ref":"#/components/schemas/cardProduct"},"creationTimestamp":{"$ref":"#/components/schemas/creationTimestamp"},"lastUpdateTimestamp":{"$ref":"#/components/schemas/lastUpdateTimestamp"}}}}}}}}},"parameters":{"authorization":{"in":"header","description":"Technical identifier pre-defined at on-boarding that identifies the API\nconsumer.\nFormat shall be the string 'APIKEY' followed by a space and the\napi key value.\n Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b\n","name":"authorization","required":true,"type":"string","minLength":1,"maxLength":512},"xCorrelationId":{"in":"header","description":"A unique message identifier. It eventually correlates the notification with a request if any. The goal is to help on customer support when needed. ","name":"x-correlation-id","required":true,"type":"string","minLength":1,"maxLength":36}},"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request - Not Retryable"},"401":{"description":"Unauthorized - Not Retryable"},"404":{"description":"Not Found - Not Retryable"},"429":{"description":"Too Many Requests - Retryable"},"500":{"description":"Internal Server Error - Retryable"},"503":{"description":"Service Unavailable - Retryable"}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.payments.thalescloud.io/merchant-tokenization/ja/bakkuendo/apis/client-api/token-management.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.