> ## 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 Virtual Account object

### Description

The Virtual Account object enables platforms to attach one or more virtual IBANs to a wallet.

Once created, any funds received on the account are automatically credited to the associated wallet as an [External Instruction Bank Wire PayIn](/api-reference/virtual-accounts/external-instruction-bank-wire-payin-object). Note therefore that `Fees` cannot be taken on pay-ins to virtual accounts.

There are two types of Virtual Account, indicated by the `VirtualAccountPurpose`:

* `COLLECTION` – Owned by Mangopay and usable by platforms and/or users for the purpose of collecting and reconciling incoming funds paid by users. Payouts are generally prohibited from the associated wallet except for refunds. The user can be categorized as a Payer or an Owner.
* `USER_OWNED` – Owned by the wallet owner, enabling them to accept and store funds and make payments. KYC verification is required and the user must be categorized as an Owner. Offering User-Owned Accounts requires your platform to sign the [VOP](/guides/vop) contract amendment and activation – contact our teams <a href="https://hub.mangopay.com/">via the Dashboard</a> to get started.

<Note>
  **Note – One account purpose per wallet**

  A wallet can only have either `COLLECTION` or `USED_OWNED` virtual accounts attached, but not both.

  It is, however, possible to attach multiple virtual accounts of the same `VirtualAccountPurpose` to a single wallet.
</Note>

<Check>
  **Best practice - Migrate from Banking Alias endpoints**

  The Virtual Account endpoints replace the legacy Banking Alias endpoints, and new integrations should use virtual accounts.

  Existing platforms are invited to change their integration to benefit from extended country and currency coverage, as well as any future product improvements. Note also that offering **User-Owned Virtual Accounts** requires your platform to sign the [VOP](/guides/vop) contract amendment.

  If a wallet already has a Banking Alias attached, it cannot be used for Virtual Accounts – you need to create a new wallet.
</Check>

For more information, see the [Virtual Account](/guides/payment-methods/banking/virtual-iban) 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="Tag" type="string">
  Max. length: 255 characters

  Custom data that you can add to this object.
</ResponseField>

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

<ResponseField name="WalletId" type="string">
  The unique identifier of the wallet.
</ResponseField>

<ResponseField name="VirtualAccountPurpose" type="string">
  **Returned values:** `COLLECTION`, `USER_OWNED`

  The type of the virtual account:

  * `COLLECTION` - Owned by Mangopay and usable by platforms and/or users for the purpose of collecting and reconciling incoming funds paid by users.
  * `USER_OWNED` - Owned by the wallet owner, enabling them to accept and store funds and make payments. Offering User-Owned Accounts requires your platform to sign the [VOP](/guides/vop) contract amendment.

  For more information, see the [virtual account](/guides/payment-methods/banking/virtual-iban) guide.
</ResponseField>

<ResponseField name="Country" type="string">
  **Returned values:** The two-letter <a href="/api-reference/overview/data-formats">ISO 3166-1</a> country code (LU, FR, GB, etc.) of an <a href="/guides/payment-methods/banking/virtual-iban">available country</a> (depends on contract and activation settings).

  The country of the IBAN. The country must correspond to the currency of the wallet. See the <a href="/guides/payment-methods/banking/virtual-iban">virtual account</a> guide for details.
</ResponseField>

