The Recipient object

Description

A Recipient represents the beneficiary and the beneficiary account (typically a bank account) of a payout. The new set of Recipient endpoints replaces the legacy Bank Account endpoints, including bank account types. A Recipient account can be registered for an Individual or Business entity, defined in RecipientType. The Country of the user’s account combines with its Currency to determine the available PayoutMethodType, which you can check using GET View payout methods. The PayoutMethodType property defines the possible payout rails that can be used with the Recipient:

LocalBankTransfer – The account can only receive the corresponding local Currency for the Country via the domestic payment rail (e.g. EUR via a SEPA local scheme to a SEPA country, GBP via FPS to a GB account, USD via ACH to a US account, etc). Payouts in non-local currencies return an error.
InternationalBankTransfer – The account can receive both non-local currencies via SWIFT and also local currency via domestic rails.

Best practice – Use InternationalBankTransfer for multi-currency accountsFor users who may wish to receive payouts in multiple currencies to the same account, use the InternationalBankTransfer for PayoutMethodType.For these Recipients, Mangopay automatically uses the domestic rail if a local currency is sent, thereby optimizing routing costs and speeds while allowing you to operate one RecipientId for a user.

Note that all legacy Bank Accounts migrated to Recipients may have the LocalBankTransfer payout method type and accept SWIFT payouts. New account registrations for multi-currency use must use InternationalBankTransfer. With the Country, Currency, and PayoutMethodType, you can then:

Dynamically retrieve the required schema of the user’s account details using GET View the schema for a Recipient
Validate the user’s data using POST Validate data for a Recipient in advance of registering the account

Recipient registration for payouts also systematically requires SCA. This allows the payout request to benefit from an SCA exemption as a trusted beneficiary. For more details, see the Recipients guide.

Attributes

string

Max length: 128 characters (see data formats for details)The unique identifier of the object.

Status

string

Possible values: PENDING, CANCELED, ACTIVE, DEACTIVATEDThe status of the recipient:

PENDING – For PAYOUT scope recipients, the user must complete SCA before the recipient can become ACTIVE. For PAYIN scope recipients, the recipient creation is in progress.
CANCELED – SCA was not successfully completed and the recipient creation request was canceled. To retry, create another recipient to retrieve another PendingUserAction.RedirectUrl. The CANCELED status does not apply if RecipientScope is PAYIN.
ACTIVE – Recipient creation was successful (including SCA if RecipientScope is PAYOUT) and the recipient is ready to be used for payouts .
DEACTIVATED – The recipient has been permanently deactivated and can no longer be used.

CreationDate

Unix timestamp

The date and time at which the object was created.

DisplayName

string

Length: 1–50; cannot contain: &,'/ (pattern:^(?!.*[&,'/]).{1,50}$)A user-friendly name to identify the account. This value cannot be changed once the recipient is created.

PayoutMethodType

string

Possible values: InternationalBankTransfer, LocalBankTransferThe payout method of the recipient:

LocalBankTransfer – The account can only receive the corresponding local Currency for the Country via the domestic payment rail (e.g. EUR via a SEPA local scheme to a SEPA country, GBP via FPS to a GB account, USD via ACH to a US account, etc). Payouts in non-local currencies return an error.
InternationalBankTransfer – The account can receive both non-local currencies via SWIFT and also local currency via domestic rails.

RecipientType

string

Possible values: Individual, BusinessThe recipient type:

Individual – An account held by a natural person, requiring the IndividualRecipient property.
Business – An account held by a legal entity, requiring the BusinessRecipient property.

Currency

string

Possible values: AED, AUD, CAD, CHF, CNH, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PLN, RON, SAR, SEK, SGD, TRY, USD, ZARThe currency of the recipient.

Country

string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)The destination country of the payout method.

UserId

string

The unique identifier of the user.

RecipientScope

string

Possible values: PAYIN, PAYOUTDefault value: PAYOUTThe scope of the recipient:

PAYOUT – Usable for payouts and in pay-in use cases. A PAYOUT recipient can only be created by a user with the UserCategory OWNER and requires SCA. You need to use the returned PendingUserAction.RedirectUrl value, adding your encoded returnUrl as a query parameter, to redirect the user to the hosted SCA session so they can complete the necessary steps.
PAYIN - Not usable for payouts but only usable for pay-in use cases, such as direct debit and refunds using payouts. A PAYIN recipient can be created by a user with the UserCategory PAYER or OWNER, and does not require SCA.

Both PAYIN and PAYOUT scopes can be created for either InternationalBankTransfer or LocalBankTransfer, and for either IndividualRecipient or BusinessRecipient, and for any Currency.

Tag

string

Max. length: 255 (pattern: ^.{0,255}$)Custom data that you can add to this object. This value cannot be changed once the recipient is created.

Individual
Business

IndividualRecipient

object

