> 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/classic-tokenization/es/referencia-de-la-api-tarjetas-de-doble-marca/referencia-de-la-api-tarjetas-de-doble-marca/saliente-al-emisor.md). # Saliente (al emisor) ## notify issuer about any virtual card (token) change > This method is used by TSH to notify issuer in case a virtual card has been updated due to:\ > \- state change (activated/suspended/resumed/deleted)\ > \- belonging card updated ```json {"openapi":"3.1.1","info":{"title":"Gemalto TSH Issuer Gateway Auxiliary API","version":"1.4.3"},"tags":[{"name":"Notify Virtual Card Change"}],"servers":[{"url":"https://issuer.host.com/issuer/igwauxapi"}],"paths":{"/notifyVirtualCardChange":{"post":{"summary":"notify issuer about any virtual card (token) change","description":"This method is used by TSH to notify issuer in case a virtual card has been updated due to:\n- state change (activated/suspended/resumed/deleted)\n- belonging card updated","operationId":"notifyVirtualCardChange","parameters":[{"$ref":"#/components/parameters/x-correlation-id-header"},{"$ref":"#/components/parameters/x-issuer-id-header"}],"responses":{"200":{"description":"Successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter","content":{"application/json":{"schema":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description|\n|-------|-------|\n|911|Operation failed|\n|921|Unexpected server error|\n"},"errorMessage":{"maxLength":256,"type":"string","description":"Textual error message"}}}}}},"500":{"description":"Internal Server Error"}},"tags":["Notify Virtual Card Change"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/notifyVirtualCardChangeReq"}}},"description":"notifyVirtualCardChange request payload","required":true}}}},"components":{"parameters":{},"schemas":{"notifyVirtualCardChangeReq":{"type":"object","properties":{"issuerCardRefId":{"$ref":"#/components/schemas/issuerCardRefId"},"virtualCardId":{"$ref":"#/components/schemas/virtualCardId"},"walletProviderId":{"$ref":"#/components/schemas/walletProviderId"},"walletCardRefId":{"$ref":"#/components/schemas/walletCardRefId"},"walletVirtualCardId":{"type":"string","description":"Wallet virtual card identifier.
For ApplePay, it corresponds to the auxiliary DPANID.","minLength":1,"maxLength":128},"primaryWalletVirtualCardId":{"type":"string","description":"Primary wallet virtual card identifier.
For ApplePay, it corresponds to the primary DPANID.","minLength":1,"maxLength":128},"tokenStorageId":{"$ref":"#/components/schemas/tokenStorageId"},"isPrimary":{"type":"boolean","description":"It is a boolean information that inform if the virtual card is a primary virtual card or if it is an auxiliary virtual card.\nAlways set to false in this API."},"action":{"type":"string","description":"This corresponds to the action performed on the token\n\nHere are the possible values:\n- ACTIVATE: When the virtual card is activated after provisioning.\n- SUSPEND: When the active virtual card is suspended.\n- RESUME: When the suspended virtual card is re-activated.\n- DELETE: When the virtual card deleted.\n- UPDATE: When the funding PAN value is updated (ex: card renewal).\n- ERASE: When a virtual card is erased following a GDPR action.","maxLength":128,"enum":["ACTIVATE","SUSPEND","RESUME","DELETE","UPDATE","ERASE"]},"tokenInfo":{"type":"string","maxLength":8196,"minLength":1,"description":"Token information in JSON.\nThis field is conditional to the TSP and provided only during enrolment.\n\nThis value is encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:
\n* The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.\n* 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.
\nThe key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
\nIt is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new issuers.\n* The encryption result is then encoded using base64.
\n* The public key length in the certificate can be 2048-bit or 4096-bit.\n\n\nOnce deciphered, the cardInfo contains the following information:
\n\n|JSON field parameter name |description|MOC|Length|\n|--------------------------|------------|----|-------|\n|pan |The token PAN.|M|Up to 19|\n|exp |The expiry date in the format MMYY.|M|4|\n"},"publicKeyIdentifier":{"type":"string","maxLength":32,"minLength":1,"description":"Identifier of the key used to encrypt tokenInfo.
Provided by Issuer to Thales during onboarding."},"errorCode":{"type":"number","description":"Error code provided in case of operation failure initiated by the issuer
\n|reason code |description|\n|------------|-----------|\n|113 |Unknown issuer|\n|115 |Unknown product|\n|119 |Unknown Token|\n|221 |The device was not reachable after retries|\n|322 |Time to live of the operation expired|\n|911 |Operation failed|\n|921 |Unexpected error|\n\nThis list is not exhaustive. Error codes not listed shall be considered as a generic error."},"source":{"type":"string","description":"The source actor that initiated the state change","maxLength":32,"enum":["WALLET","ISSUER"]}},"required":["issuerCardRefId","virtualCardId","walletProviderId","tokenStorageId","isPrimary","source"]},"issuerCardRefId":{"type":"string","maxLength":48,"description":"The unique identifier of the funding card.
This value is generated and managed by the issuer.
This value can be updated in case of funding PAN replacement by the issuer."},"virtualCardId":{"description":"Unique identifier of the virtual card","type":"string","maxLength":64,"minLength":1},"walletProviderId":{"type":"string","description":"Wallet Provider identifier, defined by Thales:\n\n|walletProviderId|Description|\n|-------|-------|\n|APPLE_PAY|Apple Pay Wallet|\n|ANDROID_PAY|Google Pay Wallet|\n|SPAYHCE|Samsung Pay Wallet|\n","minLength":1,"maxLength":128},"walletCardRefId":{"type":"string","description":"Card unique identifier defined by the Wallet Provider or the primary TSP.
For ApplePay, it corresponds to the FPANID.
\nFor Fidesmo/Digiseq, it corresponds to the card identifier provided by the primary TSP.","minLength":1,"maxLength":128},"tokenStorageId":{"type":"string","description":"Unique token storage identifier","minLength":1,"maxLength":128}}}} ``` ## check if Issuer is healthy > This method is used by TSH to monitor Issuer health ```json {"openapi":"3.1.1","info":{"title":"Gemalto TSH Issuer Gateway Auxiliary API","version":"1.4.3"},"tags":[{"name":"Health Check"}],"servers":[{"url":"https://issuer.host.com/issuer/igwauxapi"}],"paths":{"/healthCheck":{"get":{"summary":"check if Issuer is healthy","description":"This method is used by TSH to monitor Issuer health","operationId":"healthCheck","parameters":[{"$ref":"#/components/parameters/x-correlation-id-header"},{"$ref":"#/components/parameters/x-issuer-id-header"}],"responses":{"204":{"description":"Successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter"},"500":{"description":"Internal Server Error"}},"tags":["Health Check"]}}},"components":{"parameters":{}}} ``` ## request cobadge card digitization to the Issuer > This method is used by TSH exclusively to request the digitization of a cobadge card.\ > \ > \*\*TSH will provide either cipheredCardInfo or (exclusive) cipheredTokenInfo or (exclusive) issuerCardRefId\*\*, depending on inputs from the Wallet provider.\ > \ > The Issuer can still approve or reject the request. But the latter case will mostly happen in some limit, error cases, since the Wallet Provider will always trigger the cobadge digitization flow only in the case the digitization on the primary flow is approved.\ > \ > In some exceptional error case scenarios that involve a retry from the end user or the Wallet Provider, the Issuer shall expect to receive the same request several times. Only the latest request has to be taken into account.
````json {"openapi":"3.1.1","info":{"title":"Gemalto TSH Issuer Gateway Auxiliary API","version":"1.4.3"},"tags":[{"name":"Request Cobadge Card Digitization"}],"servers":[{"url":"https://issuer.host.com/issuer/igwauxapi"}],"paths":{"/requestCoBadgeDigitization":{"post":{"responses":{"200":{"description":"requestCoBadgeDigitization response payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/requestCoBadgeDigitizationRes"}}}},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter","content":{"application/json":{"schema":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description|\n|-------|-------|\n|111|Missing mandatory parameter|\n|112|Bad parameter format|\n|116|Unknown Card|158|Card is expired|\n|159|Card is supended|\n|161|Invalid CVV2|\n|166|Invalid FPAN|\n|911|Operation failed|\n|921|Unexpected server error|"},"errorMessage":{"maxLength":256,"type":"string","description":"Textual error message"}}}}}},"500":{"description":"Internal Server Error"}},"summary":"request cobadge card digitization to the Issuer","description":"This method is used by TSH exclusively to request the digitization of a cobadge card.\n\n**TSH will provide either cipheredCardInfo or (exclusive) cipheredTokenInfo or (exclusive) issuerCardRefId**, depending on inputs from the Wallet provider.\n\nThe Issuer can still approve or reject the request. But the latter case will mostly happen in some limit, error cases, since the Wallet Provider will always trigger the cobadge digitization flow only in the case the digitization on the primary flow is approved.\n\nIn some exceptional error case scenarios that involve a retry from the end user or the Wallet Provider, the Issuer shall expect to receive the same request several times. Only the latest request has to be taken into account.\n","operationId":"requestCoBadgeDigitization","parameters":[{"schema":{"type":"string","maxLength":64,"minLength":1},"in":"header","name":"x-correlation-id","description":"Unique identifier of a give session (enrolment session , Life Cycle Management session and other operation), used to link inbound and outbound **requests** of the same session together
","required":true},{"schema":{"type":"string","maxLength":10,"minLength":10},"in":"header","name":"x-issuer-id","description":"Unique identifier used to identify the issuer","required":true}],"tags":["Request Cobadge Card Digitization"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/requestCoBadgeDigitizationReq"}}},"description":"requestCoBadgeDigitization request payload"}}}},"components":{"schemas":{"requestCoBadgeDigitizationRes":{"type":"object","properties":{"issuerCardRefId":{"$ref":"#/components/schemas/issuerCardRefId"},"paymentAccountReference":{"$ref":"#/components/schemas/paymentAccountReference"},"cipheredDomesticCard":{"$ref":"#/components/schemas/cipheredDomesticCard"},"publicKeyIdentifier":{"type":"string","minLength":1,"maxLength":32,"description":"Identifier of the key used to encrypt cipheredDomesticCard.
Provided by Thales to Issuer during onboarding."}},"required":["issuerCardRefId"]},"issuerCardRefId":{"type":"string","maxLength":48,"description":"The unique identifier of the funding card.
This value is generated and managed by the issuer.
This value can be updated in case of funding PAN replacement by the issuer."},"paymentAccountReference":{"type":"string","description":"The payment account reference value to associate with the token.
The usage of this optional field depends on the solution and the personalization profile.","minLength":58,"maxLength":58},"cipheredDomesticCard":{"maxLength":8196,"minLength":1,"type":"string","description":"The domestic card information in JSON, encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:
\n* The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.\n* 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.
\nThe key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
\nIt is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new issuers.\n* The encryption result is then encoded using base64.
\n* The public key length in the certificate can be 2048-bit or 4096-bit.\n\nOnce deciphered, the payload shall contain the following information:
\n\n|JSON field parameter name |description |MOC |Length |\n|--------------------------|------------|----|-------|\n|fpan |The domestic funding pan to digitize |M |Up to 19 |\n|exp |The expiry date in the format MMYY |O |4 | \n\n
\n\n**Examples:**\n``` javascript \n {\n \"fpan\":\"1234567891234567\",\n \"exp\":\"1228\",\n}\n"},"requestCoBadgeDigitizationReq":{"type":"object","properties":{"cipheredCardInfo":{"$ref":"#/components/schemas/cipheredCardInfo"},"cipheredTokenInfo":{"$ref":"#/components/schemas/cipheredTokenInfo"},"publicKeyIdentifier":{"type":"string","maxLength":32,"minLength":1,"description":"Identifier of the key used to encrypt cipheredCardInfo.
Provided by Issuer to Thales during onboarding."},"issuerCardRefId":{"$ref":"#/components/schemas/issuerCardRefId"},"walletProviderId":{"$ref":"#/components/schemas/walletProviderId"},"walletCardRefId":{"$ref":"#/components/schemas/walletCardRefId"},"deviceInformation":{"$ref":"#/components/schemas/deviceInformation"}},"required":["walletProviderId","deviceInformation"]},"cipheredCardInfo":{"maxLength":8196,"minLength":1,"type":"string","description":"The card information in JSON, encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:
\n* The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.\n* 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.
\nThe key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
\nIt is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new issuers.\n* The encryption result is then encoded using base64.
\n* The public key length in the certificate can be 2048-bit or 4096-bit.\n\nOnce deciphered, the cardInfo contains the following information:
\n\n|JSON field parameter name |description |MOC |Length |\n|--------------------------|------------|----|-------|\n|fpan |The funding pan to digitize |M |Up to 19 |\n|exp |The expiry date in the format MMYY |O |4 |\n|cvv |Depending of the OEM and scheme, this value is provided or not |O |3 or 4 |\n\n
\n\n**Examples:**\n\n``` javascript\n Example 1\n {\n \"fpan\":\"1234567891234567\",\n \"exp\":\"1218\",\n }\n\n Example 2\n {\n \"fpan\":\"1234567891234567\",\n \"exp\":\"1218\",\n \"cvv\":\"765\"\n }\n"},"cipheredTokenInfo":{"maxLength":8196,"minLength":1,"type":"string","description":"The encrypted data contains the original token information used with primary TSP (Token for Token provisioning).\n
This is only applicable for **HCE Wallet**.\n
\n
\nThe original token information in JSON is encrypted using the PKCS#7 encryption. See encryption of **cipheredCardInfo** for more details.\n
\n
\nOnce deciphered the tokenInfo contains the following information:
\n
\n
\n|JSON field parameter name |description |MOC |Length|\n|--------------------------|------------|----|-------|\n|originalTokenRequestorId |Token Requestor Identifier of the original token provided and allocated by Scheme TSP |O |Up to 11 |\n|originalTokenId | The original token identifier as defined by the Scheme TSP.
For VISA (VTS) it corresponds to **vProvisionedTokenID**
Mandatory if originalToken is not provided. |C |Up to 64 |\n|originalToken |The original token used to request the digitization with primary TSP
Mandatory if originalTokenId is not provided. |C |Up to 19 |\n"},"walletProviderId":{"type":"string","description":"Wallet Provider identifier, defined by Thales:\n\n|walletProviderId|Description|\n|-------|-------|\n|APPLE_PAY|Apple Pay Wallet|\n|ANDROID_PAY|Google Pay Wallet|\n|SPAYHCE|Samsung Pay Wallet|\n","minLength":1,"maxLength":128},"walletCardRefId":{"type":"string","description":"Card unique identifier defined by the Wallet Provider or the primary TSP.
For ApplePay, it corresponds to the FPANID.
\nFor Fidesmo/Digiseq, it corresponds to the card identifier provided by the primary TSP.","minLength":1,"maxLength":128},"deviceInformation":{"type":"object","properties":{"tokenStorageId":{"$ref":"#/components/schemas/tokenStorageId"},"tokenStorageType":{"$ref":"#/components/schemas/tokenStorageType"}},"required":["tokenStorageId"]},"tokenStorageId":{"type":"string","description":"Unique token storage identifier","minLength":1,"maxLength":128},"tokenStorageType":{"type":"string","description":"Identifies the type of token storage location, possible values are: \nThis list may evolve in the future.","maxLength":32}}}} ```` --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.payments.thalescloud.io/classic-tokenization/es/referencia-de-la-api-tarjetas-de-doble-marca/referencia-de-la-api-tarjetas-de-doble-marca/saliente-al-emisor.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.