> 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/home/cloud-tsp-detokenization-api/appendix.md). # Appendix ## Appendix ### Token Assurance Method Codification Values are defined in the "Token Authorization Response" message in the *EMV Payment Tokenisation Specification Technical Framework v2.0*. | Category | Description | | -------- | ----------------------------------------------------------------------- | | Spaces | No Value Set | | `01–19` | Common method categories | | `00` | ID\&V Not Performed | | `01` | Non-Card Issuer Interactive Cardholder Authentication – 1 Factor | | `02` | Non-Card Issuer Interactive Cardholder Authentication – 2 Factor | | `03` | Non-Card Issuer Risk Oriented Non-Interactive Cardholder Authentication | | `04–09` | Reserved for future EMVCo use | | `10` | Card Issuer Account Verification | | `11` | Card Issuer Interactive Cardholder Authentication – 1 Factor | | `12` | Card Issuer Interactive Cardholder Authentication – 2 Factor | | `13` | Card Issuer Risk Oriented Non-Interactive Cardholder Authentication | | `14` | Card Issuer Asserted Authentication | | `15–19` | Reserved for future EMVCo use | | `20–89` | Token Programme Specific | | `90–99` | Reserved for future EMVCo use | *** ### Storage Type Attributes of the device used to identify the specific device where a Payment Token is stored. | Value | Description | | ----- | ----------------------------------- | | `01` | Device memory | | `02` | Device memory protected by TPM | | `03` | Server | | `04` | TEE | | `05` | SE | | `06` | Virtual execution environment (VEE) | *** ### Connectivity Requirements A secure channel must be established between the Cloud TSP and the remote Host (Acquirer server or Bank server). #### VPN A VPN (IPSEC) could be used with TLS Server Authentication, but this is not the recommended option. #### TLS Authentication (HTTPS) TLS shall be used to provide end-to-end encryption: * If VPN is used → TLS server authentication * If VPN is not used → TLS mutual authentication The full ISO payload is exchanged using HTTP Request/Response: **HTTP Request** (initiated by the remote host): * Method: `POST` * Content-Type: `x-www-form-urlencoded` * Body: full byte array ISO message, Base64 encoded **HTTP Response:** * Body: full byte array ISO message response, Base64 encoded * HTTP Status codes: * `200` – Cloud TSP successfully decoded and parsed the request; response contains the ISO message response * `4xx` – Cloud TSP failed to decode/parse ISO message; no ISO message present * `5xx` – Connection error; no ISO message present #### MAC Usage Usage of MAC is required in all ISO messages (Request and Response). See MAC Details. *** ### MAC Details The following principles shall be applied: * All ISO messages are protected using a MAC. * A new MAC key is generated for each ISO message. * The MAC key is protected using an Encryption key (Key Interchange). * Key Interchange is exchanged between each party, encrypted under a ZMK. * The ZMK (Zone Master Key) is exchanged during a key ceremony and imported into an HSM. #### Message Transformations The transformation is applied to the message before input to the MAC algorithm. Supported transformations: * SHA-256 *(default)* * SHA-1 *(available on request)* * None #### MAC Algorithms | Algorithm | Type | | -------------------- | ---- | | ISO 9797 Algorithm 3 | 3DES | | CMAC | AES | #### MAC Key Protection Alternatives | Alternative | | ------------------------- | | Triple DES CBC no-padding | | Triple DES ECB no-padding | | AES CBC no-padding | | AES ECB no-padding | #### Key Interchange KI (Key Interchange) is the encrypted key used to encrypt the ephemeral MAC Key. * KI is exchanged between parties during the setup phase, encrypted under ZMK and protected by HSM. * KI is identified by a key index (1 to 255) to allow key switchover (key renewal). * Key index is present in ISO messages in **Field 48** (identifier `001`). #### MAC Key A MAC key shall be present in each ISO message, encrypted under KI in **Field 48** (identifier `002`). * The MAC key is an ephemeral key generated by each party; it may be reused across several ISO messages. * Maximum recommended lifetime for an ephemeral MAC key: **1 hour**. #### MAC MAC shall be computed for each ISO message and is present in **Field 64**. Input data: SHA-256 hash of the full ISO payload (bytes), **excluding** the MAC value field (Field 64). > SHA-256 is used by default. SHA-1 can be used on request. #### Keys Type and Algorithms – 3DES | Parameter | Value | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | KI Key Type | "3 key" 3DES (24 bytes) or "2 key" 3DES (16 bytes)\* | | MAC Key Type | "2 key" 3DES (16 bytes) | | MAC Key Wrapping | 3DES using CBC or ECB | | MAC Algorithm | ISO 9797-1 Algorithm 3. Padding method 1: input data completed with `0`s until a multiple of 8-byte blocks. MAC = 8 leftmost bytes of output. | > \*KI key length depends on remote Host capability. #### Keys Type and Algorithms – AES | Parameter | Value | | ---------------- | ------------------------------------------------------------------------------------------- | | KI Key Type | AES (128, 192 or 256 bits) | | MAC Key Type | AES 128 bits | | MAC Key Wrapping | AES using CBC or ECB | | MAC Algorithm | AES-CMAC (RFC 4493), with AES-CMAC specification padding. MAC = 8 leftmost bytes of output. | *** ### Healthcheck Interface A healthcheck mechanism allows testing the peer-to-peer connectivity on a regular basis. On HTTP request to the dedicated URL, HTTP `200` is returned by the TSP while the service is up and running. Both HTTP `POST` and `GET` methods can be invoked. **URL:** ``` https:///gtotx/api/iso/healthCheck ``` *** ### ISO Interface ISO messages are carried over HTTP using the `POST` method. **URL:** ``` https:///gtotx/api/iso/v10/msg ``` *** ### ISO8583 Request/Response Examples #### Detokenization Request (1100) ``` MTI : 1100 BitMap : {2, 3, 4, 7, 14, 18, 19, 22, 23, 37, 42, 43, 48, 49, 55, 64} Field-2 : [603200*******1961] (PAN - PRIMARY ACCOUNT NUMBER) Field-3 : [000000] (PROCESSING CODE) Field-4 : [000000002100] (AMOUNT, TRANSACTION) Field-7 : [1017684135] (TRANSMISSION DATE AND TIME) Field-14 : [2809] (DATE, EXPIRATION) Field-18 : [1520] (MERCHANTS TYPE) Field-19 : [250] (ACQUIRING INSTITUTION COUNTRY CODE) Field-22 : [000] (POINT OF SERVICE ENTRY MODE) Field-23 : [000] (CARD SEQUENCE NUMBER) Field-37 : [539053756313] (RETRIEVAL REFERENCE NUMBER) Field-42 : [4992 ] (CARD ACCEPTOR IDENTIFICATION CODE) Field-43 : [BAX Test / /Paris /FR ] Field-48 : [00100210002032A9B4A1883D21FA3E19DBCDF174EB06B000501211AA22BB33CC] Field-49 : [978] (CURRENCY CODE, TRANSACTION) Field-55 : [9F0206000000002100...] (IC card system related data) Field-64 : [FA71C3422A48D361] (MESSAGE AUTHENTICATION CODE FIELD) ``` **Base64 encoded:** ``` b64Iso=[EQByBGYACGGCAREGAyABBIYgGWEAAAAAAAAAIQAQF2hBNSgJFSACUAAAAAA1MzkwNTM3NTYzMTM0OTkyICAgICAgICAgICBCQVggVGVzdCAgICAgICAgICAgICAgLyAgICAgL1BhcmlzICAgICAgICAgICAgICAgICAvRlIgQDAwMTAwMjEwMDAyMDMyQTlCNEExODgzRDIxRkEzRTE5REJDREYxNzRFQjA2QjAwMDUwMTIxMUFBMjJCQjMzQ0MJeGmfAgYAAAAAIQCfAwYAAAAAAAAfGgICUJUFAAAAAABfKgIJeJoDGAEJnAEAnzcEDwEOA4ICGoCfNgIAAZ8QIA+lAaCBAQAA8BCg+o6FJxMPAAAAAAAAAAAAAAAAAAAAnyYI+PQV6Iz2nvj6ccNCKkjTYQ==] ``` *** #### Detokenization Response (1110) ``` MTI : 1110 BitMap : {2, 14, 39, 48, 56, 64} Field-2 : [500050*******0053] (PAN - PRIMARY ACCOUNT NUMBER) Field-14 : [2303] (DATE, EXPIRATION) Field-39 : [000] (ACTION CODE) Field-48 : [00100210002032A9B4A1883D21FA3E19DBCDF174EB06B0] Field-56 : [0505434C4F5544060753504159484345] (Token Related Data) Field-64 : [BA0E969272027185] (MESSAGE AUTHENTICATION CODE FIELD) ``` **Base64 encoded:** ``` b64Iso=[ERBABAAAAgEBAREFAAUAFWAAAFMjAwAALjAwMTAwMjEwMDAyMDMyQTlCNEExODgzRDIxRkEzRTE5REJDREYxNzRFQjA2QjAQBQVDTE9VRAYHU1BBWUhDRboOlpJyAnGF] ``` *** #### Advice Request (1120) ``` MTI : 1120 Field-2 : [500050*******0053] (PAN - PRIMARY ACCOUNT NUMBER) Field-3 : [000000] (PROCESSING CODE) Field-4 : [000000000100] (AMOUNT, TRANSACTION) Field-7 : [1017684135] (TRANSMISSION DATE AND TIME) Field-14 : [2303] (DATE, EXPIRATION) Field-18 : [1520] (MERCHANTS TYPE) Field-19 : [250] (ACQUIRING INSTITUTION COUNTRY CODE) Field-22 : [000] (POINT OF SERVICE ENTRY MODE) Field-23 : [001] (CARD SEQUENCE NUMBER) Field-37 : [539053756313] (RETRIEVAL REFERENCE NUMBER) Field-39 : [000] (ACTION CODE) Field-42 : [4992 ] (CARD ACCEPTOR IDENTIFICATION CODE) Field-43 : [BAX Test / /Paris /FR ] Field-48 : [00100210002032A9B4A1883D21FA3E19DBCDF174EB06B000501211AA22BB33CC] Field-49 : [978] (CURRENCY CODE, TRANSACTION) Field-64 : [CD643CE4CE197782] (MESSAGE AUTHENTICATION CODE FIELD) ``` **Base64 encoded:** ``` b64Iso=[ESByBGYACmGAAREFAAUAFWAAAFMAAAAAAAAAAQAQF2hBNSMDFSACUAAAAAE1MzkwNTM3NTYzMTMAADQ5OTIgICAgICAgICAgIEJBWCBUZXN0ICAgICAgICAgICAgICAvICAgICAvUGFyaXMgICAgICAgICAgICAgICAgIC9GUiBAMDAxMDAyMTAwMDIwMzJBOUI0QTE4ODNEMjFGQTNFMTlEQkNERjE3NEVCMDZCMDAwNTAxMjExQUEyMkJCMzNDQwl4zWQ85M4Zd4I=] ``` *** #### Advice Response (1130) ``` MTI : 1130 BitMap : {2, 14, 39, 48, 64} Field-2 : [603200*******1961] (PAN - PRIMARY ACCOUNT NUMBER) Field-14 : [2809] (DATE, EXPIRATION) Field-39 : [000] (ACTION CODE) Field-48 : [00100210002032A9B4A1883D21FA3E19DBCDF174EB06B0] Field-64 : [42648CBBCC0A7E61] (MESSAGE AUTHENTICATION CODE FIELD) ``` **Base64 encoded:** ``` b64Iso=[ETBABAAAAgEAAREGAyABBIYgGWEoCQAALjAwMTAwMjEwMDAyMDMyQTlCNEExODgzRDIxRkEzRTE5REJDREYxNzRFQjA2QjBCZIy7zAp+YQ==] ``` --- # 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: ``` GET https://docs.payments.thalescloud.io/home/cloud-tsp-detokenization-api/appendix.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.