Transaction Management

Create Transaction

post

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.

Header parameters

authorizationstring · min: 1 · max: 512Required

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · min: 1 · max: 36Required

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Body

application/json

tokenIdstring · min: 1 · max: 128Required

The token identifier.

Pattern: ^[a-zA-Z0-9_-]+$

transactionTypestring · enum · max: 64RequiredExample: SINGLEPossible values:

visaSignedPayloadstring · min: 1 · max: 4096Optional

Required only for Visa CTF and Visa CTF with DAF. Set with the signature (JWT) generated by Thales ETP SDK.

Responses

201

Created

application/json

transactionIdstring · min: 1 · max: 128Required

The unique transaction identifier.

encryptedDatastring · max: 8196Required

The payment credentials data encrypted in a JWE structure (see security section in the documentation).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
dpan	The token PAN value provided for network token.	C	Up to 19
exp	The token expiry date in the format MMYY provided for network token.	C	4
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
fpan	The funding card PAN value. Only provided for PCI token.	C	Up to 19
fpanExp	The funding card expiry date in the format MMYY. Only provided for PCI token.	C	4

Example: {"dpan:"9580981500100002", "exp":"1222", "cryptogram": "45f8grzty7f4f5gs5s2c"}

ecistring · min: 2 · max: 2Optional

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.

Example: 07

cryptogramExpiryDatestring · max: 64Optional

Cryptogram expiry date in ISO 8601. Provided for Visa only.

Example: 2021-09-27T17:06:09.000Z

isDAFbooleanOptional

If present and set to 'true', VISA confirms it is a Digital Authentication Framework transaction. Can be present only if the transaction type is 'VISA_DAF'.

Example: true

400

Bad request - Not Retryable

application/json

401

Unauthorized - Not Retryable

404

Not Found - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

post/transactions

HTTPcURLJavaScriptPython

POST /tsh-cof/transactions HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 143

{
  "tokenId": "COFTG-M-ce464906-cf39-4990-b4a8-c160e67c603a",
  "transactionType": "SINGLE",
  "transactionData": {
    "amount": "12.84",
    "currencyCode": "EUR"
  }
}

{
  "transactionId": "COFTG-G-e141-0303e55b-5e14-4af4-9601-b268d3dfbb65",
  "encryptedData": "eyJhbGciOiJSU0EtT...GoWAB7Ucw",
  "eci": "07",
  "cryptogramExpiryDate": "2021-09-27T17:06:09.000Z"
}

Create Transaction v2

post

Provide all required data to the Merchant/PSP to build a transaction authorisation request.

Header parameters

authorizationstring · min: 1 · max: 512Required

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · min: 1 · max: 36Required

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Body

application/json

tokenIdstring · min: 1 · max: 128Required

The token identifier.

Pattern: ^[a-zA-Z0-9_-]+$

transactionTypestring · enum · max: 64Required

The request content depends on the transaction type.

Example: EMV_TOKENPossible values:

Responses

201

Created

application/json

transactionIdstring · min: 1 · max: 128Required

The unique transaction identifier.

encryptedDatastring · max: 8196Required

The payment credentials data encrypted in a JWE structure (see security section in the documentation).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
dpan	The token PAN value provided for network token.	C	Up to 19
exp	The token expiry date in the format MMYY provided for network token.	C	4
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
fpan	The funding card PAN value. Only provided for PCI token.	C	Up to 19
fpanExp	The funding card expiry date in the format MMYY. Only provided for PCI token.	C	4

Example: {"dpan:"9580981500100002", "exp":"1222", "cryptogram": "45f8grzty7f4f5gs5s2c"}

ecistring · min: 2 · max: 2Optional

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.

Example: 07

cryptogramExpiryDatestring · max: 64Optional

Cryptogram expiry date in ISO 8601. Provided for Visa only.

Example: 2021-09-27T17:06:09.000Z

isDAFbooleanOptional

If present and set to 'true', VISA confirms it is a Digital Authentication Framework transaction. Can be present only if the transaction type is 'VISA_DAF'.

Example: true

400

Bad request - Not Retryable

application/json

401

Unauthorized - Not Retryable

404

Not Found - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

post/v2/transactions

HTTPcURLJavaScriptPython

POST /tsh-cof/v2/transactions HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "tokenId": "COFTG-M-ce464906-cf39-4990-b4a8-c160e67c603a",
  "transactionType": "EMV_TOKEN",
  "EMV_TOKEN": {
    "isRecurring": false,
    "amount": "15.55",
    "currencyCode": "EUR"
  }
}

EMV Token TransactionVisa DAFMastercard TAF FIDOMastercard TAF IAAVMastercard THALES AUTHENTICATOR

{
  "transactionId": "COFTG-G-e141-0303e55b-5e14-4af4-9601-b268d3dfbb65",
  "encryptedData": "eyJhbGciOiJSU0EtT...GoWAB7Ucw",
  "eci": "07",
  "cryptogramExpiryDate": "2021-09-27T17:06:09.000Z"
}