The account holder if the RecipientType is Individual.

Show properties

FirstName

string

Length: 1–255; cannot contain: ()&,.:_/ (Pattern: ^(?!.*[()&,.:_/]).{1,255}$)The first name of the individual account holder.

LastName

string

Length: 1–255; cannot contain: ()&,.:_/ (Pattern: ^(?!.*[()&,.:_/]).{1,255}$)The last name of the individual account holder.

Address

object

Information about the address.

Show properties

AddressLine1

string

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)The first line of the address.

AddressLine2

string

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)The second line of the address. Parameter only returned if sent.

City

string

Length: 1-80; cannot contain: &,.:_' (pattern: ^(?!.*[&,.:_]).{1,80}$)The city of the address.

Region

string

Length: 1–10; cannot contain: &,.:_'-/ (pattern: ^(?!.*[&,.:_/]).{1,50}$)The region of the address. Parameter only returned if sent.

PostalCode

string

Length: 1–10; cannot contain: ()&,.:_'/ (pattern: ^(?!.*[()&,.:_'/]).{1,10}$)The postal code of the address.

Country

string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)The country of the address.

BusinessRecipient

object

The account holder if the RecipientType is Business.

Show properties

BusinessName

string

Length: 1–255; cannot contain: (),.:/ (Pattern: ^(?!.*[(),.:/]).{1,255}$)The name of the business account holder.

Address

object

Information about the address.

Show properties

AddressLine1

string

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)The first line of the address.

AddressLine2

string

Length: 1–255; cannot contain: ()/ (Pattern: ^(?!.*[()/]).{1,255}$)The second line of the address. Parameter only returned if sent.

City

string

Length: 1-80; cannot contain: &,.:_' (pattern: ^(?!.*[&,.:_]).{1,80}$)The city of the address.

Region

string

Length: 1–10; cannot contain: &,.:_'-/ (pattern: ^(?!.*[&,.:_/]).{1,50}$)The region of the address. Parameter only returned if sent.

PostalCode

string

Length: 1–10; cannot contain: ()&,.:_'/ (pattern: ^(?!.*[()&,.:_'/]).{1,10}$)The postal code of the address.

Country

string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)The country of the address.

InternationalBankTransfer
LocalBankTransfer

InternationalBankTransfer

object

The account details if PayoutMethodType is InternationalBankTransfer.

Show properties

AccountNumber

string

The account number of the account.

BIC

string

The BIC of the account. For IBAN countries, the returned BIC is generated from the IBAN.

LocalBankTransfer

object

The account details if PayoutMethodType is LocalBankTransfer, depending on the Currency. One of:

CAD

object

Hide properties

AccountNumber

string

Format: 7–35 digits (pattern: ^\\d{7,35}$)The account number of the Canadian account.

InstitutionNumber

string

Format: 3 digits (pattern: ^\\d{3}$)The institution number of the Canadian account.

BranchCode

string

Format: 5 digits (pattern: ^\\d{5}$)The branch code of the Canadian account.

BankName

string

Length: 1–50The bank name of the Canadian account.

CHF

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

CZK

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

DKK

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

EUR

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

GBP

object

Hide properties

AccountNumber

string

Format: 8 digits (pattern: ^\\d{8}$)The account number of the UK account.

SortCode

string

Format: 6 digits (pattern: ^\\d{6}$)The sort code of the UK account.

HUF

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

NOK

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

PLN

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

RON

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

SEK

object

Hide properties

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)The IBAN of the account.

USD

object

Hide properties

AccountNumber

string

Format: 8–12 alphanumeric characters (pattern: ^[0-9a-zA-Z]{8,12}$)The account number of the US account.

ABA

string

Format: 9 digits (pattern: ^\\d{9}$)The ABA routing number of the US account.

FFC

string

Format: 8-12 digits then FFC then a space then a sting of characters up to 140 total length (pattern: ^(?=.{0,140}$)[0-9]{8,12}/FFC [0-9a-zA-Z/\\-?:().,'+ ]+$)FFC transfer information for the US account.

PendingUserAction

object

Object containing the link needed for SCA redirection if triggered by the API call (otherwise returned null).

Hide properties

RedirectUrl

string

The URL to which to redirect the user to perform strong customer authentication (SCA) via a Mangopay-hosted webpage. This value is a variable and should not be hardcoded.The SCA session link expires 10 minutes after it’s generated.Caution: Before redirecting the user on this URL, you must add the query parameter ReturnUrl with the percent-encoded URL to which you want the SCA session to return the user after authentication (whether successful or not).For more details, see How to redirect a user for an SCA session.

Guide

Read about how the Recipients feature works

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Echo

Helpers

Platform account

Description

Attributes

Guide

Guide

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Echo

Helpers

Platform account

​Description

​Attributes

​Related resources

Guide

Guide

Description

Attributes

Related resources