Emulation

Emulation features are only available in Sandbox environment.

Tip – You can also rely on webhooks

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

SEPA Direct Debit reception (SDDR)

SDDR Core can be emulated by using the dedicated /simulation/payout-sddr endpoint.

This is a Payout operation; simulating an SDDR debits the Treezor Wallet.

Parameters

Attribute	Type	Description
debitorIban	string	IBAN or Virtual IBAN of the debited Wallet.
amount	integer	Amount of the SDD (will be divided by the nbTxs). Decimal amounts are not supported.
typeSDD	string	Either CORE (default) or B2B.
typeReject	string	The type of error returned if the SDDR fails. Can be: rejected (default), returned, refunded, or today (specifies that we want the SDDR to be executed today).
sci	string	The SEPA Credit Identifier of the user. In the case of simulation, this defaults to a random string.
nbTxs	integer	The number of transactions for the SDD. Defaults to 1.
mandateId	integer	The Beneficiary Mandate unique identifier. This field is optional.
executeAfterParse	integer	When set to 1, launch the job to execute pending SDDRs on the due date (must be used in combination with typeReject = today).

Request

CURL

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

Here is an example of {payload}:

JSON

{
  "amount": "26",
  "debitorIban": "FR7616798000010000071474474", 
  "sci": "FR44ZZZ332801",
  "typeSDD":"CORE",
  "typeReject":"today",
  "executeAfterParse":1
}

Response example (if executeAfterParse is set to 1):

JSON

{
    "messages":[
        "[Simulation] [POST /payoutSddr] CORE SDDR created",
        "[Simulation] batchExecuteSddr() launched"
    ]
}

SEPA Direct Debit emission (SDDE)

SDDE can be emulated by using the /v1/payins endpoint.

This is a Payin operation; simulating an SDDE credits the Treezor Wallet.

Prerequisites – SDDE emulation requires a KYC-validated legal entity with:

• A signed Mandate – Must be the correct sddType.
• A SEPA Creditor Identifier (SCI) – To enable a SCI, please contact your Treezor Account Manager.

Mandatory parameters

Attribute	Type	Description
walletId	integer	The unique identifier of the Wallet to credit.
paymentMethodId	integer	Set this value to 21 for crediting funds in Sandbox only.
amount	number	The amount to credit. Must end with 1.25 to emulate a VALIDATED result.
currency	string	The currency of the transfer. Must be EUR.
mandateId	integer	The unique identifier of the Mandate.

Request

CURL

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

Here is an example of {payload}:

JSON

{
	"walletId":"{walletId}",
	"userId":"{userId}",
	"paymentMethodId":21,
	"amount":1.25,
	"currency":"EUR",
	"mandateId":"{mandateId}"
}

Returns the Payin object.

JSON

{
	"payins": [
		{
			"payinId": "<integer>",
			"payinTag": "<string>",
			"payinStatus": "<string>",			
			"codeStatus": "<integer>",
			"informationStatus": "<string>",
			"walletId": "<integer>",			// id of the wallet to credit
			"userId": "<integer>",
			"amount": "<string>",
			"currency": "<string>",
			[...] // some attributes are hidden
		}
	]
}

Note – Funds availability latency

Funds are usually available in the Wallet within 5 minutes following the request.

SEPA Credit Transfer reception (SCTR)

SCTR can be emulated by using the dedicated /simulation/payin-sct endpoint.

This is a Payin operation; simulating an SCTR credits the Treezor Wallet.

Parameters

The following parameters are required.

Attribute	Type	Description
iban	string	The IBAN of the Wallet to credit.
amount	integer	The amount to credit. Decimal amounts are not supported.

Request

Endpoint: /simulation/payin-sct

CURL

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

Here is an example of {payload}

JSON

{
	"iban":"FR7616798000010001726649397",
	"amount": 20
}

Returns the id of the SCTR, its txId (transaction id) and its payinId.

JSON

{
    "sctrs": [
        {
            "id": 10022,
            "txId": "xxCN7gLRpqmjS6p5",
            "payinId": 1234567,
            "returnReasonCode": null
        }
    ]
}

Tip – The returnReasonCode provides more information

The returnReasonCode can inform you of the reason for a rejection, in which case the payinId will be null.

Accepted SCTR

• The IBAN must be valid and,
• The Wallet must be validated and,
• The User must have its KYC validated except when the SCTR is used as an additional vigilance measure.

Refused SCTR

• The IBAN can be erroneous (you can for example use FR76169999999999999999999) or,
• The User KYC status can be NONE/PENDING or,
• The Wallet status can be PENDING or CANCELED

Legacy

SCTR Emulation can also be achieved using the same procedure as for SDDE, by changing the paymentMethodId to 20.

Instant SEPA Credit Transfer reception

SCTR Inst can be emulated by using the dedicated /simulation/sct-inst/payin endpoint.

CURL

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

Here is an example of {payload}:

JSON

