Beneficiaries

Beneficiaries are bank accounts that are outside your Treezor ecosystem (as opposed to Wallets). They are therefore the target of payouts (SEPA Direct Debit, SEPA Credit Transfers, and International Transfers), and are necessarily attached to a User.

SEPA Beneficiaries

Information – Treezor is connected to the SEPA STEP2 transfer network

This network is used by all European banks, and a few other outside of Europe. To transfers fund in and out, both parties must be in same network.

When making a payout (outgoing funds), Beneficiaries are created:

• Manually prior to emitting a SEPA Credit Transfer (usableForSct set to true).
• Automatically when paying with a SEPA Direct Debit (usableForSct set to false).

Note – Beneficiaries must be created before for B2B SDDR

The Beneficiary sddB2bWhitelist.uniqueMandateReference field must be populated once the User receives their UMR from their creditor. If not, the SDDR will be declined upon reception.

A Beneficiary can only be associated to a single user at a time. If multiple Users need to send/receive funds to/from the same identical Beneficiary, it can either be duplicated or associated to a parent user.

Beneficiary object

JSON

{
	"tag": "string",
	"userId": 0,
	"nickName": "string",
	"name": "string",
	"address": "string",
	"iban": "string",
	"bic": "string",
	"sepaCreditorIdentifier": "string",		
	"sddB2bWhitelist": [
		{
			"uniqueMandateReference": "nn888890886DGFIP2020045229KFDZBOAB",	
			"isRecurrent": true,
			"walletId": 0
		}
	],
	"sddCoreBlacklist": [
		"string"
	],
	"usableForSct": false,
	"sddCoreKnownUniqueMandateReference": [
		"string"
	],
	"isActive": true,
	"createdDate": "string",
	"modifiedDate": "string"
}

Key attributes

Below are some of the most important Beneficiary attributes.

Attribute	Type	Description
nickName	string	Field that you are free to populate to identify the Beneficiary.
iban	string	The IBAN of the Beneficiary.
bic	string	The BIC of the Beneficiary.
name	string	The name of the Beneficiary (see charset restrictions below).
sepaCreditorIdentifier	string	The SCI.
uniqueMandateReference	string	The UMR.
sddCoreBlacklist	array	List of UMR that are revoked. Core scheme only.
sddCoreKnownUniqueMandateReference	array	List of all UMR that have debited the User
sddB2bWhitelist.uniqueMandateReference	array	List of UMR that are allowed to debit the Wallet. B2B scheme only.
sddB2bWhitelist.isRecurrent	boolean	true – Allows multiple debits for this Beneficiary false – Allows a single debit for this Beneficiary
sddB2bWhitelist.walletId	integer	Defines which Wallet can be debited by the Beneficiary.
isActive	boolean	Toggle the Beneficiary (for both SDDR and SCTE): true – Enables the Beneficiary false – Disables the Beneficiary
usableForSct	boolean	Defines if this Beneficiary can be used to send SCTE

Information – Rules for the name attribute

• Must be at least 1-character long, but not a single space character.
• Can only contain the following characters: a-z, A-Z, 0-9, /, -, ?, :, (, ), ., ,, ', + and  (space).

Accepted countries

SEPA Transfers are only supported for beneficiaries domiciled in one of the SEPA Scheme countries. If the Beneficiary bic or iban country code is not a SEPA Scheme country, an HTTP error will be returned.

Reading – EPC list of Countries in the SEPA Scheme

You may find the list of accepted BIC and IBAN countries (and the corresponding country codes) in the EPC list of Countries in the SEPA Schemes document.

Creation

Attribute	Type	Description
userId	string	The unique identifier of the User to which the Beneficiary is attached.
name	string	The name of the Beneficiary (see charset restrictions below).
iban	string	The IBAN of the Beneficiary.
bic	string	The BIC of the Beneficiary.

Information – Rules for the name attribute

• Must be at least 1-character long, but not a single space character.
• Can only contain the following characters: a-z, A-Z, 0-9, /, -, ?, :, (, ), ., ,, ', + and (space).

Example

To create a Beneficiary, use the following request:

CURL

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

Here is an example of {payload}:

JSON

{
	"userId":123456,
	"name":"Alex Oak",
	"tag":"aoak-1982",
	"nickName":"A Oak checking",
	"address":"Woods Bank",
	"iban":"FR7616798000010000012345678",
	"bic":"TRZOFR21XXX",
	"usableForSct":true
}

Tip – Make sure you use a real IBAN

If the provided IBAN is incorrect, an error is returned and the Beneficiary is not created.

Returns a Beneficiary object, with its beneficiaryId (11XXXX8). It can be used to initiate an outgoing transfer (SCTE) right away.

JSON

