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.

Each recipient can be used for one combination of a payout method and currency, which together determine the account details required.

The Recipients feature also provides endpoints for you to:

• Dynamically retrieve the schema of a Recipient
• Validate a user’s data in advance of registering the account

Recipient registration for payouts also systematically requires SCA, thereby enabling the payout request benefit from an SCA exemption as a trusted beneficiary.

For more details, see the Recipients guide.

Attributes

Id · string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

Status · string

Possible values: PENDING, CANCELED, ACTIVE, DEACTIVATED

The 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, LocalBankTransfer

The payout method of the recipient.

• InternationalBankTransfer – A bank wire transfer sent via SWIFT, requiring the InternationalBankTransfer property.
• LocalBankTransfer – A bank wire transfer sent via local routes, requiring the LocalBankTransfer property.

RecipientType · string

Possible values: Individual, Business

The 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, ZAR

The currency of the recipient.

UserId · string

The unique identifier of the user.

RecipientScope · string

Possible values: PAYIN, PAYOUT

Default value: PAYOUT

The 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

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.

InternationalBankTransfer

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.

PendingUserAction · object

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

Show 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.

Related resources

Guide

Read about how the Recipients feature works

Guide

Read more about SCA