{
  "name":"M. Firstname LASTNAME", 	  // Name of the recipient (User)
  "bic":"TRZOFR21XXX",                // BIC of the recipient (User)
  "iban":"FR76167980019999999999999", // IBAN of the recipient (Wallet)
  "currency":"EUR", 
  "amount":10.0
}

Returns the paymentID and sctInstID.

JSON

{
    "sctInstID": "2333c7a8-25c5-54ff-a06e-7ed2bd8c2f66",
    "paymentID": "RECEPTION_6cde3d9f-58d2-11ec-8593-86285561c46d"
}

The sctInstID can be used to retrieve the payin using the /v1/payins/{sctInstId} endpoint.

Accepted SCTR Inst

For an emulated SCTR Inst to be accepted:

• The IBAN must be valid and,
• The Wallet must be validated.

Refused SCTR Inst

The emulated SCTR Inst may be refused if:

• The IBAN is erroneous (e.g., you can use FR76169999999999999999999), or
• The Wallet status can be PENDING or CANCELED
• The SCTR Inst amount can be greater that €10,000 in a B2C context or greater than €50,000 in a B2B context

In which case, you receive a sepaSctrInst.reject_sctr_inst webhook.

SCTR Recalls

To initiate an SCTR Recall, you can use the following request.

Prerequisites – You need an SCTR first

Use the /simulation/payin-sct endpoint to create a valid SCTR emulation beforehand.

Parameters

Attribute	Type	Description
cxlId	string	The unique identifier of the Recall. We recommend that you use the SCTR's id.
statusId	integer	The status of the recall resource. For simulation purposes, you must set this to 2 (PENDING_PAYIN_REFUND_CREATED).
sctrId	integer	The SCTR's id as provided by the SCTR simulation endpoint.
txId	string	The txId value returned by the SCTR simulation endpoint.
reasonCode	string	Reason code of the recall request see available values.
createPayinRefund	boolean	Creates a payinrefund resource and receives the corresponding webhooks if set to true.

Request

CURL

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

Here is an example of {payload}:

JSON

{ 
  "cxlId": "401", 
  "statusId": 2, 
  "sctrId": 401, 
  "txId": "401", 
  "reasonCode": "TECH", 
  "createPayinRefund": true 
}

Returns the id of the Recall.

JSON

{
	"recalls": {
    	"id": 10
	}
}

SCTR Inst Recalls

To initiate an SCTR Inst Recall, you can use the following request.

Prerequisites – You need an SCTR Inst first

A valid SCTR Inst must have been emulated beforehand.

Parameters

Attribute	Type	Description
sctInstId	string	The SCTR Inst's id as provided by the SCTR Inst simulation endpoint.
demandDate	string	The date of the recall request.
reasonCode	string	The reason code of the recall request see available values.
additionalInformation	string	Information on top of the recall reason code you want to receive (can only be used with reasonCode of type FRAD).

Request

CURL

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

Here is a {payload} example:

JSON

{ 
	"sctInstId": "1380aeca-963b-5497-aef4-a9532086653c",
	"demandDate": "2022-11-24",
	"reasonCode": "FRAD",
	"additionalInformation": ""
}

Returns the id for the Recall:

JSON

{
    "sctInstId": "c8457258-b18c-5647-9950-9ba3c99a9543",
    "recallrId": "f3f6a9c8-2f4b-5906-9ac7-2d908d04b681"
}

Beneficiary Validation (vopResult)

You can emulate the validation result (vopResult) of the beneficiary by using the specific request payloads below.

Endpoint: /v1/beneficiaries/validation

CURL

curl -X POST '{baseUrl}/v1/beneficiaries/validation' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here are the {payload} examples for each result:

MTCH

{
  "beneficiaryName": "Sophie Weber",
  "beneficiaryIBAN": "DE28503399002244668800"
}

CMTC

{
  "beneficiaryName": "Sophy Weber",
  "beneficiaryIBAN": "DE28503399002244668800"
}

NMTC

{
  "beneficiaryName": "Alex Oak",
  "beneficiaryIBAN": "DE28503399002244668800"
}

NOAP

{
  "beneficiaryName": "Sophy Weber",
  "beneficiaryIBAN": "DE82503399000000062899"
}

SEPA Credit Transfer emission (SCTE)

The emulation of an SCTE in Sandbox occurs in 2 steps:

1. /v1/payouts – Create an SCTE (payoutTypeId of 1).
2. /simulation/payouts/{payoutId} – Update the payoutStatus to either accept or reject the payout in Sandbox.

Prerequisites

• You have created an active Beneficiary
• You have requested a Beneficiary Validation

1. Create the SCTE payout

Endpoint: /v1/payouts

CURL

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

Here is an example of {payload}:

JSON

{
	"walletId":{walletId},
	"beneficiaryId":{beneficiaryId},
	"beneficiaryValidationId":{beneficiaryValidationId},
	"amount":1000,
	"currency":"EUR"
}

Returns the Payout object, with its payoutStatus set to PENDING.

2. Update the SCTE payout in Sandbox

Endpoint: /simulation/payouts/{payoutId}

CURL

curl -X PUT '{baseUrl}/simulation/payouts/{payoutId}' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is a {payload} example.