{
	"id": 11XXXX8,
	"tag": "aoak-1982",
	"userId": 22XXXX6,
	"nickName": "A Oak checking",
	"name": "STE A",
	"address": "Woods Bank",
	"iban": "2XXXXXXXX X X 7XXXXXXXXX5 X X 75XXXXXXXX6 X X 1XXXXX4",
	"bic": "BNPAFRPP",
	"sepaCreditorIdentifier": "",
	"sddB2bWhitelist": [],
	"sddCoreBlacklist": [],
	"usableForSct": true,
	"sddCoreKnownUniqueMandateReference": [],
	"isActive": true
}

Treezor also sends a beneficiary.create webhook.

Tip – Useful information about the returned object

• usableForSct indicates if the beneficiary can be used to initiate outgoing transfers (SCTE).
• iban is returned in an encoded format and cannot be read directly.

Beneficiary validation (VoP)

The Verification of Payee (VoP) is a legal obligation for the initiator of a SEPA transfer to verify that the beneficiary’s name and IBAN match with the information registered at their bank.

The beneficiary validation endpoint allows you to initiate a Verification of Payee request and must be used prior to any:

• SEPA Credit Transfer
• SEPA Instant Credit Transfer

A given beneficiaryValidationId can only be used once and expires 72 hours after the validation request.

Therefore, you must request a new beneficiary validation for each payout, except in specific use cases such as scheduled and mass payouts.

Information – Verification of Payee exemptions

Some payouts are exempted of VoP. Contact Treezor to find out if your model is eligible and how to implement the exemption.

Verification of Payee process

When a payout falls under the Verification of Payee obligation, you must expose to your user the result of the verification with mandatory messages before they decide whether they want to proceed with the payout.

Key attributes

Attribute	Type	Description
beneficiaryName	string	The complete name of the beneficiary the end user wants to reach, as defined in the Beneficiary object. This beneficiaryName will be compared to the name of the account holder as registered with the responding bank.
beneficiaryIBAN	string	The IBAN of the beneficiary.
recurrenceType	string	If you've put in place your own system to schedule payments at a later date (one-time or recurring), you must set the recurrence type to scheduled.

API – API Reference available

For a complete list of Beneficiary Validation attributes, check the Beneficiaries section of the API Reference.

Below is some key information returned in the vop object.

Validation result (vopResult)

Value	Result description	Mandatory message to display to the end user
CMTC	Close Match The beneficiary details are similar to the information provided by the end user, but there are some minor discrepancies.	”The name of the beneficiary associated with this IBAN partially matches the name you provided. The IBAN is registered under the name: {matchedName}. If you validate your transfer, it could be credited to the account of another beneficiary. In this case, TREEZOR, our partner payment service provider, cannot be held responsible.”
MTCH	Match The beneficiary details provided by the responding bank align with the details the information provided by the end user.	“The name of the beneficiary associated with this IBAN fully matches the name you provided.”
NMTC	No Match There is a discrepancy between the beneficiary details and the information provided by the end user.	“The name of the beneficiary associated with this IBAN is different from the name you provided. If you validate your transfer, it could be credited to the account of another beneficiary. In this case, TREEZOR, our partner payment service provider, cannot be held responsible.”
NOAP	Verification Not Possible The verification of payee couldn't occur. The reason is specified in the vopReasonCode field.	“The name of the beneficiary associated with this IBAN could not be verified. If you validate your transfer, it could be credited to the account of another beneficiary.”

Reason codes (vopReasonCode)

Value	Description
9001	The bank or payment service provider is not reachable.
9007	The account does not exist.
9008	The account is closed.
9009	Technical error.
9010	Other reason.

Request example

Endpoint: /v1/beneficiaries/validation

CURL

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

Here is a {payload} example:

JSON

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

Returns the following beneficiary validation object if successful.

JSON

{
  "beneficiaryValidationId": "f8e4a7b2-c1d3-4e5a-8b0f-9c2d1e0a3b5c",
  "createdDate": "2025-08-29T16:52:27.379Z",
  "vop": {
    "result": "CMTC",
    "matchedName": "Axel Oak",
    "reasonCode": "",
    "recurrenceType": "default"
  }
}

The beneficiaryValidationId is to be included in the /v1/payouts request within 72 hours after the validation request.

Endpoints

SEPA Beneficiaries

Endpoint	Scope
/v1/beneficiaries Create a Beneficiary	read_write
/v1/beneficiaries Search for Beneficiaries	read_only
/v1/beneficiaries/{beneficiaryId} Retrieve a Beneficiary	read_only
/v1/beneficiaries/{beneficiaryId} Update a Beneficiary	read_write

Beneficiary validation

Endpoint	Scope
/v1/beneficiaries/validation Request Beneficiary Validation	read_write
/v1/beneficiaries/validation/{beneficiaryValidationId} Get Beneficiary Validation	read_only