> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/bank-accounts/bank-account-object) 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](/api-reference/recipients/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](/guides/payouts#payout-rails) (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.

<Check>
  **Best practice – Use `InternationalBankTransfer` for multi-currency accounts**

  For 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](/guides/payouts#payout-rails) if a local currency is sent, thereby optimizing routing costs and speeds while allowing you to operate one `RecipientId` for a user.
</Check>

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](/api-reference/recipients/view-recipient-schema)
* Validate the user's data using [POST Validate data for a Recipient](/api-reference/recipients/validate-recipient-data) 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](/guides/sca#exemptions-available-to-mangopay) as a trusted beneficiary.

For more details, see the [Recipients](/guides/sca/recipients) guide.

### Attributes

<ResponseField name="Id" type="string">
  Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)

  The unique identifier of the object.
</ResponseField>

<ResponseField name="Status" type="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.
</ResponseField>

<ResponseField name="CreationDate" type="Unix timestamp">
  The date and time at which the object was created.
</ResponseField>

<ResponseField name="DisplayName" type="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.
</ResponseField>

<ResponseField name="PayoutMethodType" type="string">
  **Possible values:** `InternationalBankTransfer`, `LocalBankTransfer`

  The payout method of the recipient:

  * `LocalBankTransfer` – The account can **only** receive the corresponding local `Currency` for the `Country` via the [domestic payment rail](/guides/payouts#payout-rails) (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.
</ResponseField>

<ResponseField name="RecipientType" type="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.
</ResponseField>

<ResponseField name="Currency" type="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.
</ResponseField>

<ResponseField name="Country" type="string">
  Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))

  The destination country of the payout method.
</ResponseField>

<ResponseField name="UserId" type="string">
  The unique identifier of the user.
</ResponseField>

<ResponseField name="RecipientScope" type="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](/guides/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`.
</ResponseField>

<ResponseField name="Tag" type="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.
</ResponseField>

<Tabs>
  <Tab title="Individual">
    <ResponseField name="IndividualRecipient" type="object">
      The account holder if the `RecipientType` is `Individual`.
    </ResponseField>

    <Expandable title="properties">
      <ResponseField name="FirstName" type="string">
        Length: 1–255; cannot contain: `()&,.:_/` (Pattern: `^(?!.*[()&,.:_/]).{1,255}$`)

        The first name of the individual account holder.
      </ResponseField>

      <ResponseField name="LastName" type="string">
        Length: 1–255; cannot contain: `()&,.:_/` (Pattern: `^(?!.*[()&,.:_/]).{1,255}$`)

        The last name of the individual account holder.
      </ResponseField>

      <ResponseField name="Address" type="object">
        Information about the address.

        <Expandable title="properties">
          <ResponseField name="AddressLine1" type="string">
            Length: 1–255; cannot contain: `()/` (Pattern: `^(?!.*[()/]).{1,255}$`)

            The first line of the address.
          </ResponseField>

          <ResponseField name="AddressLine2" type="string">
            Length: 1–255; cannot contain: `()/` (Pattern: `^(?!.*[()/]).{1,255}$`)

            The second line of the address. Parameter only returned if sent.
          </ResponseField>

          <ResponseField name="City" type="string">
            Length: 1-80; cannot contain: `&,.:_'` (pattern: `^(?!.*[&,.:_]).{1,80}$`)

            The city of the address.
          </ResponseField>

          <ResponseField name="Region" type="string">
            Length: 1–10; cannot contain: `&,.:_'-/` (pattern: `^(?!.*[&,.:_/]).{1,50}$`)

            The region of the address. Parameter only returned if sent.
          </ResponseField>

          <ResponseField name="PostalCode" type="string">
            Length: 1–10; cannot contain: `()&,.:_'/` (pattern: `^(?!.*[()&,.:_'/]).{1,10}$`)

            The postal code of the address.
          </ResponseField>

          <ResponseField name="Country" type="string">
            Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))

            The country of the address.
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>
  </Tab>

  <Tab title="Business">
    <ResponseField name="BusinessRecipient" type="object">
      The account holder if the `RecipientType` is `Business`.
    </ResponseField>

    <Expandable title="properties">
      <ResponseField name="BusinessName" type="string">
        Length: 1–255; cannot contain: `(),.:/` (Pattern: `^(?!.*[(),.:/]).{1,255}$`)

        The name of the business account holder.
      </ResponseField>

      <ResponseField name="Address" type="object">
        Information about the address.

        <Expandable title="properties">
          <ResponseField name="AddressLine1" type="string">
            Length: 1–255; cannot contain: `()/` (Pattern: `^(?!.*[()/]).{1,255}$`)

            The first line of the address.
          </ResponseField>

          <ResponseField name="AddressLine2" type="string">
            Length: 1–255; cannot contain: `()/` (Pattern: `^(?!.*[()/]).{1,255}$`)

            The second line of the address. Parameter only returned if sent.
          </ResponseField>

          <ResponseField name="City" type="string">
            Length: 1-80; cannot contain: `&,.:_'` (pattern: `^(?!.*[&,.:_]).{1,80}$`)

            The city of the address.
          </ResponseField>

          <ResponseField name="Region" type="string">
            Length: 1–10; cannot contain: `&,.:_'-/` (pattern: `^(?!.*[&,.:_/]).{1,50}$`)

            The region of the address. Parameter only returned if sent.
          </ResponseField>

          <ResponseField name="PostalCode" type="string">
            Length: 1–10; cannot contain: `()&,.:_'/` (pattern: `^(?!.*[()&,.:_'/]).{1,10}$`)

            The postal code of the address.
          </ResponseField>

          <ResponseField name="Country" type="string">
            Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))

            The country of the address.
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>
  </Tab>
