Beneficiaries and Payout Methods

OverviewCopied!

Beneficiaries and their associated Payout Methods play a crucial role in the transaction flow within the platform. This document provides an overview of how Beneficiaries, as well as their Payout Methods (such as bank accounts, cards, electronic wallets, or cash pickup locations), are managed. It covers their association with Account and Program entities, regulatory compliance checks, and statuses.

PurposeCopied!

Beneficiaries can have multiple Payout Methods associated with them, meaning that funds can be sent to different accounts or through different mechanisms. For instance, a single Beneficiary may receive funds via direct bank deposit, mobile wallet, card, or a cash pickup location. This flexibility in Payout Methods provides Beneficiaries with diverse options for accessing the funds they receive.

Entity hierarchyCopied!

Beneficiaries are established as subordinate entities under Account entities, and Payout Methods entities are further established as children of Beneficiaries, as illustrated below:

Account (Consumer, Business) -> Beneficiaries -> Payout Methods

BeneficiaryCopied!

Beneficiaries serve as the focal point for the end receipt of both international and domestic transactions.

A Beneficiary is typically an individual or entity that is designated to receive funds through various transaction types, such as international or domestic transfers.

Beneficiary creation

Beneficiaries are created through the Create beneficiary endpoint. When a new Beneficiary is registered on the platform, the system prompts for the submission of personal information related to the recipient. This encompasses particulars such as the Beneficiary's name, the currency for the transaction, and the country where the Beneficiary is officially residing.

It is imperative to note that all Beneficiaries are subjected to Sanctions screening, in compliance with regulatory requirements. This screening takes place after a Beneficiary is created and is processed asynchronously within the system. Once all compliance checks have passed, the Beneficiary is placed in the ACTIVE status.

Best practices for Beneficiary data

Transactions involving are subject to validation checks and data quality controls to safeguard against the risks posed by incomplete or inaccurate data. Vague, unclear or partial information in data fields may lead to delays or Rejections in processing Payments. To avoid these, please ensure that all required information and data fields are formatted correctly and accurately.

For transactions to individual Beneficiaries, the name must:

