# Beneficiaries

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

SEPA Transfers Beneficiary
Info icon

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:

Thumbs icon

Best practice – Beneficiaries must be created beforehand in the specific case of 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 duplicated or associated to a parent user.

# Structure

# 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 Beneficary can be used to send SCTE
Info icon

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's countries. If the Beneficiary bic or iban country code is not a SEPA Scheme country, an HTTP error will be returned.

books icon

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 (opens new window) 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.
Info icon

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:

Here is an example of {payload}:

Bulb icon

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.

Bulb icon

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 Description 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
Updated on: 4/24/2024, 12:38:33 PM