Virtual IBANs

Introduction

A Virtual IBAN (vIBAN) operate as routing identifiers within a two-tier account structure, where master IBANs maintain actual balances while virtual IBANs serve as payment reception endpoints. Incoming payments directed to virtual IBANs are automatically routed to the associated master IBAN. The virtual IBAN reference and associated metadata are preserved throughout the transaction flow and appear in master account statements. Virtual IBANs maintain zero balances and function exclusively for payment reception and routing.

To subscribe to the vIBAN product, contact GuruPay client care team at [email protected].

Core Concepts

GuruPay implements vIBANs using a two-tier account structure:

          ┌──────────────────────┐
          │  Virtual IBAN A      │
Customer ─┤  Virtual IBAN B      ├──► Master IBAN (real balance)
          │  Virtual IBAN C      │
          └──────────────────────┘

• Master IBAN Holds the actual account balance.

• Virtual IBANs Hold no balance, serve as routing endpoints, and forward all funds to the master IBAN.

All metadata (vIBAN reference, owner information, etc.) is preserved in master account statements.

vIBAN Capabilities

Feature / Capability	Supported	Notes
Receive payments	✔	Payments routed automatically to master IBAN with metadata preserved.
Send payments “from” a vIBAN	✔	Funds deducted from master IBAN; recipient sees vIBAN sender info.
Zero-balance vIBAN model	✔	vIBANs never hold funds; all balances reside in master account.
Webhook-based asynchronous creation	✔	201 returned immediately; webhook sent when vIBAN becomes active.
Echo Service (Sandbox-only)	✔	Requires SEPA Instant only for testing, not a production capability.

Virtual IBAN Creation

Before creating vIBANs, you need to identify your master IBAN's UUID.

Use the following endpoint to retrieve a list of all accounts.

Endpoint

GET /api/v1/customers/{customer_uuid}/accounts

In the response, look for:

• "account_type": "virtual_parent"

• This account’s "uuid" is your master_account_uuid.

More information about retrieving account details can be found in our Accounts | Documentation

vIBAN creation is asynchronous:

1. API returns 201 Created immediately.

2. GuruPay sends a webhook when the vIBAN is ready. The webhook contains your new vIBAN details.

Account Event

Important: Set up webhook handling to receive the account creation confirmation.

Create virtual account

post

https://public-api.gurupay.euhttps://public-api-dev.gurupay.eu

/api/v1/customers/{customer_uuid}/accounts/open/virtual

Create new virtual account

Authorizations

BearerAuth

AuthorizationstringRequired

Authentication using a Bearer token.

Path parameters

customer_uuidstring · uuidRequired

Universally Unique Identifier (UUID) as defined by RFC 4122.

Example: e1f8a3b1-7d6c-4e9a-9b2e-3f8d1a9c5f2gPattern: ^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$

Body

application/json

Data required to create a new virtual account.

master_account_uuidstring · uuidRequired

The UUID of the master account.

Example: d8f7b4a0-6e3c-4b5a-8d1e-2f7c9a8b4e1f

person_typestring · enumRequired

Person legal type: legal or natural

Example: legalPossible values:

external_idstringOptional

External ID to be used to track virtual IBAN

Example: bbf12075-90a8-462f-bc73-7c10cec42147

Responses

201

Virtual account creation has been initiated.

401

Unauthorized.

application/json

422

Unprocessable.

application/json

post

/api/v1/customers/{customer_uuid}/accounts/open/virtual

HTTPcURLJavaScriptPython

POST /api/v1/customers/{customer_uuid}/accounts/open/virtual HTTP/1.1
Host: public-api.gurupay.eu
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 509

{
  "master_account_uuid": "d8f7b4a0-6e3c-4b5a-8d1e-2f7c9a8b4e1f",
  "person_type": "legal",
  "external_id": "bbf12075-90a8-462f-bc73-7c10cec42147",
  "person": {
    "first_name": "Account holder",
    "last_name": "Account holder",
    "date_of_birth": "1991-01-01",
    "citizenship": "LT",
    "address": {
      "line": "1 Financial Square",
      "city": "London",
      "country": "GB",
      "postal_code": "123456"
    }
  },
  "company": {
    "company_name": "Gurupay",
    "registration_code": "123456",
    "address": {
      "line": "1 Financial Square",
      "city": "London",
      "country": "GB",
      "postal_code": "123456"
    }
  }
}