</Tabs>

<br />

<Tabs>
  <Tab title="InternationalBankTransfer">
    <ResponseField name="InternationalBankTransfer" type="object">
      The account details if `PayoutMethodType` is `InternationalBankTransfer`.

      <Expandable title="properties">
        <ResponseField name="AccountNumber" type="string">
          The account number of the account.
        </ResponseField>

        <ResponseField name="BIC" type="string">
          The BIC of the account. For IBAN countries, the returned `BIC` is generated from the IBAN.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="LocalBankTransfer">
    <ResponseField name="LocalBankTransfer" type="object">
      The account details if `PayoutMethodType` is `LocalBankTransfer`, depending on the `Currency`. One of:

      <Tabs>
        <Tab title="CAD">
          <ResponseField name="CAD" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="AccountNumber" type="string">
                Format: 7–35 digits (pattern: `^\\d{7,35}$`)

                The account number of the Canadian account.
              </ResponseField>

              <ResponseField name="InstitutionNumber" type="string">
                Format: 3 digits (pattern: `^\\d{3}$`)

                The institution number of the Canadian account.
              </ResponseField>

              <ResponseField name="BranchCode" type="string">
                Format: 5 digits (pattern: `^\\d{5}$`)

                The branch code of the Canadian account.
              </ResponseField>

              <ResponseField name="BankName" type="string">
                Length: 1–50

                The bank name of the Canadian account.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="CHF">
          <ResponseField name="CHF" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="CZK">
          <ResponseField name="CZK" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="DKK">
          <ResponseField name="DKK" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="EUR">
          <ResponseField name="EUR" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="GBP">
          <ResponseField name="GBP" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="AccountNumber" type="string">
                Format: 8 digits (pattern: `^\\d{8}$`)

                The account number of the UK account.
              </ResponseField>

              <ResponseField name="SortCode" type="string">
                Format: 6 digits (pattern: `^\\d{6}$`)

                The sort code of the UK account.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="HUF">
          <ResponseField name="HUF" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        {/* <Tab title="MXN">
                <ResponseField name="MXN" type="object">
                <Expandable title="properties" defaultOpen>
                  <ResponseField name="BIC" type="string">
                  Format: 8–11 alphanumeric characters (pattern: `^[0-9a-zA-Z]{8}([0-9a-zA-Z]{3})?$`)

                  The BIC of the Mexican account.
                  </ResponseField>
                  <ResponseField name="Clabe" type="string">
                  Format: 18 digits (pattern: `^\\d{18}$`)

                  The CLABE of the Mexican account.
                  </ResponseField>
                </Expandable>
                </ResponseField>
                </Tab> */}

        <Tab title="NOK">
          <ResponseField name="NOK" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="PLN">
          <ResponseField name="PLN" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="RON">
          <ResponseField name="RON" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="SEK">
          <ResponseField name="SEK" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="IBAN" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>

        <Tab title="USD">
          <ResponseField name="USD" type="object">
            <Expandable title="properties" defaultOpen>
              <ResponseField name="AccountNumber" type="string">
                Format: 8–12 alphanumeric characters (pattern: `^[0-9a-zA-Z]{8,12}$`)

                The account number of the US account.
              </ResponseField>

              <ResponseField name="ABA" type="string">
                Format: 9 digits (pattern: `^\\d{9}$`)

                The ABA routing number of the US account.
              </ResponseField>

              <ResponseField name="FFC" type="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.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Tab>
      </Tabs>
    </ResponseField>
  </Tab>
</Tabs>

<ResponseField name="PendingUserAction" type="object">
  Object containing the link needed for SCA redirection if triggered by the API call (otherwise returned `null`).

  <Expandable title="properties" defaultOpen>
    <ResponseField name="RedirectUrl" type="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](/guides/sca/session#how-to-redirect-a-user-for-sca).
    </ResponseField>
  </Expandable>
</ResponseField>

## Related resources

<CardGroup cols={2}>
  <Card title="Guide" href="/guides/sca/recipients">
    Read about how the Recipients feature works
  </Card>

  <Card title="Guide" href="/guides/sca">
    Read more about SCA
  </Card>
</CardGroup>