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 requests. This emulation feature is compatible with Transactions external validation and Multi-Criteria Dynamic Card (MDC) testing.

Simulate an Authorization

The authorization is the first step of the card payment, which you can emulate with the following request.

Prerequisites – For the paymentStatus to be accepted, you must ensure that:

• The cardholder is KYC-validated & the Wallet has sufficient funds
• The card is activated and the limits are properly set

If not, the card transaction is created but refused (paymentStatus set to I), and you won't be able to emulate a settlement or reversal afterwards.

Parameters

Here are a few key parameters for simulation.

Attribute	Type	Description
cardId	integer	The unique identifier of the card.
amount	integer	Amount of the transaction expressed in the smallest unit of the Euro currency (e.g., 500 for "5.00"). Parameter available in the payment object.
category	string	The type of card transaction. Can be: ecommerce, atm, chip, contactless, contactlessOnlinePin. Parameter available in the payment object.
partialApproval	boolean	Emulates a partial approval of the card transaction.

You can add more information regarding the desired payment and merchant information by adding the relevant parameters to the corresponding objects.

API – API Reference available

For a complete list of Card Transaction simulation attributes, check the /simulation/cardtransaction/authorization endpoint documentation.

Request

Endpoint: /simulation/cardtransaction/authorization

CURL

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

Here is a {payload} example:

JSON

{
    "cardId": 12345,
    "payment": {
        "amount": 500,
        "category": "ecommerce"
    }
}

Returns the following information.

JSON

{
    "paymentStatus": "A",
    "cardTransactionId": 749207
}

Treezor also sends a cardtransaction.create webhook.

Use the /v1/cardtransactions/{cardTransactionId} endpoint to retrieve the details of the emulated card transaction.

Simulate a Settlement

You can then emulate the settlement of the card transaction step, which occurs after the authorization. This emulation generates the following CardTransaction objet, which will have the same paymentId as the authorization, and a paymentStatus set to S.

Request

Endpoint: /simulation/cardtransaction/clearing

CURL

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

Here is a {payload} example:

JSON

{
    "cardId": 12345,
    "cardTransactionId": 67890
}

Returns an HTTP 204 No Content if successful.

Treezor also sends a cardtransaction.create webhook and a balance.update webhook when applicable.

After a few seconds, you can see the corresponding card transaction object with the relevant status was created by using the following request: /v1/cardtransactions?cardId=12345

Simulate a Reversal

You can then emulate the reversal of a card transaction. An authorization must have occurred first. This emulation generates the following CardTransaction objet, which will have the same paymentId as the authorization, and a paymentStatus set to V.

Request

Endpoint: /simulation/cardtransaction/reversal

CURL

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

Here is a {payload} example:

JSON

{
    "cardId": 12345,
    "cardTransactionId": 67890,
	"amount": 250	// Optional, for partial reversal
}

Returns an HTTP 204 No Content if successful.

Treezor also sends a cardtransaction.create webhook and a balance.update webhook when applicable.

After a few seconds, you can see the corresponding card transaction object with the relevant status was created by using the following request: /v1/cardtransactions?cardId=12345.

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.

Prerequisites – Enroll the user card for OOB authentication first

The card must be enrolled for OOB in order to simulate an authentication.

/v1/cards/{cardId}/authentication-methods

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.

Request example

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

CURL

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

Here is a {payload} example:

JSON

{
	"authenticationResult": "OK"
}

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.