JSON

{
  "payoutStatus": "VALIDATED" // or CANCELED
}

Returns the following information if successful.

JSON

{
  "payoutId": "12345",
  "payoutStatus": "VALIDATED",
  "payoutTypeId": 1,
  "payoutTag": "string"
}

Legacy SCTE validation emulation

Emulating SCTE in Sandbox only requires you use your regular payout endpoint. Any amount will return a PENDING status (and the Wallet Balance will be updated the day after around 10:30AM Paris time), except for amounts ending in 1.25.

For the later, retrieving the Payout shortly after will return a VALIDATED result, and the debited Wallet Balance is updated at the same time.

This method is now replaced by the /simulation/payouts/{payoutId} and will be discontinued in the near future.

Instant SEPA Credit Transfer emission (SCTE Inst)

Emulating SCTE in Sandbox only requires you use your regular payout endpoint.

Prerequisites:

• User must be KYC validated.
• Beneficiary userId and Wallet owner must be the same User.
• Necessary funds must be available on the debited Wallet.
• You have requested a Beneficiary Validation.

Mandatory parameters

Attribute	Type	Description
payoutTypeId	integer	Must be 3 for an SCTE Inst.
walletId	integer	The unique identifier of the debited Wallet.
beneficiaryId	integer	The unique identifier of the Beneficiary of the credit transfer. You must have created the Beneficiary object beforehand.
beneficiaryValidationId	integer	The unique identifier of the Beneficiary Validation of the credit transfer. You must have created the Beneficiary object beforehand.
amount	number	The amount of the credit transfer, which value defines the result of the emulation: VALIDATED – Provide an amount strictly below 1000.00 CANCELED – Provide an amount strictly above 1000.00
currency	string	The currency of the credit transfer. Must be EUR.

Request

CURL

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

Here is an example of {payload}:

JSON

{
    "payoutTypeId":3,
	"walletId":{walletId},
	"beneficiaryId":{beneficiaryId},
    "beneficiaryValidationId":{beneficiaryValidationId},
	"amount":800.00,
	"currency":"EUR"
}

Returns a Payout object.

JSON

{
    "payouts": [
        {
            "payoutId": "8929329c-b4a5-4bb9-b792-0e9e9d98xxxa",
            "payoutTag": "",
            "payoutStatus": "PENDING",
            "payoutTypeId": 3,
            "payoutType": "Instant Credit Transfer",
            "walletId": 3059736,
            "payoutDate": "2024-06-26 10:15:17",
            "walletEventName": "Name of the Wallet",
            "walletAlias": "name-of-the-wallet-667bcd66d546b",
            "userFirstname": "Alex",
            "userLastname": "Oak.validated",
            "userId": 965725,
            "beneficiaryId": 40963,
            "uniqueMandateReference": "",
            "bankaccountIBAN": "FR761679800001000030XXXXXX3",
            "label": "",
            "amount": "800.00",
            "currency": "EUR",
            "partnerFee": "0",
            "createdDate": "2024-06-26 10:15:17",
            "modifiedDate": "",
            "virtualIbanId": null,
            "virtualIbanReference": null,
            "codeStatus": "160001",
            "informationStatus": "PENDING",
            "supportingFileLink": "",
            "endToEndId":"2dbb81b26db94db3b530988b4189aad7",
            "reasonCode":null,
            "reasonDescription":null,
            "internationalBeneficiaryId": null,
            "quotationId": null,
            "metadata":null,
            "totalRows":null,
            "beneficiaryValidationId": null
        }
    ]
}

You can use the /v1/payouts/{payoutId} endpoint to view the updated payout with its VALIDATED status.

JSON

{
    "payouts": [
        {
            "payoutId": "8929329c-b4a5-4bb9-b792-0e9e9d98xxxa",
            "payoutTag": "",
            "payoutStatus": "VALIDATED",
            "payoutTypeId": 3,
            "payoutType": "Instant Credit Transfer",
            "walletId": 3059736,
            "payoutDate": "2024-06-26 10:15:17",
            "walletEventName": "Name of the Wallet",
            "walletAlias": "name-of-the-wallet-667bcd66d546b",
            "userFirstname": "Alex",
            "userLastname": "Oak.validated",
            "userId": 965725,
            "beneficiaryId": 40963,
            "uniqueMandateReference": "",
            "bankaccountIBAN": "FR761679800001000030XXXXXX3",
            "label": "",
            "amount": "800.00",
            "currency": "EUR",
            "partnerFee": "0",
            "createdDate": "2024-06-26 10:15:17",
            "modifiedDate": "",
            "virtualIbanId": null,
            "virtualIbanReference": null,
            "codeStatus": "160004",
            "informationStatus": "VALIDATED",
            "supportingFileLink": "",
            "endToEndId":"2dbb81b26db94db3b530988b4189aad7",
            "reasonCode":null,
            "reasonDescription":null,
            "internationalBeneficiaryId": null,
            "quotationId": null,
            "metadata":null,
            "totalRows":null,
            "beneficiaryValidationId": null
        }
    ]
}