<ResponseField name="Status" type="string">
  The status of the Virtual Account:

  * `PENDING` – The account creation request is being processed and full account details may not yet be returned. Any funds sent to the account are returned (if account details exist). `PENDING` can transition to `ACTIVE` or `FAILED`.
  * `ACTIVE` – The account is active and can receive funds (see note about delayed [UK CoP recognition](#set-up-the-account) for `GB` accounts). `ACTIVE` can transition to `BLOCKED` or `CLOSED`.
  * `BLOCKED` – The account is blocked and is not active. Any funds sent to the account are returned. This temporary status may be used during processes relating to user verification or fraud screening. `BLOCKED` can transition to `ACTIVE` or `CLOSED`.
  * `CLOSED` – The account has been deactivated and is closed. Any funds sent to the account are returned. This is a final state.
  * `FAILED` – The account creation request failed or was rejected. This final state is rare. Any funds sent to the account are returned (if account details exist).

  See the [virtual account](/guides/payment-methods/banking/virtual-iban#status) guide for more details.
</ResponseField>

<ResponseField name="Active" type="boolean">
  Whether or not the Virtual Account is active.
</ResponseField>

<ResponseField name="AccountOwner" type="string">
  The owner of the virtual account.

  The account owner is assigned automatically depending on the `VirtualAccountPurpose`:

  * `COLLECTION` – Owned by Mangopay SA or Mangopay UK Ltd., mentioning the platform's trading name in the format "MGP `PlatformTradingName`"
  * `USER_OWNED` – Owned by the owner of the associated wallet: `FirstName` `LastName` for Natural Users; `Name` for Legal Users
</ResponseField>

<ResponseField name="LocalAccountDetails" type="object">
  The account details in local format, populated if `Capabilities.LocalPayinAvailable` is `true`.

  **Caution:** Retrieve both the fields and values of these child objects dynamically to present to the user. The `LocalAccountDetails.Account` object has different properties depending on the virtual account `Country`, and these may change over time as Mangopay's coverage expands.

  <Expandable>
    <ResponseField name="Address" type="object">
      The address associated with the account.

      <Expandable>
        <ResponseField name="StreetName" type="string">
          Max. length: 255 characters

          The building number and street name of the address.
        </ResponseField>

        <ResponseField name="PostCode" type="string">
          Max. length: 50 characters

          The postal code of the address.
        </ResponseField>

        <ResponseField name="TownName" type="string">
          Max. length: 255 characters

          The town or city of the address.
        </ResponseField>

        <ResponseField name="CountrySubDivision" type="string">
          Max. length: 255 characters

          The region, state, or county 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>

    <ResponseField name="Account" type="object | null">
      Details of the account in local account identifier format.

      The properties of this object differ depending on the Virtual Account `Country`:

      * **IBAN** – Format if `Country` is `DE`, `ES`, `FR`, `LU`
      * **DK** – Format if `Country` is `DK`
      * **GB** – Format if `Country` is `GB`
      * **US** – Format if `Country` is `US`
      * **CA** – Format if `Country` is `CA`
      * **AU** – Format if `Country` is `AU`
      * **LI** – Format if `Country` is `LI`

      **Caution:** Other formats are planned in future as Mangopay's account coverage expands. Ensure you retrieve the `Account` object's properties and values dynamically.

      <Tabs>
        <Tab title="IBAN">
          <Expandable title="properties" defaultOpen>
            <ResponseField name="Iban" type="string">
              The international bank account number (IBAN) of the account.
            </ResponseField>

            <ResponseField name="Bic" type="string">
              The bank identifier code (BIC) of the account.
            </ResponseField>
          </Expandable>
        </Tab>

        <Tab title="DK">
          <Expandable title="properties" defaultOpen>
            <ResponseField name="BankCode" type="string">
              The 4-digit bank code of the DK local account.
            </ResponseField>

            <ResponseField name="AccountNumber" type="string">
              The 10-digit account number of the DK local account.
            </ResponseField>
          </Expandable>
        </Tab>

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

            <ResponseField name="SortCode" type="string">
              The sort code of the account.
            </ResponseField>
          </Expandable>
        </Tab>

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

            <ResponseField name="AchNumber" type="string">
              The 9-digit ACH routing number of the US account.
            </ResponseField>

            <ResponseField name="FedWireNumber" type="string">
              The 9-digit Fedwire (ABA) number of the US account.
            </ResponseField>

            <ResponseField name="AccountType" type="string">
              The account type of the US account, which is always `CHECKING`.
            </ResponseField>
          </Expandable>
        </Tab>

        <Tab title="CA">
          <Expandable title="properties" defaultOpen>
            <ResponseField name="BranchCode" type="string">
              The 5-digit branch code or transit number of the CA account.
            </ResponseField>

            <ResponseField name="InstitutionNumber" type="string">
              The 3-digit institution number of the CA account.
            </ResponseField>

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

        <Tab title="AU">
          <Expandable title="properties" defaultOpen>
            <ResponseField name="BSBCode" type="string">
              The 6-digit bank state branch (BSB) code of the AU local account.
            </ResponseField>

            <ResponseField name="AccountNumber" type="string">
              The 10-digit account number of the AU local account.
            </ResponseField>
          </Expandable>
        </Tab>

        <Tab title="LI">
          <Expandable title="properties" defaultOpen>
            <ResponseField name="BCNumber" type="string">
              The 5-digit bank clearing number of the LI local account.
            </ResponseField>

            <ResponseField name="AccountNumber" type="string">
              The 12-digit account number of the LI local account.
            </ResponseField>
          </Expandable>
        </Tab>
      </Tabs>
    </ResponseField>

    <ResponseField name="BankName" type="string | null">
      The name of the bank.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="InternationalAccountDetails" type="array (object)">
  List of the account details in international format, populated if `Capabilities.InternationalPayinAvailable` is `true`.

  **Best practice:** Retrieve both the fields and values of these child objects dynamically to present to the user. The `InternationalAccountDetails.Account` object may be `null` depending on the virtual account `Country`.

  <Expandable>
    <ResponseField name="Address" type="object">
      The address associated with the account.

      <Expandable>
        <ResponseField name="StreetName" type="string">
          Max. length: 255 characters

          The building number and street name of the address.
        </ResponseField>

        <ResponseField name="PostCode" type="string">
          Max. length: 50 characters

          The postal code of the address.
        </ResponseField>

        <ResponseField name="TownName" type="string">
          Max. length: 255 characters

          The town or city of the address.
        </ResponseField>

        <ResponseField name="CountrySubDivision" type="string">
          Max. length: 255 characters

          The region, state, or county 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>

    <ResponseField name="Account" type="object | null">
      Details of the account in international format.

      Returned `null` if `Country` is `US`, `CA`, or `AU` as `Capabilities.InternationalPayinAvailable` is `false` for these countries.

      <Expandable>
        <ResponseField name="Iban" type="string">
          The international bank account number (IBAN) of the account.
        </ResponseField>

        <ResponseField name="Bic" type="string">
          The bank identifier code (BIC) of the account.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="BankName" type="string | null">
      The name of the bank.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Capabilities" type="object">
  Information about the account's payment capabilities.

  <Expandable>
    <ResponseField name="LocalPayinAvailable" type="boolean">
      Whether or not local bank wires can be made to this account.
    </ResponseField>

    <ResponseField name="InternationalPayinAvailable" type="boolean">
      Whether or not international bank wires can be made to this account.

      Returned `false` if `Country` is `US` or `CA`.
    </ResponseField>

    <ResponseField name="Currencies" type="array">
      **Returned values:** One or more currency codes in <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217</a> format (EUR, GBP, etc.)

      List of currencies supported by the account.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ResultCode" type="string">
  The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
</ResponseField>

<ResponseField name="ResultMessage" type="string">
  The explanation of the result code.
</ResponseField>

### Related resources

<CardGroup cols={1}>
  <Card title="Guide" href="/guides/payment-methods/banking/virtual-iban">
    Learn more about virtual accounts
  </Card>
</CardGroup>