Beneficiaries

@qonto/embed-sdk / beneficiaries

Variable: beneficiaries

const beneficiaries: object

The beneficiaries namespace contains all the client-side functions related to beneficiary operations. This version uses proxy-based authentication (proxyEndpointDescriptor) and is designed for browser environments.

For server-side operations using access tokens, import from '@qonto/embed-sdk/server/beneficiaries'.

It can be accessed like this:

import { beneficiaries } from `'@qonto/embed-sdk/beneficiaries'`;

Then, the beneficiaries object contains the functions to perform beneficiary operations:

await beneficiaries.getBeneficiaries({
  operationSettings: { proxyEndpointDescriptor }
});
await beneficiaries.getBeneficiary({
  beneficiarySettings: { beneficiaryId: '...' },
  operationSettings: { proxyEndpointDescriptor }
});

Note: The trustBeneficiaries function requires UI elements and is only available in the client-side version.

Type declaration

addBeneficiary()

addBeneficiary: (addBeneficiaryParams) => Promise<Beneficiary>

Adds a new beneficiary in the current user’s account.

Client-side only - Uses proxy-based authentication. For server-side operations, import from '@qonto/embed-sdk/server/beneficiaries'.

Parameters

addBeneficiaryParams

BeneficiaryClientParams<NewBeneficiary>

An object containing:

• beneficiarySettings: An object with the new beneficiary details. Requires at least the name and iban properties to be present.
• operationSettings: An object with operation-level settings such as proxyEndpointDescriptor (required), idempotencyKey, and other optional parameters.

Returns

Promise<Beneficiary>

A promise that resolves to the created beneficiary.

Throws

InvalidParametersError If any required property is missing or invalid, or if proxyEndpointDescriptor is not provided.

Throws

EmbedApiError If the API request fails or returns an error.

getBeneficiaries()

getBeneficiaries: (getBeneficiariesParams?) => Promise<GetBeneficiariesResponse>

Fetches the list of beneficiaries for the current user.

Client-side only - Uses proxy-based authentication. For server-side operations, import from '@qonto/embed-sdk/server/beneficiaries'.

Parameters

getBeneficiariesParams?

BeneficiaryClientParams<never>

An object containing:

• operationSettings: An object with operation-level settings such as proxyEndpointDescriptor (required), paginationSettings, and other optional parameters.

Returns

Promise<GetBeneficiariesResponse>

A promise that resolves to an array of beneficiaries and a meta object containing pagination state.

Throws

InvalidParametersError If proxyEndpointDescriptor is not provided.

Throws

EmbedApiError If the API request fails or returns an error.

getBeneficiary()

getBeneficiary: (getBeneficiaryParams) => Promise<Beneficiary>

Fetches a single beneficiary of the current user by ID.

Client-side only - Uses proxy-based authentication. For server-side operations, import from '@qonto/embed-sdk/server/beneficiaries'.

Parameters

getBeneficiaryParams

BeneficiaryClientParams<{ beneficiaryId: string; }>

An object containing:

• beneficiarySettings: An object with the beneficiaryId property (string).
• operationSettings: An object with operation-level settings such as proxyEndpointDescriptor (required).

Returns

Promise<Beneficiary>

A promise that resolves to a beneficiary.

Throws

InvalidParametersError If the beneficiaryId parameter is not a string or is missing, or if proxyEndpointDescriptor is not provided.

Throws

EmbedApiError If the API request fails or returns an error.

trustBeneficiaries()

trustBeneficiaries: (trustBeneficiariesParams) => Promise<Beneficiary[]>

Trusts a list of beneficiaries in the current user’s account.

Client-side only - This function requires UI elements (iframe/SCA) and is only available in the client-side version. It is not available in the server-side API.

Parameters

trustBeneficiariesParams

BeneficiaryClientParamsWithUI<{ beneficiaryIds: string[]; }>

An object containing:

• beneficiarySettings: An object with the list of beneficiary IDs to trust (e.g., { beneficiaryIds: string[] }).
• operationSettings: An object with operation-level settings such as accessToken, stagingToken, uiParentElementId, and other optional parameters.

Returns

Promise<Beneficiary[]>

A promise that resolves to an array of trusted beneficiaries.

Throws

AuthenticationError If the access token is invalid or missing. Ensure initialize has been called before using this function if you are not passing the access token.

Throws

InvalidParametersError If the beneficiaryIds parameter is not an array of strings or is missing.

Throws

EmbedApiError If the API request fails or returns an error.

untrustBeneficiaries()

untrustBeneficiaries: (untrustBeneficiariesParams) => Promise<Beneficiary[]>

Untrusts a list of beneficiaries in the current user’s account.

Client-side only - Uses proxy-based authentication. For server-side operations, import from '@qonto/embed-sdk/server/beneficiaries'.

Parameters

untrustBeneficiariesParams

BeneficiaryClientParams<{ beneficiaryIds: string[]; }>

An object containing:

• beneficiarySettings: An object with the list of beneficiary IDs to untrust (e.g., { beneficiaryIds: string[] }).
• operationSettings: An object with operation-level settings such as proxyEndpointDescriptor (required).

Returns

Promise<Beneficiary[]>

A promise that resolves to an array of untrusted beneficiaries.

Throws

InvalidParametersError If the beneficiaryIds parameter is not an array of strings or is missing, or if proxyEndpointDescriptor is not provided.

Throws

EmbedApiError If the API request fails or returns an error.

updateBeneficiary()

updateBeneficiary: (updateBeneficiaryParams) => Promise<Beneficiary>

Update any of the editable properties of a beneficiary in the current user’s account by ID.

Client-side only - Uses proxy-based authentication. For server-side operations, import from '@qonto/embed-sdk/server/beneficiaries'.

Parameters

updateBeneficiaryParams

BeneficiaryClientParams<EditableBeneficiaryProperties>

An object containing:

• beneficiarySettings: An object that contains a mandatory beneficiary ID and any of the editable properties of a beneficiary, which are name, email and activityTag.
• operationSettings: An object with operation-level settings such as proxyEndpointDescriptor (required), mfaPreference, idempotencyKey, and other optional parameters.

Returns

Promise<Beneficiary>

A promise that resolves to the updated beneficiary.

Throws

InvalidParametersError If the beneficiary ID is missing or if none of the editable properties (name, email, activityTag) are provided or are of incorrect type, or if proxyEndpointDescriptor is not provided.

Throws

EmbedApiError If the API request fails or returns an error.