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 transfer funds in and out, both parties must be in the 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 beforehand 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 Beneficiary, it can either be duplicated or associated with a parent user.

Beneficiary object

JSON

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).

Request example

/v1/beneficiaries

CURL

bash

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

Here is an example of {payload}:

JSON

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

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 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 (`result`)

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 `reasonCode` 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.”
`NOAP`	Verification Unavailable The verification of payee couldn't occur due to a technical error (`reasonCode`: `9009`).	“The beneficiary name match check is unavailable. If you validate your transfer, it could be credited to the account of another beneficiary.”

Tip – Mock values available in Sandbox

You can emulate different results using the payloads available in the Beneficiary validation result article.

Reason codes (`reasonCode`)

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

bash

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

Here is a {payload} example:

JSON

json

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

Returns the following beneficiary validation object if successful.

JSON

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.

Tip – Mock values available in Sandbox

You can emulate different results using the payloads available in the Beneficiary validation result article.

Received Verification of Payee

In the same way that you must verify the beneficiary of an SCT payout, any bank sending funds to a Treezor Wallet through SEPA Credit Transfer must comply with the Verification of Payee (VoP).

However, Treezor doesn't manage nor host the matching mechanism. When receiving a VoP query for a given IBAN, Treezor returns the account information to its RVM (Routing and/or Verification Mechanism).

If the wallet and user both exist, Treezor checks the user KYC Validation status in order to only share information for users whose:

kycLevel is REGULAR or STRONG
kycReview is VALIDATED

In that case, Treezor sends to the RVM the wallet owner's:

firstname and lastname (Physical Users)
legalName (Legal Entities and Self-employed Users)

International Beneficiaries Beta

The International Beneficiary object represents the external account targeted by International Transfers payouts.

In order to emit an International Transfer, an international beneficiary must be created at least 48 hours before.

Creating an international beneficiary is a 2-step process:

Retrieve requirements – Get the necessary information to create the international beneficiary.
Create international beneficiary – Create the beneficiary account based on the previously obtained information.

Retrieve requirements

Banking requirements vary heavily depending on the country, currency, and amount. This endpoint enables you to collect the information required to create an international beneficiary.

Query parameters

Attribute	Type	Description
`sourceCurrency`	string	The initial currency of the emitted transfer. As of today, can only be `EUR`.
`targetCurrency`	string	The currency for the beneficiary wallet.
`amount`	string	The amount to be emitted (float).

Request example

Endpoint: /v1/internationalBeneficiaries/requirements

CURL

bash

curl -X POST '{baseUrl}/v1/internationalBeneficiaries/requirements?sourceCurrency=EUR&targetCurrency=USD&amount=1000' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

The response varies depending on the requirements for the beneficiary. Here is an example:

JSON

json

