> 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/click-to-pay-merchants/backend-integration/apis/server-api/transaction-management.md). # Transaction Management ## Create Transaction > Provide all required data to the Merchant/PSP to build a transaction authorization request.\ > \ > In case of network token, the token PAN, expiry date and cryptogram are provided.\ > \ > In case of PCI token, the card PAN and expiry date are provided. ```json {"openapi":"3.1.1","info":{"title":"Thales ETP Server API","version":"1.78"},"tags":[{"name":"Transaction Management"}],"servers":[{"url":"https://thales.api.com/tsh-cof"}],"paths":{"/transactions":{"post":{"description":"Provide all required data to the Merchant/PSP to build a transaction authorization request.\n\nIn case of network token, the token PAN, expiry date and cryptogram are provided.\n\nIn case of PCI token, the card PAN and expiry date are provided.","operationId":"createTransaction","parameters":[{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/xCorrelationId"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["transactionId","encryptedData"],"properties":{"transactionId":{"$ref":"#/components/schemas/transactionId"},"encryptedData":{"$ref":"#/components/schemas/encryptedPaymentCredentials"},"eci":{"$ref":"#/components/schemas/eci"},"cryptogramExpiryDate":{"$ref":"#/components/schemas/cryptogramExpiryDate"},"isDAF":{"$ref":"#/components/schemas/isDAF"}}}}}},"400":{"description":"Bad request - Not Retryable","content":{"application/json":{"schema":{"type":"object","properties":{"errorCode":{"type":"string","maxLength":128,"description":"Optional information that details the error.\n\n-----------------\n|Error Code|Description|\n|-------|-------|\n|INVALID_TOKEN_STATE|The current token state doesn't allow the operation.|\n|INVALID_SIGNATURE|The 'visaSignedPayload' can't be verified by Visa.|\n|TSP_NON_RETRYABLE_ERROR|Non retryable errors returned by the TSP.|\n|PAN_NOT_ELIGIBLE|The Issuer considers the PAN as not eligible for the operation.|\n|SCHEME_TECHNICAL_ERROR|Technical error returned by TSP.|\n\n-----------------"},"errorDetails":{"$ref":"#/components/schemas/errorDetails"},"schemeCorrelationId":{"$ref":"#/components/schemas/schemeCorrelationId"}}}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Transaction Management"],"summary":"Create Transaction","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tokenId","transactionType"],"properties":{"tokenId":{"$ref":"#/components/schemas/tokenId"},"transactionType":{"$ref":"#/components/schemas/transactionType"},"authentication":{"$ref":"#/components/schemas/authenticationTransaction"},"visaSignedPayload":{"$ref":"#/components/schemas/visaSignedPayload"},"transactionData":{"$ref":"#/components/schemas/transactionData"},"device":{"$ref":"#/components/schemas/deviceTransaction"},"cardholder":{"$ref":"#/components/schemas/cardholderTransaction"}}}}},"description":""}}}},"components":{"parameters":{"authorization":{"schema":{"type":"string","maxLength":512,"minLength":1},"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},"xCorrelationId":{"schema":{"type":"string","maxLength":36,"minLength":1},"in":"header","description":"Technical identifier used for troubleshooting. \n
It helps on customer support when needed. \n
Each API request must be identified with a unique correlation Id.\n
It correlates the response and the request and eventually a notification if any. ","name":"x-correlation-id","required":true}},"schemas":{"transactionId":{"type":"string","description":"The unique transaction identifier.","minLength":1,"maxLength":128},"encryptedPaymentCredentials":{"type":"string","maxLength":8196,"description":"The payment credentials data encrypted in a JWE structure (see security section in the documentation).\n\nOnce decrypted, the JWE plaintext contains the following JSON object:\n\n|JSON field parameter name|description|MOC|Length|\n|-------|-------|-------|-------|\n|dpan|The token PAN value provided for network token.|C|Up to 19|\n|exp|The token expiry date in the format MMYY provided for network token.|C|4|\n|cryptogram|The payment cryptogram to use with the token for a payment. Presence of the cryptogram depends on the transaction type and the scheme.|C|Up to 256|\n|fpan|The funding card PAN value. Only provided for PCI token.|C|Up to 19|\n|fpanExp|The funding card expiry date in the format MMYY. Only provided for PCI token.|C|4|\n\nExample: {\"dpan:\"9580981500100002\", \"exp\":\"1222\", \"cryptogram\": \"45f8grzty7f4f5gs5s2c\"}"},"eci":{"type":"string","minLength":2,"maxLength":2,"description":"The Electronic Commerce Indicator. Payment System-specific value to indicate the results of the attempt to authenticate the cardholder. Provided only for Visa & Mastercard SCOF."},"cryptogramExpiryDate":{"type":"string","maxLength":64,"description":"Cryptogram expiry date in ISO 8601. Provided for Visa only."},"isDAF":{"type":"boolean","description":"If present and set to 'true', VISA confirms it is a Digital Authentication Framework transaction. \nCan be present only if the transaction type is 'VISA_DAF'."},"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."},"schemeCorrelationId":{"type":"string","maxLength":128,"description":"Identifier used by the schemes for additional support."},"tokenId":{"type":"string","description":"The token identifier.","pattern":"^[a-zA-Z0-9_-]+$","minLength":1,"maxLength":128},"transactionType":{"type":"string","maxLength":64,"description":"","enum":["SINGLE","SPLIT","RECURRING"]},"authenticationTransaction":{"type":"object","description":"Required only for Visa DAF.","required":["firstFactor"],"properties":{"firstFactor":{"$ref":"#/components/schemas/firstAuthenticationFactor"},"secondFactor":{"$ref":"#/components/schemas/secondAuthenticationFactor"}}},"firstAuthenticationFactor":{"type":"string","description":"First factor used to authenticate the card holder.","enum":["LOGIN_PASSWORD","DEVICE_UNLOCK","OTP_SMS","OTP_EMAIL","FIDO_BIOMETRIC","FIDO_PASSCODE","FIDO_NO_AUTH","VISA_CTF_BINDING"]},"secondAuthenticationFactor":{"type":"string","description":"Second factor used to authenticate the card holder as specified by Visa.","enum":["LOGIN_PASSWORD","DEVICE_UNLOCK","OTP_SMS","OTP_EMAIL","FIDO_BIOMETRIC","FIDO_PASSCODE","FIDO_NO_AUTH","VISA_CTF_BINDING"]},"visaSignedPayload":{"type":"string","description":"Required only for Visa CTF and Visa CTF with DAF. Set with the signature (JWT) generated by Thales ETP SDK.","minLength":1,"maxLength":4096},"transactionData":{"type":"object","description":"Required only for Visa DAF & ELO. When transactionData is present, both amount and currencyCode must be specified.","required":["amount","currencyCode"],"properties":{"amount":{"$ref":"#/components/schemas/amount"},"currencyCode":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 alphabetic currency code on 3 characters.\nELO ignores currencyCode."}}},"amount":{"type":"string","description":"Transaction amount or maximum amount authorized. Shall be positive value. Digits after the '.' are required in accordance with the scheme and currency code.","minLength":1,"maxLength":13,"pattern":"^(([1-9]{1}(\\d+)?)(\\.\\d+)?)|^([0]\\.(\\d+)?([1-9]{1})(\\d+)?)$"},"deviceTransaction":{"type":"object","required":["ipAddress"],"description":"Required for Visa DAF only. deviceId and ipAddress are mandated. location is optional.","properties":{"ipAddress":{"$ref":"#/components/schemas/ipAddressSimpleDesc"},"location":{"$ref":"#/components/schemas/location"}}},"ipAddressSimpleDesc":{"type":"string","minLength":1,"maxLength":64,"description":"The card holder's device IP address in format IPv4."},"location":{"type":"string","minLength":1,"maxLength":32,"description":"The card holder's device location.
\n
Format requirements: \n* Up to 14 characters for Mastercard and Visa.\n* Latitude is between -90 and 90 degrees.\n* Longitude is between -180 and 180 degrees.\n* For positive value, the sign '+' shall not be provided.\n* Values are provided in decimal degrees with a precision of 2 decimal places.\n* Latitude and longitude are separated by a comma.\n* Spaces are not allowed.\n\nExamples: \n* '20.68,-88.56'\n* '51.53,-133.72'\n* '-10.00,-111.00'"},"cardholderTransaction":{"type":"object","description":"Required for Visa DAF only.Information about the card holder.\n","required":["email"],"properties":{"email":{"$ref":"#/components/schemas/cardholderEmail"},"billingAddress":{"$ref":"#/components/schemas/cardholderBillingAddress"}}},"cardholderEmail":{"type":"string","minLength":1,"maxLength":128,"description":"Card holder email address."},"cardholderBillingAddress":{"type":"object","description":"Card holder billing address.","required":["line1","city","postalCode","country"],"properties":{"line1":{"$ref":"#/components/schemas/cardholderLine1"},"line2":{"$ref":"#/components/schemas/cardholderLine2"},"city":{"$ref":"#/components/schemas/cardholderCity"},"postalCode":{"$ref":"#/components/schemas/cardholderPostalCode"},"country":{"$ref":"#/components/schemas/country"},"subdivision":{"$ref":"#/components/schemas/cardholderSubdivision"}}},"cardholderLine1":{"type":"string","minLength":1,"maxLength":140,"description":"Card holder address line 1."},"cardholderLine2":{"type":"string","minLength":1,"maxLength":140,"description":"Card holder address line 2."},"cardholderCity":{"type":"string","minLength":1,"maxLength":100,"description":"Card holder city.","pattern":"^[A-Za-z0-9-_. ]+$"},"cardholderPostalCode":{"type":"string","minLength":1,"maxLength":16,"description":"Card holder postal code or zip code.","pattern":"^[A-Za-z0-9]+$"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Card holder country in ISO-3166-1 alpha-2 two-letter country code."},"cardholderSubdivision":{"type":"string","minLength":2,"maxLength":2,"description":"Card holder state or province code in ISO-3166-1 alpha-2 two-letter format."}},"responses":{"401":{"description":"Unauthorized - Not Retryable"},"404":{"description":"Not Found - Not Retryable"},"429":{"description":"Too Many Requests - Retryable"},"500":{"description":"Internal Server Error - Not Retryable"},"503":{"description":"Service Unavailable - Retryable"}}}} ``` ## Create Transaction v2 > Provide all required data to the Merchant/PSP to build a transaction authorisation request. ```json {"openapi":"3.1.1","info":{"title":"Thales ETP Server API","version":"1.78"},"tags":[{"name":"Transaction Management"}],"servers":[{"url":"https://thales.api.com/tsh-cof"}],"paths":{"/v2/transactions":{"post":{"description":"Provide all required data to the Merchant/PSP to build a transaction authorisation request.","operationId":"createTransactionV2","parameters":[{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/xCorrelationId"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["transactionId","encryptedData"],"properties":{"transactionId":{"$ref":"#/components/schemas/transactionId"},"encryptedData":{"$ref":"#/components/schemas/encryptedPaymentCredentials"},"eci":{"$ref":"#/components/schemas/eci"},"cryptogramExpiryDate":{"$ref":"#/components/schemas/cryptogramExpiryDate"},"isDAF":{"$ref":"#/components/schemas/isDAF"}}}}}},"400":{"description":"Bad request - Not Retryable","content":{"application/json":{"schema":{"type":"object","properties":{"errorCode":{"type":"string","maxLength":128,"description":"Optional information that details the error.\n\n|Error Code|Description|\n|-------|-------|\n|INVALID_TOKEN_STATE|The current token state doesn't allow the operation.|\n|INVALID_SIGNATURE|A signature (visaSignedPayload, FIDO, IAAV, THALES_AUTHENTICATOR, etc.) can't be verified by the scheme or has expired.|\n|TSP_NON_RETRYABLE_ERROR|Non retryable errors returned by the TSP.|\n|PAN_NOT_ELIGIBLE|The Issuer considers the PAN as not eligible for the operation.|\n|TOKEN_NOT_BOUND|Token is not bound to the specified device or authenticator.|\n|WRONG_ASSERTION|Verification of assertion data was unsuccessful.|\n|SCHEME_TECHNICAL_ERROR|Technical error returned by TSP.|\n|PASSKEY_AUTHENTICATION_FAILED|Passkey authentication failed|\n\n-----------------"},"errorDetails":{"$ref":"#/components/schemas/errorDetails"},"schemeCorrelationId":{"$ref":"#/components/schemas/schemeCorrelationId"}}}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Transaction Management"],"summary":"Create Transaction v2","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tokenId","transactionType"],"properties":{"tokenId":{"$ref":"#/components/schemas/tokenId"},"transactionType":{"$ref":"#/components/schemas/transactionTypeV2"},"EMV_TOKEN":{"$ref":"#/components/schemas/EMV_TOKEN"},"VISA_DAF":{"$ref":"#/components/schemas/VISA_DAF"},"MASTERCARD_TAF_FIDO":{"$ref":"#/components/schemas/MASTERCARD_TAF_FIDO"},"MASTERCARD_TAF_IAAV":{"$ref":"#/components/schemas/MASTERCARD_TAF_IAAV"},"MASTERCARD_THALES_AUTHENTICATOR":{"$ref":"#/components/schemas/MASTERCARD_THALES_AUTHENTICATOR"},"MASTERCARD_TAS":{"$ref":"#/components/schemas/MASTERCARD_TAS"}}}}}}}}},"components":{"parameters":{"authorization":{"schema":{"type":"string","maxLength":512,"minLength":1},"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},"xCorrelationId":{"schema":{"type":"string","maxLength":36,"minLength":1},"in":"header","description":"Technical identifier used for troubleshooting. \n
It helps on customer support when needed. \n
Each API request must be identified with a unique correlation Id.\n
It correlates the response and the request and eventually a notification if any. ","name":"x-correlation-id","required":true}},"schemas":{"transactionId":{"type":"string","description":"The unique transaction identifier.","minLength":1,"maxLength":128},"encryptedPaymentCredentials":{"type":"string","maxLength":8196,"description":"The payment credentials data encrypted in a JWE structure (see security section in the documentation).\n\nOnce decrypted, the JWE plaintext contains the following JSON object:\n\n|JSON field parameter name|description|MOC|Length|\n|-------|-------|-------|-------|\n|dpan|The token PAN value provided for network token.|C|Up to 19|\n|exp|The token expiry date in the format MMYY provided for network token.|C|4|\n|cryptogram|The payment cryptogram to use with the token for a payment. Presence of the cryptogram depends on the transaction type and the scheme.|C|Up to 256|\n|fpan|The funding card PAN value. Only provided for PCI token.|C|Up to 19|\n|fpanExp|The funding card expiry date in the format MMYY. Only provided for PCI token.|C|4|\n\nExample: {\"dpan:\"9580981500100002\", \"exp\":\"1222\", \"cryptogram\": \"45f8grzty7f4f5gs5s2c\"}"},"eci":{"type":"string","minLength":2,"maxLength":2,"description":"The Electronic Commerce Indicator. Payment System-specific value to indicate the results of the attempt to authenticate the cardholder. Provided only for Visa & Mastercard SCOF."},"cryptogramExpiryDate":{"type":"string","maxLength":64,"description":"Cryptogram expiry date in ISO 8601. Provided for Visa only."},"isDAF":{"type":"boolean","description":"If present and set to 'true', VISA confirms it is a Digital Authentication Framework transaction. \nCan be present only if the transaction type is 'VISA_DAF'."},"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."},"schemeCorrelationId":{"type":"string","maxLength":128,"description":"Identifier used by the schemes for additional support."},"tokenId":{"type":"string","description":"The token identifier.","pattern":"^[a-zA-Z0-9_-]+$","minLength":1,"maxLength":128},"transactionTypeV2":{"type":"string","maxLength":64,"description":"The request content depends on the transaction type.","enum":["EMV_TOKEN","PCI_TOKEN","VISA_DAF","MASTERCARD_TAF_IAAV","MASTERCARD_TAF_FIDO","MASTERCARD_THALES_AUTHENTICATOR","MASTERCARD_TAS"]},"EMV_TOKEN":{"type":"object","description":"List the parameters that are accepted to get a cryptogram for a transaction with the token.","required":["isRecurring"],"properties":{"isRecurring":{"$ref":"#/components/schemas/isRecurring"},"amount":{"type":"string","description":"Transaction amount or maximum amount authorized. Shall be positive value. Digits after the '.' are required in accordance with the currency code.\n
If amount is defined, currencyCode must be present also.\n
Mandatory for ELO.","minLength":1,"maxLength":13,"pattern":"^(([1-9]{1}(\\d+)?)(\\.\\d+)?)|^([0]\\.(\\d+)?([1-9]{1})(\\d+)?)$"},"currencyCode":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 alphabetic currency code on 3 characters.\nIf currencyCode is defined, amount must be present also.\n
Mandatory for ELO."}}},"isRecurring":{"type":"boolean","description":"Indicate if the payment is recurring (like a monthly subscription)"},"VISA_DAF":{"type":"object","description":"List the parameters that are required to get a Visa DAF compliant cryptogram.","required":["firstFactor","visaSignedPayload","amount","currencyCode","ipAddress","email"],"properties":{"firstFactor":{"$ref":"#/components/schemas/firstAuthenticationFactor"},"secondFactor":{"$ref":"#/components/schemas/secondAuthenticationFactor"},"visaSignedPayload":{"$ref":"#/components/schemas/visaSignedPayloadTrxV2"},"amount":{"$ref":"#/components/schemas/amount"},"currencyCode":{"$ref":"#/components/schemas/currencyCode"},"ipAddress":{"$ref":"#/components/schemas/ipAddressSimpleDesc"},"location":{"$ref":"#/components/schemas/location"},"email":{"$ref":"#/components/schemas/cardholderEmail"},"billingAddress":{"$ref":"#/components/schemas/cardholderAddress"}}},"firstAuthenticationFactor":{"type":"string","description":"First factor used to authenticate the card holder.","enum":["LOGIN_PASSWORD","DEVICE_UNLOCK","OTP_SMS","OTP_EMAIL","FIDO_BIOMETRIC","FIDO_PASSCODE","FIDO_NO_AUTH","VISA_CTF_BINDING"]},"secondAuthenticationFactor":{"type":"string","description":"Second factor used to authenticate the card holder as specified by Visa.","enum":["LOGIN_PASSWORD","DEVICE_UNLOCK","OTP_SMS","OTP_EMAIL","FIDO_BIOMETRIC","FIDO_PASSCODE","FIDO_NO_AUTH","VISA_CTF_BINDING"]},"visaSignedPayloadTrxV2":{"type":"string","description":"Set with the signature (JWT) generated by Thales ETP SDK.","minLength":1,"maxLength":4096},"amount":{"type":"string","description":"Transaction amount or maximum amount authorized. Shall be positive value. Digits after the '.' are required in accordance with the scheme and currency code.","minLength":1,"maxLength":13,"pattern":"^(([1-9]{1}(\\d+)?)(\\.\\d+)?)|^([0]\\.(\\d+)?([1-9]{1})(\\d+)?)$"},"currencyCode":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 alphabetic currency code on 3 characters."},"ipAddressSimpleDesc":{"type":"string","minLength":1,"maxLength":64,"description":"The card holder's device IP address in format IPv4."},"location":{"type":"string","minLength":1,"maxLength":32,"description":"The card holder's device location.
\n
Format requirements: \n* Up to 14 characters for Mastercard and Visa.\n* Latitude is between -90 and 90 degrees.\n* Longitude is between -180 and 180 degrees.\n* For positive value, the sign '+' shall not be provided.\n* Values are provided in decimal degrees with a precision of 2 decimal places.\n* Latitude and longitude are separated by a comma.\n* Spaces are not allowed.\n\nExamples: \n* '20.68,-88.56'\n* '51.53,-133.72'\n* '-10.00,-111.00'"},"cardholderEmail":{"type":"string","minLength":1,"maxLength":128,"description":"Card holder email address."},"cardholderAddress":{"type":"object","description":"Card holder billing address.","required":["line1","city","postalCode","country"],"properties":{"line1":{"$ref":"#/components/schemas/cardholderLine1"},"line2":{"$ref":"#/components/schemas/cardholderLine2"},"city":{"$ref":"#/components/schemas/cardholderCity"},"postalCode":{"$ref":"#/components/schemas/cardholderPostalCode"},"country":{"$ref":"#/components/schemas/country"},"subdivision":{"$ref":"#/components/schemas/cardholderSubdivision"}}},"cardholderLine1":{"type":"string","minLength":1,"maxLength":140,"description":"Card holder address line 1."},"cardholderLine2":{"type":"string","minLength":1,"maxLength":140,"description":"Card holder address line 2."},"cardholderCity":{"type":"string","minLength":1,"maxLength":100,"description":"Card holder city.","pattern":"^[A-Za-z0-9-_. ]+$"},"cardholderPostalCode":{"type":"string","minLength":1,"maxLength":16,"description":"Card holder postal code or zip code.","pattern":"^[A-Za-z0-9]+$"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Card holder country in ISO-3166-1 alpha-2 two-letter country code."},"cardholderSubdivision":{"type":"string","minLength":2,"maxLength":2,"description":"Card holder state or province code in ISO-3166-1 alpha-2 two-letter format."},"MASTERCARD_TAF_FIDO":{"type":"object","description":"List the parameters that are required to get a Mastercard TAF compliant cryptogram for a token bound to a FIDO authenticator. All cardholder related parameters must be provided if they are collected according to compliance with applicable laws and local regulation.","required":["amount","currencyCode","merchantCategoryCode","merchantCountry","deviceId","mcCertifiedSolutionId","credentialId","fidoRelyingParty","fidoUserId","isSpcEnabled","fidoAuthenticationResponse","mcTransactionAssertion"],"properties":{"amount":{"$ref":"#/components/schemas/amount"},"currencyCode":{"$ref":"#/components/schemas/currencyCode"},"deviceId":{"$ref":"#/components/schemas/deviceIdMdes"},"ipAddress":{"$ref":"#/components/schemas/ipAddressSimpleDesc"},"location":{"$ref":"#/components/schemas/locationMastercardTrx"},"mcCertifiedSolutionId":{"$ref":"#/components/schemas/mcCertifiedSolutionId"},"credentialId":{"$ref":"#/components/schemas/credentialId"},"fidoRelyingParty":{"$ref":"#/components/schemas/fidoRelyingParty"},"fidoUserId":{"$ref":"#/components/schemas/fidoUserId"},"isSpcEnabled":{"$ref":"#/components/schemas/isSpcEnabled"},"fidoAuthenticationResponse":{"$ref":"#/components/schemas/fidoPublicKeyCredential"},"mcTransactionAssertion":{"$ref":"#/components/schemas/mcTransactionAssertion"},"email":{"$ref":"#/components/schemas/cardholderEmail"},"billingAddress":{"$ref":"#/components/schemas/cardholderAddressTAF"},"shippingAddress":{"$ref":"#/components/schemas/cardholderAddressTAF"},"merchantCategoryCode":{"$ref":"#/components/schemas/merchantCategoryCode"},"merchantCountry":{"$ref":"#/components/schemas/merchantCountry"}}},"deviceIdMdes":{"type":"string","description":"The unique device identifier.","minLength":1,"maxLength":36},"locationMastercardTrx":{"type":"string","minLength":1,"maxLength":9,"description":"The card holder's device location.
\n
Format requirements: \n* Up to 9 characters for Mastercard.\n* Latitude is between -90 and 90 degrees.\n* Longitude is between -180 and 180 degrees.\n* For positive value, the sign '+' shall not be provided.\n* It's formatted as first 8 digits are latitude & longitude hexadecimal encoded degree with two decimal places and last digit is latitude & longitude sector value from one of the values (1:NW 2:NE 3SW 4SE). \n\nExample: \n* -20.45,139.56 is equals to Sector=4, Longitude=3684 (hex), Latitude=07FD (hex) \n* final value: 07FD36844"},"mcCertifiedSolutionId":{"type":"string","minLength":1,"maxLength":128,"description":"Unique identifier of the Mastercard TAF certified MFA method."},"credentialId":{"type":"string","minLength":1,"maxLength":128,"description":"UUID identifying the FIDO authenticator."},"fidoRelyingParty":{"type":"string","minLength":1,"maxLength":128,"description":"The FIDO relying party."},"fidoUserId":{"type":"string","minLength":1,"maxLength":128,"description":"The FIDO user identifier."},"isSpcEnabled":{"type":"boolean","description":"Indicates if Secure Payment Confirmation is enabled."},"fidoPublicKeyCredential":{"type":"object","description":"A JSON FIDO public key as per https://www.w3.org/TR/webauthn-3/#iface-pkcredential.\n
Also known as FIDO assertion.

\nExample:\n
{
\n\"type\": \"public-key\",
\n\"id\": \"h0mC9xtLjggpcvxq4YXepkemUt2oNL5F_-NPpCCcHNE\",
\n\"rawId\": \"h0mC9xtLjggpcvxq4YXepkemUt2oNL5F_-NPpCCcHNE\",
\n\"authenticatorAttachment\": \"platform\",
\n\"response\": {
\n\"clientDataJSON\": \"SZY...In0\",
\n\"authenticatorData\": \"o2Nm...AAA\",
\n\"signature\": \"MEU...VQQ\",
\n\"userHandle\": \"ca7...002\"\n\"transports\": [
\n \"internal\"
\n ]
\n},
\n\"clientExtensionResults\": {}
\n}
"},"mcTransactionAssertion":{"type":"string","minLength":1,"maxLength":8196,"description":"The transaction assertion JWT as per Mastercard specifications."},"cardholderAddressTAF":{"type":"object","description":"Card holder billing address.","required":["line1","city","postalCode","country"],"properties":{"line1":{"$ref":"#/components/schemas/cardholderLine1"},"city":{"$ref":"#/components/schemas/cardholderCity"},"postalCode":{"$ref":"#/components/schemas/cardholderPostalCode"},"country":{"$ref":"#/components/schemas/country"},"subdivision":{"$ref":"#/components/schemas/cardholderSubdivision"}}},"merchantCategoryCode":{"type":"string","minLength":1,"maxLength":4,"description":"The merchant category code."},"merchantCountry":{"type":"string","minLength":2,"maxLength":2,"description":"Merchant country in ISO-3166-1 alpha-2 two-letter country code."},"MASTERCARD_TAF_IAAV":{"type":"object","description":"List the parameters that are required to get a Mastercard TAF compliant cryptogram from and issuer IAAV. All cardholder related parameters must be provided if they are collected according to compliance with applicable laws and local regulation.","required":["amount","currencyCode","mcIaav","mcIaavTransactionId","verificationTimestamp","merchantCategoryCode","merchantCountry"],"properties":{"amount":{"$ref":"#/components/schemas/amount"},"currencyCode":{"$ref":"#/components/schemas/currencyCode"},"ipAddress":{"$ref":"#/components/schemas/ipAddressSimpleDesc"},"location":{"$ref":"#/components/schemas/locationMastercardTrx"},"mcIaav":{"$ref":"#/components/schemas/mcIaav"},"mcIaavTransactionId":{"$ref":"#/components/schemas/mcIaavTransactionId"},"verificationTimestamp":{"$ref":"#/components/schemas/timestamp"},"email":{"$ref":"#/components/schemas/cardholderEmail"},"billingAddress":{"$ref":"#/components/schemas/cardholderAddressTAF"},"shippingAddress":{"$ref":"#/components/schemas/cardholderAddressTAF"},"merchantCategoryCode":{"$ref":"#/components/schemas/merchantCategoryCode"},"merchantCountry":{"$ref":"#/components/schemas/merchantCountry"}}},"mcIaav":{"type":"string","minLength":1,"maxLength":8196,"description":"The issuer IAAV as per Mastercard specifications, so JSON encoded in Base64."},"mcIaavTransactionId":{"type":"string","minLength":1,"maxLength":128,"description":"The transaction identifier as present in the issuer IAAV."},"timestamp":{"type":"string","minLength":1,"maxLength":64,"description":"A timestamp compliant with ISO 8601."},"MASTERCARD_THALES_AUTHENTICATOR":{"type":"object","description":"List the parameters that are required to get a Mastercard TAF compliant cryptogram using their proprietary PKI as their MFA method. All cardholder related parameters must be provided if they are collected according to compliance with applicable laws and local regulation.","required":["amount","currencyCode","deviceId","tafAssertionPayload","merchantCategoryCode","merchantCountry"],"properties":{"amount":{"$ref":"#/components/schemas/amount"},"currencyCode":{"$ref":"#/components/schemas/currencyCode"},"deviceId":{"$ref":"#/components/schemas/deviceIdMdes"},"tafAssertionPayload":{"type":"string","minLength":1,"maxLength":10000,"description":"JSON assertion payload Base64 encoded, generated by Thales ETP SDK."},"merchantCategoryCode":{"$ref":"#/components/schemas/merchantCategoryCode"},"merchantCountry":{"$ref":"#/components/schemas/merchantCountry"},"email":{"$ref":"#/components/schemas/cardholderEmail"},"location":{"$ref":"#/components/schemas/locationMastercardTrx"},"ipAddress":{"$ref":"#/components/schemas/ipAddressSimpleDesc"},"billingAddress":{"$ref":"#/components/schemas/cardholderAddressTAF"},"shippingAddress":{"$ref":"#/components/schemas/cardholderAddressTAF"}}},"MASTERCARD_TAS":{"type":"object","description":"List the parameters that are required to get a Mastercard TAS compliant cryptogram using passkey. All cardholder related parameters must be provided if they are collected according to compliance with applicable laws and local regulation.","required":["amount","currencyCode","merchantCategoryCode","merchantCountry","acquirerMerchantId","acquirerBin","ipAddress","mcCallbackUri"],"properties":{"mcCallbackUri":{"$ref":"#/components/schemas/mcCallbackUri"},"amount":{"$ref":"#/components/schemas/amount"},"currencyCode":{"$ref":"#/components/schemas/currencyCode"},"merchantCategoryCode":{"$ref":"#/components/schemas/merchantCategoryCode"},"merchantCountry":{"$ref":"#/components/schemas/merchantCountry"},"acquirerMerchantId":{"$ref":"#/components/schemas/acquirerMerchantId"},"acquirerBin":{"$ref":"#/components/schemas/acquirerBin"},"email":{"$ref":"#/components/schemas/cardholderEmail"},"phoneCountryCode":{"$ref":"#/components/schemas/phoneCountryCode"},"phoneNumber":{"$ref":"#/components/schemas/phoneNumber"},"location":{"$ref":"#/components/schemas/locationMastercardTrx"},"ipAddress":{"$ref":"#/components/schemas/ipAddressSimpleDesc"},"billingAddress":{"$ref":"#/components/schemas/cardholderAddressTAF"},"shippingAddress":{"$ref":"#/components/schemas/cardholderAddressTAF"}}},"mcCallbackUri":{"type":"string","minLength":1,"maxLength":2048,"description":"Updated merchant callback url provided by mastercard during authenticate step, the object contains the authenticationSessionId, flowId and srcCorrelationId"},"acquirerMerchantId":{"type":"string","description":"One of the below configuration must be provided:
- businessIdentificationType and businessIdentificationValue or
- acquirerId and acquirerMerchantId.

Acquirer merchant identifier.","minLength":1,"maxLength":25},"acquirerBin":{"type":"string","pattern":"^([0-9]*$)","minLength":1,"maxLength":6,"description":"Acquiring institution BIN"},"phoneCountryCode":{"type":"string","minLength":1,"maxLength":4,"description":"Country code for phone number"},"phoneNumber":{"type":"string","minLength":1,"maxLength":128,"description":"Phone number without country code."}},"responses":{"401":{"description":"Unauthorized - Not Retryable"},"404":{"description":"Not Found - Not Retryable"},"429":{"description":"Too Many Requests - Retryable"},"500":{"description":"Internal Server Error - Not 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 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/click-to-pay-merchants/backend-integration/apis/server-api/transaction-management.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.