No content

Retrieve vIBAN Details

Retrieve full information about your newly created vIBAN so you can begin receiving payments, initiating outgoing transfers, and managing the account lifecycle.

Endpoint

GET /api/v1/customers/{customer_uuid}/accounts

The response will list all your accounts. Look for:

• "account_type": "virtual"

• "status": "created"

• "iban" — share with customers.

• "uuid" — store for management.

• parent_uuid — links to your master account.

More information about retrieving account details can be found in our Accounts | Documentation

Receiving Payments

Once your vIBAN is active, payments work automatically:

1. Customer sends payment to your vIBAN.

2. GuruPay routes payment to your master IBAN instantly.

3. Balance always shows 0.00 as funds route to your master IBAN balance.

4. Transaction details include vIBAN reference for easy identification.

For more details regarding receiving payment, refer to Webhook Messages | Documentation and Transactions | Documentation

Sending Payments

You can initiate outgoing payments directly from your vIBANs using the GuruPay API. When you send a payment from a vIBAN, the funds are deducted from your master account while the payment appears to originate from the vIBAN.

Endpoint

POST /api/v1/transactions

Payment Flow:

1. You initiate a payment using vIBAN as the sender.

2. Funds are deducted from the linked master account balance.

3. Payment is sent with vIBAN owner information as the sender.

4. Recipient sees the vIBAN details (not your master account).

The payment initiation process follows the same structure as standard payment initiation in the GuruPay API. Refer to the public API documentation for detailed endpoint specifications and request parameters. More information can be found at Transactions | Documentation

Key Parameters:

• Sender Account: Use your vIBAN UUID.

• Funds Source: Automatically deducted from master account.

• Sender Information: vIBAN owner details (as registered).

Closing Virtual IBAN

When you request to close a vIBAN, the API immediately returns a 201 Accepted response while the closure is processed asynchronously. Once closed, the vIBAN stops accepting incoming payments, and any future transfers to it will be rejected. The vIBAN cannot be reactivated, but all historical transaction data remains available for reporting and reconciliation.

Warning: Once closed, the vIBAN cannot be reactivated. Create a new one if needed.

Close virtual account

post

https://public-api.gurupay.euhttps://public-api-dev.gurupay.eu

/api/v1/customers/{customer_uuid}/accounts/close/virtual

Close virtual account

Authorizations

BearerAuth

AuthorizationstringRequired

Authentication using a Bearer token.

Path parameters

customer_uuidstring · uuidRequired

Universally Unique Identifier (UUID) as defined by RFC 4122.

Example: e1f8a3b1-7d6c-4e9a-9b2e-3f8d1a9c5f2gPattern: ^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$

Body

application/json

Data required to close virtual account.

virtual_account_uuidstring · uuidOptional

The UUID of the virtual account.

Example: d8f7b4a0-6e3c-4b5a-8d1e-2f7c9a8b4e1f

Responses

201

Close virtual account has been initiated.

401

Unauthorized.

application/json

422

Unprocessable.

application/json

post

/api/v1/customers/{customer_uuid}/accounts/close/virtual

HTTPcURLJavaScriptPython

POST /api/v1/customers/{customer_uuid}/accounts/close/virtual HTTP/1.1
Host: public-api.gurupay.eu
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "virtual_account_uuid": "d8f7b4a0-6e3c-4b5a-8d1e-2f7c9a8b4e1f"
}

No content

Verification of Payee (VoP) Support

vIBANs are fully compatible with Verification of Payee checks. When your vIBAN is created, GuruPay registers it with the European Payments Council (EPC) database using dual ownership information:

• Your details (as the account client).

• Virtual owner details (as provided during creation).

This dual registration ensures that when someone initiates a payment to your vIBAN, the VoP verification will return a MATCH response regardless of whether the sender uses:

• Your company information.

• The virtual owner information you specified.

If sender details contain typos or misspellings of either ownership information, standard VoP matching rules apply and may result in partial matches or no matches. For complete VoP guidance, refer to the European Payments Council documentation: Verification Of Payee and EPC recommendations for the matching processes under the Verification Of Payee scheme rulebook