Be provided in full: First Name, Middle Name, Last Name, Second Last Name (if applicable);
Between 2-60 characters;
Not contain special characters (e.g., !”#$%?:;-_*=/);
Not contain company identifiers (e.g., LLC, LLP);
Not contain initials, acronyms or single character names;
Do not provide and in the first or last name field. The Transaction should be sent to a single person, not multiple people.

Examples of High-quality Beneficiary data:

John Smith
John Michael Smith

Examples of Low-quality Beneficiary data:

J Smith
John Smith LLP

For transactions to business Beneficiaries, entity names must:

Have the full legal entity name without abbreviations except for those of standard suffixes (e.g., LLP, LLC, Ltd.);
Follow alphanumeric format between 2-60 characters;

Examples of High-quality Beneficiary data:

ABC Company Ltd.
X2 Communication Services Limited
Fruits 100 Ltd.

Examples of Low-quality Beneficiary data:

12245678

Beneficiary Address

For transactions, the Beneficiary Address should:

Contain the full address, including the country;
No PO boxes
Not contain null or missing values.

Acceptable Example:Copied!

20 Longleat Drive, Baltimore 12345, Maryland, United States

Rejected Example:Copied!

12345, Baltimore, Maryland, United States

Beneficiary update

In alignment with compliance protocols, Beneficiaries have the flexibility to update their personal information at any stage, including when their status is ACTIVE. This amendment permits the modification of key details such as the beneficiary's name, phone number, date of birth, label, and external_ID. Following these updates, a re-evaluation for sanctions will be automatically initiated.

Beneficiary types

There are two types of Beneficiaries in the system, LOCAL and INTERNATIONAL.

A LOCAL beneficiary is a consumer or business who will receive funds within the same country with the same type of currency (e.g. USD). If the consumer or business are part of the same Alviere Program, they can use P2P, if enabled, to transfer funds - see the Send funds API.

An INTERNATIONAL Beneficiary is an consumer or business who will receive funds outside the sender’s country and it usually involves sending funds in a different currency known as remittance.

Note that it is possible for the same consumer to have multiple Beneficiaries in system even though they are the same individual. This scenario would occur when the individual needs to receive funds while LOCAL or when abroad making it INTERNATIONAL. For example: Jane, who lives in Florida wants to send her daughter, Jennifer, who lives in Texas, some money. In the case, Jennifer would be a LOCAL Beneficiary. Now let’s say Jennifer is traveling to Mexico on vacation and needs cash to make a purchase for her mom, Jane. Jane can send Jennifer the funds but she would need to create a new Beneficiary for Jennifer with the type of INTERNATIONAL since she in is Mexico. This would also involve a remittance where US dollars are converted to Pesos that Jennifer can pick up at a nearby location to make the purchase.

Beneficiary statuses

Beneficiaries within the platform are assigned statuses that indicate either their position in the validation process or their conclusive status.

Below is a comprehensive list of the various statuses that a Beneficiary may be in within the platform:

Status	Description
`CREATED`	The Beneficiary record has been created and initiated its validation process.
`ACTIVE`	The beneficiary is active, and funds can be remitted to them.
`DELETED`	The Beneficiary has been deleted upon the customer's request. This status is irreversible.
`PROCESSING`	The Beneficiary is undergoing validation for Sanctions screening.
`PENDING_USER`	The Beneficiary requires the customer to supply additional information.
`MANUAL_REVIEW`	The Beneficiary is subjected to a manual review by Alviere's compliance department.
`REJECTED`	The Beneficiary has been rejected by Alviere's compliance department.

The status_reasonattribute elaborates on the reason for the Beneficiary’s current status. It is particularly crucial when additional information or actions are required for moving the Beneficiary through the validation process.

The table below summarizes possible values for status_reason and their descriptions:

Status Reason	Applicable status(es)	Description
`STAGE_VALIDATION`	`MANUAL_REVIEW`	The compliance validation for the Beneficiary failed, requiring a manual review.
`INVALID_NAME`	`PENDING_USER`	The provided first and/or last name is invalid, requiring re-submission.
`SANCTIONED_USER`	`REJECTED`	The Beneficiary has been rejected due to sanctions.
`CUSTOM`	`REJECTED`	The Beneficiary has been rejected for reasons other than sanctions.

Beneficiary address

In order to ensure accurate and efficient processing of transactions, it is essential to provide the correct beneficiary address information. The requirements for beneficiary addresses vary by country, encompassing both mandatory and optional fields. Below is a comprehensive table detailing the specific address requirements for countries supported by our platform. This table outlines the character limits and format specifications needed for each field, ensuring compliance with regional regulations and standards.

Country	Line 1	Line 2	City	State	Postal code	Country code
Argentina	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^[A-Z]?\d{4}[A-Z]{0,3}$	ARG
Bolivia	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	not used	BOL
Brazil	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2 letter ISO code	mandatory, ^[0-9]{5}-[0-9]{3}$	BRA
Chile	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^\d{7}$	CHL
Colombia	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^\d{6}$	COL
Ecuador	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^\d{6}$	ECU
Haiti	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^HT\d{4}$	HTI
Peru	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^\d{5}$	PER
Uruguay	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^\d{5}$	URY
Venezuela	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^\d{4}$	VEN
Paraguay	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, 2-128 characters	optional, ^\d{6}$	PRY
United States of America	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^[A-Z]{2}$	mandatory, ^.{5,9}$	USA
Mexico	mandatory, 2-128 characters	non-mandatory, 2-128 characters	mandatory, 2-128 characters	mandatory, ^[A-Z]{2-4}$	mandatory, ^.{5,9}$	MEX

Payout MethodsCopied!

These represent the different options through which the Beneficiaries can receive the funds or resources. Being children of Beneficiaries means that these Payout Methods are associated specifically with each Beneficiary.

Payout Method types

Types of Payout Methods include:

Bank account: The funds are transferred directly to the Beneficiary's bank account.

Cash pickup location: The Beneficiary can collect cash in person from a designated location, such as a money transfer service or retail outlet.

Electronic wallet (e-wallet): The Beneficiary receives funds in a digital wallet, which can be used for online transactions or converted to physical cash.

Card: The funds are transferred directly to the bank account that is tied to the Beneficiary's debit card, allowing them to access the funds through their card.

Address: Custom payout location that is not limited to the platform's supported cash pickup locations.

The availability of specific Payout Methods is dependent on the configuration settings of the program they are associated with.

Payout Method creation

The Create payout method endpoint, allows for the creation of a new Payout Method within the system. It is mandatory to associate the Payout Method with a specific Beneficiary by supplying the Beneficiary's universally unique identifier (UUID). The Payout Method will be created as a child entity under the designated Beneficiary.

In addition a Payout Method can be set as primary, meaning that this Payout Method will be the default for this Beneficiary.

Payout Method update

Due to compliance requirements, the account information associated with Payout Methods is immutable once the Payout Method has been created. However, certain non-account-related properties can still be modified. These properties include:

external_id: An identifier that can be used for referencing the Payout Method in external systems.
label: A human-readable label or description for the Payout Method.
primary: A boolean flag indicating whether this Payout Method should be set as the primary/default method for the associated Beneficiary.

It is crucial to ensure that the account information is accurate at the time of creation, as it cannot be altered subsequently due to regulatory constraints. The external_id, label, and primary properties offer some flexibility for managing Payout Method metadata and preferences post-creation.

Payout Method statuses

Within the platform, Payout Methods are assigned statuses that provide insights into their current state. These statuses can reflect the Payout Method's position in the validation process or represent a conclusive status that defines its current functionality or state.

The table below provides a comprehensive list of the various statuses that a Payout Method can have within the platform:

Status	Description
`ACTIVE`	The Payout Method is in an active state, and funds can be disbursed through it.
`DELETED`	The Payout Method has been deleted at the request of the customer. This status is final and cannot be reversed.