Emulation

Emulation features are only available in the Sandbox environment.

Tip – You can also rely on webhooks

For operations that cannot be emulated in Sandbox, webhook examples are provided.

Card Transactions

You can emulate Card Transactions using the following request.

Parameters

Attribute	Type	Description
publicToken	string	The public token of the Card to use for the Card Transaction.
transLink	string	A unique reference used to associate the Card Transaction with a paymentId. Must be 100000000000000 or greater.
paymentStatus	string	The type of CardTransaction, which for simulation purposes can be A or S. See list of values.
date	string	The date of the CardTransaction, as seen in the authorizationIssuerTime attribute.
amount	number	The amount of the CardTransaction, as seen it the paymentAmount and paymentLocalAmount attributes.
mcc	string	The Merchant Category Code for this CardTransaction, allowing you to check your Card MCC restrictions.
merchantId	string	The Merchant's ID for this CardTransaction, allowing you to check your Card MID restrictions.
merchantName	string	The name of the merchant.

Tip – You can emulate a complete flow

To emulate a complete flow, set a paymentStatus = A followed by S while specifying the same transLink for both requests.

Learn more about the different transaction flows in the Transaction examples article.

Request

CURL

curl -X POST {baseUrl}/simulation/cardtransactions \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	--data-raw '{payload}'

Here is a {payload} example:

JSON

{
	"publicToken": "103020378",
	"date": "2022-02-12 13:00:00",
	"amount": 15.90,
	"mcc": "8574",
	"merchantId": "3256",
	"merchantName": "Merchant Name",
	"paymentStatus": "A",
	"paymentCode": "100000000000004"
}

The request returns a 201 HTTP Status Code without any content and sends a cardtransaction.create webhook.

Note – Disclaimers about this emulation

• No impact on Wallet Balances: A balance.update webhook is sent, but values are set to 0.
• No support for refunds and negative amount settlements yet.

Simulate Card Transaction Authentication (SCA)

The Treezor API allows you to simulate the authentication (SCA) process of an online card transaction. With these dedicated endpoints, you can trigger the relevant webhooks.

This is a 2-step process:

1. Simulate the authentication of an online card transaction for a given card.
2. Submit the result of the authentication to obtain the final result from Treezor.

Optionally, you can also simulate the cancellation of the authentication process.

Simulate an authentication

This request simulates the authentication of an online card transaction for a given card.

Parameters

Attribute	Type	Description
cardId	integer	The unique identifier of the Card for which you want to simulate card transaction authentication.
merchantName	string	The name of the merchant processing the transaction for the simulated authentication.
paymentAmount	number	The amount of the transaction for the simulated authentication.
paymentCurrency	string	The currency of the transaction for the simulated authentication, in the ISO 4217 format.
merchantAppRedirectURL	string	As defined in the 3DS 2.2 specification, links back to the merchant application from an OOB app.

Request example

Endpoint: /simulation/auth-requests

CURL

curl -X POST {baseUrl}/simulation/auth-requests \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	--d '{payload}'

Here is a {payload} example:

JSON

{
	"cardId": 12345,
	"merchantName": "Tree Company",
	"paymentAmount": 10.01,
	"paymentCurrency": "EUR",
	"merchantAppRedirectURL": "https://your.app.com/redirect"
}

Treezor sends a card3DSv2Authentication.create webhook.

From there, you can either:

• Simulate a canceled authentication
• Submit the authentication result

Simulate a canceled authentication

If the cardholder cancels the authentication process before it can be completed (i.e., leaves the application), the server indicates to Treezor that the authentication couldn't be carried out.

This information is available to you after you've submitted the authentication result through the card3DSv2Authentication.update webhook authenticationFinalResult.

Treezor provides a dedicated endpoint to simulate this situation.

Request example

Endpoint: /simulation/auth-requests/{authRequestId}/cancel

The authRequestId is available in the card3DSv2Authentication.create webhook.

CURL

curl -X POST {baseUrl}/simulation/authrequests/{authRequestId}/cancel \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

Treezor answers with an HTTP 204.

You can now submit the authentication result.

Submit the authentication result

Whether you use the cancellation simulation or not, you must submit the authentication result to Treezor, so that Treezor can inform you of the final authentication result with the relevant webhook.

Parameters

Attribute	Type	Description
authenticationResult	integer	The result of your end user authentication, which can be: OK, KO_TECHNICAL, KO_AUTH_FAILED, or FALLBACK.
authenticationSignature	string	The authentication signature (SCA proof), optional if the authenticationResult is other than OK.

Request example

Endpoint: /v1/auth-requests/{authRequestId}/result

CURL

curl -X PUT '{baseUrl}/v1/auth-requests/{authRequestId}/result`' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content: application/json' \
	-d '{payload}'

Here is a {payload} example:

JSON

{
	"authenticationResult": "OK",					
	"authenticationSignature": "dnptZ3V...m9hZWc="
}

Treezor sends the card3DSv2Authentication.update webhook with the authenticationFinalResult set as follows.

Submitted authenticationResult	authenticationFinalResult
OK	SUCCESS
KO_AUTH_FAILED	UNAUTHENTICATED
KO_TECHNICAL	ERROR
FALLBACK	FALLBACK

If you've simulated a cancellation by the server, the authenticationFinalResult is set to ERROR.