[
  {
    "fields": [
      {
        "group": [
          {
            "example": "",
            "key": "legalType",
            "name": "Recipient type",
            "refreshRequirementsOnChange": true,
            "type": "select",
            "valuesAllowed": [
              {
                "key": "PRIVATE",
                "name": "Person"
              },
              {
                "key": "BUSINESS",
                "name": "Business"
              }
            ]
          }
        ],
        "name": "Recipient type"
      },
      {
        "group": [
          {
            "example": "Choose recipient's bank",
            "key": "bankCode",
            "name": "Bank name",
            "refreshRequirementsOnChange": false,
            "type": "select",
            "valuesAllowed": [
              {
                "key": "",
                "name": "Choose recipient's bank"
              },
              {
                "key": "ABBMMAMC",
                "name": "Al Barid Bank [ABBMMAMC]"
              },
              {
                "key": "ARABMAMC",
                "name": "Arab Bank Plc. [ARABMAMC]"
              },
              {
                "key": "AIBSMAMT",
                "name": "Attijari International Bank S.A. [AIBSMAMT]"
              },
              {
                "key": "BCMAMAMC",
                "name": "Attijariwafa Bank [BCMAMAMC]"
              },
              {
                "key": "BCPOMAM10MS",
                "name": "BANQUE POPULAIRE OUARZAZATE [BCPOMAM10MS]"
              },
              {
                "key": "BSABMAMC",
                "name": "Banco De Sabadell, S.A. [BSABMAMC]"
              },
              {
                "key": "BKAMMAMR",
                "name": "Bank Al-Maghrib [BKAMMAMR]"
              },
              {
                "key": "BCPOMAMCYSR",
                "name": "Banque Centrale Populaire - Casablanca [BCPOMAMCYSR]"
              },
              {
                "key": "BCPOMAMC",
                "name": "Banque Centrale Populaire [BCPOMAMC]"
              },
              {
                "key": "BMCEMAMC",
                "name": "Banque Marocaine Du Commerce Exterieur [BMCEMAMC]"
              },
              {
                "key": "BMCIMAMC",
                "name": "Banque Marocaine Pour Le Commerce Et L'Industrie [BMCIMAMC]"
              },
              {
                "key": "BCPOMAMCCES",
                "name": "Banque Populaire Agadir [BCPOMAMCCES]"
              },
              {
                "key": "BCPOMAMCALH",
                "name": "Banque Populaire Al Hoceima [BCPOMAMCALH]"
              },
              {
                "key": "BCPOMAMCBNM",
                "name": "Banque Populaire Beni Mellal [BCPOMAMCBNM]"
              },
              {
                "key": "BCPOMAMCBRK",
                "name": "Banque Populaire Berkane [BCPOMAMCBRK]"
              },
              {
                "key": "BCPOMAMCCAS",
                "name": "Banque Populaire Casa-Anfa [BCPOMAMCCAS]"
              },
              {
                "key": "BCPOMAMCELJ",
                "name": "Banque Populaire El Jadida [BCPOMAMCELJ]"
              },
              {
                "key": "BCPOMAMCFES",
                "name": "Banque Populaire Fes [BCPOMAMCFES]"
              },
              {
                "key": "BCPOMAMCGHA",
                "name": "Banque Populaire Gharb [BCPOMAMCGHA]"
              },
              {
                "key": "BCPOMAMCLAY",
                "name": "Banque Populaire Laayoune [BCPOMAMCLAY]"
              },
              {
                "key": "BCPOMAMCMKH",
                "name": "Banque Populaire Marrakech [BCPOMAMCMKH]"
              },
              {
                "key": "BCPOMAMCMEK",
                "name": "Banque Populaire Meknes [BCPOMAMCMEK]"
              },
              {
                "key": "BCPOMAMCNAD",
                "name": "Banque Populaire Nador [BCPOMAMCNAD]"
              },
              {
                "key": "BCPOMAMCOUJ",
                "name": "Banque Populaire Oujda [BCPOMAMCOUJ]"
              },
              {
                "key": "BCPOMAMCRAB",
                "name": "Banque Populaire Rabat [BCPOMAMCRAB]"
              },
              {
                "key": "BCPOMAMCSAF",
                "name": "Banque Populaire Safi [BCPOMAMCSAF]"
              },
              {
                "key": "BCPOMAMCTAT",
                "name": "Banque Populaire Tanger [BCPOMAMCTAT]"
              },
              {
                "key": "BCPOMAM10MV",
                "name": "Banque Populaire Taza [BCPOMAM10MV]"
              },
              {
                "key": "BCPOMAM10MW",
                "name": "Banque Populaire Tetouan [BCPOMAM10MW]"
              },
              {
                "key": "BCPOMAM10MY ",
                "name": "Banque Populaire Tinznit [BCPOMAM10MY ]"
              },
              {
                "key": "CAFGMAMCXXX",
                "name": "CFG Bank [CAFGMAMCXXX]"
              },
              {
                "key": "CADGMAMR",
                "name": "Caisse De Depot Et De Gestion [CADGMAMR]"
              },
              {
                "key": "CAFGMAMC",
                "name": "Casablanca Finance Markets [CAFGMAMC]"
              },
              {
                "key": "RDGCMAMR",
                "name": "Cdg Capital [RDGCMAMR]"
              },
              {
                "key": "CITIMAMC",
                "name": "Citibank Maghreb [CITIMAMC]"
              },
              {
                "key": "CNCAMAMR",
                "name": "Credit Agricole Du Maroc [CNCAMAMR]"
              },
              {
                "key": "CDMAMAMC",
                "name": "Credit Du Maroc [CDMAMAMC]"
              },
              {
                "key": "CIHMMAMC",
                "name": "Credit Immobilier Et Hotelier [CIHMMAMC]"
              },
              {
                "key": "GOCPMAMC",
                "name": "Groupe Ocp [GOCPMAMC]"
              },
              {
                "key": "CAIXMAMC",
                "name": "La Caixa, Succursale Maroc [CAIXMAMC]"
              },
              {
                "key": "MEDCMAMC",
                "name": "Mediafinance [MEDCMAMC]"
              },
              {
                "key": "SGMBMAMC",
                "name": "Societe Generale Marocaine De Banques [SGMBMAMC]"
              },
              {
                "key": "SGTGMAMC",
                "name": "Societe Generale Tanger Offshore [SGTGMAMC]"
              },
              {
                "key": "UMABMAMC",
                "name": "Union Marocaine De Banques [UMABMAMC]"
              }
            ]
          }
        ],
        "name": "Bank name"
      },
      {
        "group": [
          {
            "example": "123456789012345678901234",
            "key": "accountNumber",
            "maxLength": 24,
            "minLength": 24,
            "name": "Account number (RIB)",
            "refreshRequirementsOnChange": false,
            "type": "text",
            "validationRegexp": "^\\d{24}$",
            "valuesAllowed": []
          }
        ],
        "name": "Account number (RIB)"
      }
    ],
    "title": "Local bank account",
    "type": "morocco"
  }
]

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240

