Appearance
Are you an LLM? You can read better optimized documentation at /guide/transfers/beneficiaries.md for this page in Markdown format
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 totrue
). - Automatically when paying with a SEPA Direct Debit (
usableForSct
set tofalse
).
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"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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 |
|
sddB2bWhitelist.walletId | integer | Defines which Wallet can be debited by the Beneficiary. |
isActive | boolean | Toggle the Beneficiary (for both SDDR and SCTE):
|
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:
bash
curl -X POST '{baseUrl}/v1/beneficiaries' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
1
2
3
4
2
3
4
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
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
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
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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:
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
bash
curl -X POST '{baseUrl}/v1/beneficiaries/validation' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
1
2
3
4
2
3
4
Here is a {payload}
example:
json
{
"beneficiaryName": "Alex Oak",
"beneficiaryIBAN": "DE15801640509362882000"
}
1
2
3
4
2
3
4
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"
}
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
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 |