Guide: How to issue virtual IBANs with OpenPayd


Posted on December 18, 2023
Guide: How to issue virtual IBANs with OpenPayd
Virtual accounts and IBANs are the cornerstone of a modern payments infrastructure. Here’s how our clients are issuing them.
OpenPayd Editorial Team
OpenPayd Editorial Team
December 18, 2023

Virtual IBANs are probably the part of the OpenPayd offering that we get most excited about. Every day, we see the impact they’re having for our clients, from easing payment reconciliation, to providing a seamless user experience. That’s why we’ve developed this guide, to provide an in-depth exploration of the process our clients use to begin issuing virtual IBANs. 

Before diving in any further though, we should be clear: This guide is for people who understand what a virtual account is and the role it will play in their business. If you aren’t familiar with the terms, check out our article on What is a Virtual IBAN before tackling the rest of this guide. You can also refer to our technical documentation for further details.


Understanding your existing account infrastructure

When we talk about “account infrastructure”, we are looking at the accounts that a business needs to manage its money most effectively. For most businesses, this is a single corporate account that they use to manage every payment in and out and hold their cash balance.

In some cases though, a business will also be handling client funds. In this case, either for regulatory reasons or to simplify their book-keeping, a business will need a segregated master account for client funds that keeps them separate from the business’s accounts. 

This article explores how to issue vIBANs on top of one of these two account structures. The process for issuing vIBANs doesn’t change with either model, but it’s important to understand your current account set-up and how vIBANs will work within your organisation. Regardless of your existing set-up, you will also need to have opened either a corporate account or a master client account with OpenPayd already – we cannot offer vIBANs linked to a third-party bank account.


Virtual accounts vs vIBANs – what is the difference? 

You’ll notice as you read through this guide that we often use the terms “vIBAN” and virtual “account” interchangeably, and that our API documentation refers to this as the “Account object”. Ultimately, these refer to the same thing – a vIBAN is the service we offer, whereas a virtual account describes how our clients use the functionality in their business. The Account Object is simply how we refer to an account in our data architecture.


Mapping your vIBAN recipients

Now that you have a main account set up, it’s time to start mapping the vIBAN recipients. These can be either businesses or individuals that require a unique IBAN for payments in and payouts in their name.

Given that most businesses exploring virtual IBANs will be looking to issue hundreds, if not thousands of them, the best way to do this will be via an API integration. Typically, when our clients are getting started, this project will involve two elements: 

  • Issuing vIBANs for their existing user-base, if required.
  • Issuing new vIBANs every time a new user signs up to use their services.

Technically, the process here will be exactly the same for either group: your system will need to collect a set of data points for each individual IBAN, which it then passes to the OpenPayd system via our API. For new users, this process involves integrating this data collection into the user onboarding journey – so a customer onboarding within the Eurozone is issued with a EUR IBAN, for example. For existing clients, it’s likely that you’ll already have the required user data, but it will require a dedicated project to migrate these users over to OpenPayd vIBANs and fill any gaps in the data we require. 


The Objects you’ll be creating via API call

To fully onboard a user and issue them a vIBAN, you’ll need to set up two objects in our system, using different API calls. 

The first is the Linked Client object. This is the entity in our system that corresponds with a user: a single person or business. You have to create the Linked Client first before you can create an account for that user.

Once the Linked Client object is created, the next step is to create the Account object using additional API calls, and also any beneficiaries the account needs. (We won’t get into beneficiary creation in this guide, but they are essential if your users will be making payouts.) The reason we separate these objects in our data architecture is so that one user can have multiple accounts.

To run through this with an example, let’s imagine you’re onboarding a retail customer in the UK called Andy Pope. The process would be:

  1. You’ll set up Andy as a Linked Client (it’s referred to as “linked” because Andy is linked to your business’s main account). 
  2. Once that process is complete, we can issue a GB account with a Sort Code/Account number in Andy’s name.
  3. If Andy needs a Euro account in the future, we can then make the same API call to create a new account, using the same Linked Client ID we have already created for Andy, but in a different currency. 
  4. We now have one linked client (Andy) with two virtual accounts (a GBP account and a EUR account, both in Andy’s name).


How to start issuing vIBANs via the OpenPayd API

If that’s the high-level process we’re going to develop, the next step is to get into the sequence of API calls needed to do this. For a newly onboarded client who needs a vIBAN, the data flow below details the process involved: 

linked client and account creation with french iban


This process has a number of key steps:

  • A user signs up for the service and provides all the required demographic data

This will happen on your platform as part of your user onboarding.

  • The Create Linked Client API call is sent to OpenPayd 

This uses the POST /api/linkedClient and requires the account holder ID retrieved from the dashboard or the authentication endpoint – if you have any questions about finding these, this page has more information

The information submitted in the Create Linked Client API call will be slightly different depending on whether it is a business or retail user – these will require different inputs.

  • Once submitted, you will receive the account holder id related to the linked client

This will then be used to start issuing accounts for the user. 

  • Then use POST /api/accounts to create the account for the linked client

The main data fields that we need at this stage are: 

  • 3-letter currency code
  • A “friendly name” for the account
  • The IBAN Country code – such as “GB” or “MT” 
  • EndToEndReference – for additional information such as your internal client ID. 

There are a few others that you may need to include to ensure the account is set up in the correct way. For more information, you can check out our technical documentation here on The Account Object and API call.

  • An account id is returned. This can then be used for the GET /api/bank-accounts to retrieve account details

These account details will include IBAN and BIC or Account Number and Sort Code. Once these steps are completed, the account will be fully set up and ready to receive incoming payments from our user.


Next steps for your virtual IBAN infrastructure

From this base, it’s possible to start building additional functionality. This might be offering additional currencies to users by repeating steps three and four for different currencies. It may be to start building beneficiaries for each Linked Client, using the Create Bank Beneficiary API call. Or it may be to build webhooks that update your other user data sources and will fire once an element of the account changes.

In other words, issuing virtual IBANs for users is just the start of the possible applications for embedding accounts into your products and services. Just another reason we get so excited about the different ways our customers are using them.