Creation

Using the information gathered in the previous step, you can now create your international beneficiary.

Parameters

Attribute	Type	Description
`userId`	string	The unique identifier of the User to which the International Beneficiary is attached.
`name`	string	The name of the Beneficiary.
`type`	string	Specifies the system used for the transaction.
`currency`	string	Specifies the target attached to the international beneficiary (target currency).
`address`	object	All the sub-parameters are required except for `state`, which is required for specific countries only.
`details`	object	Information to provide depending on the result of the requirements request.

API – API Reference available

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

Request example

Endpoint: /v1/internationalBeneficiaries

CURL

bash

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

Here is an example of {payload}:

JSON

json

{
   "userId": 123456,
   "name": "John Doe",
   "nickName": "John Doe",
   "type": "ACH",
   "currency": "USD",
   "address": {
     "streetName": "Liberty Island",
     "buildingNumber": "1",
     "city": "New York",
     "state": "New York",
     "postalCode": "10004",
     "country": "United States"
   },
   "details": {
     "recipientType": "individual",
     "routingNumber": "021000021",
     "accountNumber": "1234567890",
     "accountType": "savings"
   }
}

Returns the International Beneficiary object. After 48 hours, it can be used to initiate an outgoing international transfer.

JSON

json

{
  "internationalBeneficiaries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": 123456,
      "name": "John Doe",
      "nickName": "John Doe",
      "type": "ACH",
      "currency": "USD",
      "address": {
        "streetName": "Liberty Island",
        "buildingNumber": "1",
        "city": "New York",
        "state": "New York",
        "postalCode": "10004",
        "country": "United States"
      },
      "details": {
        "recipientType": "individual",
        "routingNumber": "021000021",
        "accountNumber": "1234567890",
        "accountType": "savings"
      },
      "status": "VALIDATED",
      "createdDate": "2026-01-23 12:34:12",
      "modifiedDate": "2026-01-27 04:17:22"
    }
  ]
}

Treezor also sends an internationalBeneficiary.create webhook.

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`

International Beneficiaries

Endpoint	Scope
`/v1/internationalBeneficiaries/requirements` Retrieve international beneficiaries requirements	`read_only`
`/v1/internationalBeneficiaries` Create international beneficiary	`read_write`
`/v1/internationalBeneficiaries/{internationalBeneficiaryId}` Retrieve international beneficiary	`read_only`

Beneficiaries ​

SEPA Beneficiaries ​

Beneficiary object ​

Key attributes ​

Accepted countries ​

Creation ​

Request example ​

Beneficiary validation (VoP) ​

Verification of Payee process ​

Key attributes ​

Validation result (result) ​

Reason codes (reasonCode) ​

Request example ​

Received Verification of Payee ​

International Beneficiaries Beta ​

Retrieve requirements ​

Query parameters ​

Request example ​

Creation ​

Parameters ​

Request example ​

Endpoints ​

SEPA Beneficiaries ​

Beneficiary validation ​

International Beneficiaries ​

Beneficiaries

SEPA Beneficiaries

Beneficiary object

Key attributes

Accepted countries

Creation

Request example

Beneficiary validation (VoP)

Verification of Payee process

Key attributes

Validation result (`result`)

Reason codes (`reasonCode`)

Request example

Received Verification of Payee

International Beneficiaries Beta

Retrieve requirements

Query parameters

Request example

Creation

Parameters

Request example

Endpoints

SEPA Beneficiaries

Beneficiary validation

International Beneficiaries