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.

Endpoints

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