> 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/xpay-enablement/api-reference/tsp-api-v2/incoming-operations-from-tsp/transaction-notification-api.md).
# Transaction Notification API
[TSP-API-IN-v2-Transaction-Notification-oas2.yaml](https://openapi.gitbook.com/o/fwy1mtbRONGA2YDKDBr0/spec/TSP-API-IN-v2-Transaction-Notification-oas2.yaml)
## Submit token transaction details
> This method is used by TSP to send the detailed result of a transaction from a token
```json
{"openapi":"3.1.1","info":{"title":"Gemalto TSH Transaction Notification API","version":"2.2.2"},"tags":[{"name":"Token Transactions"}],"servers":[{"url":"https://api.dbp.thalescloud.io/tns-dispatcher/tsh/tnapi/v2.0"}],"paths":{"/token-transactions/{transactionId}":{"put":{"summary":"Submit token transaction details","description":"This method is used by TSP to send the detailed result of a transaction from a token","operationId":"notifyTokenTransaction","parameters":[{"$ref":"#/components/parameters/x-correlation-id-header"},{"$ref":"#/components/parameters/x-wallet-indicator-header"},{"$ref":"#/components/parameters/transactionIdPath"}],"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter. Possible error codes are 111, 112, 113, 119, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"description":"Internal Server Error"}},"tags":["Token Transactions"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/notifyTokenTransactionReq"}}},"description":"notifyTransaction request payload","required":true}}}},"components":{"parameters":{"transactionIdPath":{"schema":{"type":"string","maxLength":64,"minLength":1},"in":"path","required":true,"description":"Transaction identifier","name":"transactionId"}},"schemas":{"errorRes":{"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|113|Unknown issuer| \n|116|Unknown card|\n|119|Unknown Token|\n|911|Operation failed|\n|921|Unexpected server error|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"notifyTokenTransactionReq":{"type":"object","required":["issuerId","tokenId","transactionInfo"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"tokenId":{"description":"Unique token identifier.
For Apple Pay International Card Scheme transactions, ICS DPANID shall be used.\n","$ref":"#/components/schemas/tokenId"},"transactionInfo":{"$ref":"#/components/schemas/tokenTransactionInfo"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"tokenId":{"maxLength":48,"minLength":1,"type":"string","description":"Identifier of the token"},"tokenTransactionInfo":{"type":"object","description":"Token payment transaction information.","properties":{"transactionType":{"$ref":"#/components/schemas/transactionType"},"transactionResult":{"$ref":"#/components/schemas/transactionResult"},"transactionResultReason":{"$ref":"#/components/schemas/transactionResultReason"},"linkedTransactionId":{"type":"string","maxLength":64,"description":"The transactionId of a previous purchase, in case of refund.
Applicable to Google Pay only.\n"},"transactionIdentifier":{"type":"string","maxLength":64,"minLength":1,"description":"The format of the transaction identifier is in the format expected by the Wallet Provider. \n### **Apple Pay Transaction Identifier**:\nShall be provided as hexadecimal string\n#### In case of EMV Transaction\n- Concatenate the TOKEN DPAN, the ATC value and the ARQC\n- Compute a SHA256 over the concatenated value\n- transactionIdentifier = SHA-256 (DPAN | ATC | Application Cryptogram)\n - *DPAN is the value of tag 5A*\n - *ATC of the tag 9F36*\n - *ARQC of the tag 9F26*\n#### In case of mCommerce Transaction\n- Concatenate the TOKEN DPAN, the ATC value and the Remote Payment Cryptogram\n- Compute a SHA256 over the concatenated value\n- *transactionIdentifier = SHA-256 (DPAN | ATC | Remote Payment Cryptogram)*\n#### In case of MagStripe Transaction\n- Concatenate :\n - 16-Less Significant Byte of SHA256 of Track 1 Data\n - with 16-Less Significant Byte of the SHA-256 of Track 2 Data\n - *transactionIdentifier = 16-LSB (SHA-256 (Track 1 Data)) | 16-LSB (SHA-256 (Track 2 Data))*\n - where Track 1 Data should be encoded in ASCII without the start sentinel, end sentinel, and longitudinal redundancy check (LRC). All other special characters should be included.\n - where Track 2 Data should be encoded in 4-bit packed BCD (binary-coded decimal). Odd-length data is padded with a hex 'F' at the end.\n#### In case of QuicPay Transaction\n- *transactionIdentifier = MSB16( SHA-256( Card ID | ATC | Expiration Date)) | 16x '00'*\n - Card ID should be 8 bytes.\n - ATC should be 2 bytes.\n - Expiration Date should be a 2 byte hex representation in YYMM format.\n### **Google Pay Transaction Identifier**:\n#### In case of iD/QP Transaction\n- Concatenate the DPAN and transactionDate\n- Compute a SHA256 over the concatenated value\n- *transactionIdentifier = SHA-256 (DPAN | transactionDate)*\n#### In case of PURE Transaction\n- *transactionIdentifier = ATC*\n"},"totalAmount":{"$ref":"#/components/schemas/totalAmount"},"currency":{"$ref":"#/components/schemas/currency"},"merchant":{"$ref":"#/components/schemas/merchant"},"rawMerchantName":{"$ref":"#/components/schemas/rawMerchantName"},"merchantCity":{"$ref":"#/components/schemas/merchantCity"},"merchantZip":{"$ref":"#/components/schemas/merchantZip"},"merchantCountryCode":{"$ref":"#/components/schemas/merchantCountryCode"},"industryCategory":{"$ref":"#/components/schemas/industryCategory"},"industryCode":{"$ref":"#/components/schemas/industryCode"},"transactionDate":{"$ref":"#/components/schemas/transactionDate"}},"required":["transactionType","transactionResult","currency"]},"transactionType":{"type":"string","enum":["PURCHASE","REFUND"],"minLength":1,"description":"Transaction type"},"transactionResult":{"type":"string","enum":["APPROVED","PENDING","REFUNDED","DECLINED"],"description":"Transaction result status."},"transactionResultReason":{"type":"number","description":"Transaction result status reason. Provided if the result is \"DECLINED\""},"totalAmount":{"type":"number","description":"Transaction amount\nConditional to the type of transaction\n"},"currency":{"type":"string","maxLength":3,"minLength":1,"description":"ISO 4217 currency format numeric code (e.g. 978)"},"merchant":{"type":"string","maxLength":32,"minLength":1,"description":"The merchant name.\n\nIt is also referred as the card acceptor name.\n\nThis parameter is mandatory for ApplePay.\n"},"rawMerchantName":{"type":"string","maxLength":32,"minLength":1,"description":"This field should contain the original L1 value of the merchant, as seen on a customer’s bank statement.\n\nIt is also referred as the card acceptor identification code.\n\nThis parameter is mandatory for ApplePay."},"merchantCity":{"type":"string","maxLength":128,"minLength":1,"description":"Merchant Address - city"},"merchantZip":{"type":"string","maxLength":10,"minLength":1,"description":"Merchant Address -zip code"},"merchantCountryCode":{"type":"string","maxLength":2,"minLength":2,"description":"ISO 3166 Alpha 2 format"},"industryCategory":{"type":"string","maxLength":16,"minLength":1,"description":"Used to describe what type of category the merchant falls into"},"industryCode":{"type":"string","maxLength":16,"minLength":1,"description":"The industry category should be described using the ISO 18245 code, if possible"},"transactionDate":{"type":"string","format":"date-time","description":"RFC3339 format.\nDate time of the transaction.\n\nThis parameter is mandatory for ApplePay.\n"}}}}
```
## Submit card transaction details
> This method is used by TSP to send the detailed result of a transaction from a funding card
```json
{"openapi":"3.1.1","info":{"title":"Gemalto TSH Transaction Notification API","version":"2.2.2"},"tags":[{"name":"Card Transactions"}],"servers":[{"url":"https://api.dbp.thalescloud.io/tns-dispatcher/tsh/tnapi/v2.0"}],"paths":{"/card-transactions/{transactionId}":{"put":{"summary":"Submit card transaction details","description":"This method is used by TSP to send the detailed result of a transaction from a funding card","operationId":"notifyCardTransaction","parameters":[{"$ref":"#/components/parameters/x-correlation-id-header"},{"$ref":"#/components/parameters/transactionIdPath"}],"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter. Possible error codes are 111, 112, 113, 116, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"description":"Internal Server Error"}},"tags":["Card Transactions"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/notifyCardTransactionReq"}}},"description":"notifyTransaction request payload","required":true}}}},"components":{"parameters":{"transactionIdPath":{"schema":{"type":"string","maxLength":64,"minLength":1},"in":"path","required":true,"description":"Transaction identifier","name":"transactionId"}},"schemas":{"errorRes":{"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|113|Unknown issuer| \n|116|Unknown card|\n|119|Unknown Token|\n|911|Operation failed|\n|921|Unexpected server error|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"notifyCardTransactionReq":{"type":"object","required":["issuerId","cardId","transactionInfo"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"cardId":{"$ref":"#/components/schemas/cardId"},"transactionInfo":{"$ref":"#/components/schemas/cardTransactionInfo"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"cardId":{"maxLength":64,"minLength":1,"type":"string","description":"Identifier of the funding card"},"cardTransactionInfo":{"type":"object","description":"Card payment transaction information.","properties":{"transactionType":{"$ref":"#/components/schemas/transactionType"},"transactionResult":{"$ref":"#/components/schemas/transactionResult"},"transactionResultReason":{"$ref":"#/components/schemas/transactionResultReason"},"totalAmount":{"$ref":"#/components/schemas/totalAmount"},"currency":{"$ref":"#/components/schemas/currency"},"merchant":{"$ref":"#/components/schemas/merchant"},"rawMerchantName":{"$ref":"#/components/schemas/rawMerchantName"},"merchantCity":{"$ref":"#/components/schemas/merchantCity"},"merchantZip":{"$ref":"#/components/schemas/merchantZip"},"merchantCountryCode":{"$ref":"#/components/schemas/merchantCountryCode"},"industryCategory":{"$ref":"#/components/schemas/industryCategory"},"industryCode":{"$ref":"#/components/schemas/industryCode"},"transactionDate":{"$ref":"#/components/schemas/transactionDate"}},"required":["transactionType","transactionResult","currency"]},"transactionType":{"type":"string","enum":["PURCHASE","REFUND"],"minLength":1,"description":"Transaction type"},"transactionResult":{"type":"string","enum":["APPROVED","PENDING","REFUNDED","DECLINED"],"description":"Transaction result status."},"transactionResultReason":{"type":"number","description":"Transaction result status reason. Provided if the result is \"DECLINED\""},"totalAmount":{"type":"number","description":"Transaction amount\nConditional to the type of transaction\n"},"currency":{"type":"string","maxLength":3,"minLength":1,"description":"ISO 4217 currency format numeric code (e.g. 978)"},"merchant":{"type":"string","maxLength":32,"minLength":1,"description":"The merchant name.\n\nIt is also referred as the card acceptor name.\n\nThis parameter is mandatory for ApplePay.\n"},"rawMerchantName":{"type":"string","maxLength":32,"minLength":1,"description":"This field should contain the original L1 value of the merchant, as seen on a customer’s bank statement.\n\nIt is also referred as the card acceptor identification code.\n\nThis parameter is mandatory for ApplePay."},"merchantCity":{"type":"string","maxLength":128,"minLength":1,"description":"Merchant Address - city"},"merchantZip":{"type":"string","maxLength":10,"minLength":1,"description":"Merchant Address -zip code"},"merchantCountryCode":{"type":"string","maxLength":2,"minLength":2,"description":"ISO 3166 Alpha 2 format"},"industryCategory":{"type":"string","maxLength":16,"minLength":1,"description":"Used to describe what type of category the merchant falls into"},"industryCode":{"type":"string","maxLength":16,"minLength":1,"description":"The industry category should be described using the ISO 18245 code, if possible"},"transactionDate":{"type":"string","format":"date-time","description":"RFC3339 format.\nDate time of the transaction.\n\nThis parameter is mandatory for ApplePay.\n"}}}}
```
---
# 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/xpay-enablement/api-reference/tsp-api-v2/incoming-operations-from-tsp/transaction-notification-api.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.