Skip to main content

Overview

The Virtual Accounts API allows you to create and manage virtual IBANs for wallets. Virtual accounts provide dedicated bank account details that can be used to receive funds directly into a wallet, simplifying the funding process for your users. Virtual accounts support both COLLECTION and USER_OWNED purposes, with country-specific IBAN generation.

Methods

Create

Create a new virtual account for a wallet.
public function Create($virtualAccount, $walletId, $idempotencyKey = null)
virtualAccount
VirtualAccount
required
The virtual account object to create
walletId
string
required
The wallet identifier
idempotencyKey
string
Optional idempotency key to ensure request uniqueness
Returns: VirtualAccount - The created virtual account object Example:
$api = new MangoPay\MangoPayApi();

$virtualAccount = new MangoPay\VirtualAccount();
$virtualAccount->VirtualAccountPurpose = 'COLLECTION';
$virtualAccount->Country = 'FR';

$createdAccount = $api->VirtualAccounts->Create($virtualAccount, 'wallet_123456');
echo "IBAN: " . $createdAccount->LocalAccountDetails->IBAN;

Get

Retrieve a virtual account by its ID.
public function Get($walletId, $virtualAccountId)
walletId
string
required
The wallet identifier
virtualAccountId
string
required
The virtual account identifier
Returns: VirtualAccount - The virtual account object Example:
$virtualAccount = $api->VirtualAccounts->Get('wallet_123456', 'vacct_123456');

GetAll

Retrieve all virtual accounts for a specific wallet.
public function GetAll($walletId, $pagination = null, $sorting = null)
walletId
string
required
The wallet identifier
pagination
Pagination
Pagination object
sorting
Sorting
Sorting configuration object
Returns: VirtualAccount[] - Array of virtual account objects Example:
$pagination = new MangoPay\Pagination(1, 10);
$virtualAccounts = $api->VirtualAccounts->GetAll('wallet_123456', $pagination);

foreach ($virtualAccounts as $account) {
    echo "Status: " . $account->Status . "\n";
}

Deactivate

Deactivate a virtual account.
public function Deactivate($walletId, $virtualAccountId)
walletId
string
required
The wallet identifier
virtualAccountId
string
required
The virtual account identifier to deactivate
Returns: VirtualAccount - The deactivated virtual account object Example:
$deactivated = $api->VirtualAccounts->Deactivate('wallet_123456', 'vacct_123456');

GetAvailabilities

Retrieve available virtual account configurations by country and currency.
public function GetAvailabilities()
Returns: VirtualAccountAvailabilities - Object containing available virtual account configurations Example:
$availabilities = $api->VirtualAccounts->GetAvailabilities();
foreach ($availabilities->Local as $availability) {
    echo "Country: " . $availability->Country . ", Currency: " . $availability->Currency . "\n";
}

VirtualAccount Entity

The VirtualAccount entity represents a virtual IBAN with the following properties:
Id
string
The unique identifier of the virtual account
CreationDate
int
Unix timestamp of when the virtual account was created
Tag
string
Custom data that you can add to this item
WalletId
string
The ID of the wallet
CreditedUserId
string
The credited user ID
VirtualAccountPurpose
string
The type of the virtual account. Allowed values: COLLECTION, USER_OWNED
Country
string
The country of the IBAN (ISO 3166-1 alpha-2 format). Must correspond to the currency of the wallet.
Status
string
The status of the virtual account. See VirtualAccountStatus for possible values.
Active
bool
Whether the virtual account is active or not
AccountOwner
VirtualAccountOwner
Information about the account owner
LocalAccountDetails
LocalAccountDetails
Local account details including IBAN, BIC, and other country-specific information
InternationalAccountDetails
InternationalAccountDetails
International account details (when applicable)
Capabilities
VirtualAccountCapabilities
Capabilities of the virtual account (e.g., supported payment methods)
ResultCode
string
Result code if the creation failed
ResultMessage
string
Result message providing details about any errors

VirtualAccountAvailabilities Entity

Contains information about available virtual account configurations:
Local
VirtualAccountAvailability[]
Array of available local virtual account configurations by country and currency
International
VirtualAccountAvailability[]
Array of available international virtual account configurations

VirtualAccountAvailability Entity

Country
string
Country code (ISO 3166-1 alpha-2)
Currency
string
Currency code (ISO 4217)
Available
bool
Whether virtual accounts are available for this country/currency combination

Build docs developers (and LLMs) love