Introduction

This how-to guide will show you how to successfully associate a virtual IBAN to a Wallet.

Prerequisites

  • A ClientId and an API key – if you don’t have these, contact Sales to get access to the Mangopay Hub
  • A Mangopay user for which to create the wallet and its virtual IBAN.
  • Activation of the feature by Mangopay teams (including Sandbox).

Mangopay supports for its wallets the creation of a virtual bank account number.

Once a wallet is associated with a virtual IBAN, users can do a bank wire directly from their bank account to the wallet, as they would do for any other wire transfer from one bank account to another.

Learn more about virtual IBAN

1. Create the wallet

Create the Wallet which is to be associated with a virtual IBAN.

The currency of the wallet must correspond to the country of the IBAN that you’ll attach to it. See IBAN countries and currencies for details.

POST /v2.01/{ClientId}/wallets

2. Create the virtual IBAN

Create the virtual IBAN by (called a Banking Alias in the API) using the previously created wallet Id as a path parameter. You need to specify the OwnerName, the Country, and optionally a Tag.

The OwnerName must match the name of the user owning the wallet (FirstName and LastName for a Natural User, Name for a Legal User).

If Mangopay has provided your platform with a Technical Collection Virtual IBAN for reconciliation purposes, the OwnerName must be “Mangopay S.A.” or “Mangopay S.A. - Your Trading Name”. Please ensure your have confirmed this integration with our teams via the Hub.

POST /v2.01/{ClientId}/wallets/{WalletId}/bankingaliases/iban

The API then returns the Banking Alias object, which contains your virtual IBAN number. This IBAN can be used to make a bank wire directly from a bank account to the wallet, as they would do for any other wire transfer (from one bank account to another).

API response
{
    "OwnerName": "Alex Smith",
    "IBAN": "FR117452110000JIULYOYXT2D48",
    "BIC": "MPAYFRP1PIN",
    "CreditedUserId": "146476890",
    "Country": "FR",
    "Tag": "Custom meta",
    "CreationDate": 1670263006,
    "Active": true,
    "Type": "IBAN",
    "Id": "wltbank_m_01HT2J9Y0A8XTNDE1JVV8Q7PQM",
    "WalletId": "157607922"
}

3. Deactivate a virtual IBAN

If the virtual IBAN is no longer required, you’ll need to deactivate it.

Caution - Deactivating a Banking Alias is irreversible

Once the Banking Alias object is deactivated, you cannot reactivate it. Any funds wired to this banking alias won’t be credited to the corresponding wallet.

If such cases arise, please get in touch with Mangopay teams via the Hub.

PUT /v2.01/{ClientId}/bankingaliases/{BankingAliasId}