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 clientcare@gurupay.eu.

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 virtual accounts 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:

API returns 201 Created immediately with a status WAITING_FOR_APPROVAL.
Requests are approved automatically by default. In some cases, additional compliance checks may be required, and the request may be placed in a review queue.
Once virtual account creation or review is completed, the webhook sends the final status CREATED or REJECTED
When the new virtual account is created, the webhook will contain new vIBAN details.

Account Event

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

Create virtual account

post

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

Create new virtual account

Authorizations

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

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_idstring · max: 70Optional

External ID to be used to track virtual IBAN

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

Responses

201

Virtual account creation has been initiated. Returns the Public API UUID and initial request status.

application/json

Response returned after a virtual IBAN creation request is accepted by Public API.

uuidstring · uuidRequired

Public API UUID of the virtual account request. This UUID is later reused in webhook payloads and, after approval, becomes the Public API account UUID.

Example: 0fc45cc2-78ba-4867-9cd2-24ed54f87ecd

statusstring · enumRequired

Initial Public API status of the virtual account request.

Example: WAITING_FOR_APPROVALPossible values:

401

Unauthorized.

application/json

422

Unprocessable.

application/json

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

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: 528

{
  "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",
    "industry_type": 13,
    "address": {
      "line": "1 Financial Square",
      "city": "London",
      "country": "GB",
      "postal_code": "123456"
    }
  }
}

{
  "uuid": "0fc45cc2-78ba-4867-9cd2-24ed54f87ecd",
  "status": "WAITING_FOR_APPROVAL"
}

Retrieve Virtual IBAN 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:

Customer sends payment to your vIBAN.
GuruPay routes payment to your master IBAN instantly.
Balance always shows 0.00 as funds route to your master IBAN balance.
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:

You initiate a payment using vIBAN as the sender.
Funds are deducted from the linked master account balance.
Payment is sent with vIBAN owner information as the sender.
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).

Update virtual account

put

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

Fully updates the resource by replacing the existing data with the provided request body. All required fields must be provided, as missing values may be overwritten or cleared.

Authorizations

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

Data required to update a virtual account.

virtual_account_uuidstring · uuidRequired

The UUID of the virtual account to update.

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

person_typestring · enumRequired

Person legal type: legal or natural

Example: legalPossible values:

external_idstring · max: 70Optional

External ID to be used to track virtual IBAN

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

Responses

204

Virtual account has been updated.

No content

404

Not found

application/json

422

Unprocessable.

application/json

put/api/v1/customers/{customer_uuid}/accounts/update/virtual

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

{
  "virtual_account_uuid": "d8f7b4a0-6e3c-4b5a-8d1e-2f7c9a8b4e1f",
  "person_type": "legal",
  "external_id": "bbf12075-90a8-462f-bc73-7c10cec42147",
  "person": {
    "first_name": "John",
    "last_name": "Doe",
    "citizenship": "LT",
    "address": {
      "line": "1 Financial Square",
      "building_number": "15",
      "city": "London",
      "country": "GB",
      "postal_code": "123456"
    }
  },
  "company": {
    "company_name": "Gurupay",
    "industry_type": 13,
    "address": {
      "line": "1 Financial Square",
      "building_number": "15",
      "city": "London",
      "country": "GB",
      "postal_code": "123456"
    }
  }
}

No content

Blocking Virtual IBAN

Blocking a virtual IBAN places it into a non-operational state.

When a vIBAN is blocked, its status is set to disabled. Blocking applies as a full block, and all incoming and outgoing payments to the vIBAN are rejected, as the IBAN is blocked.

Blocked vIBANs remain visible and are returned in GET IBAN details endpoints.

Block virtual account

post

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

Block virtual account

Authorizations

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

Data required to block virtual account.

virtual_account_uuidstring · uuidOptional

The UUID of the virtual account.

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

Responses

200

Block virtual account has been initiated.

No content

400

Unprocessable.

application/json

404

Not found.

application/json

post/api/v1/customers/{customer_uuid}/accounts/block/virtual

POST /api/v1/customers/{customer_uuid}/accounts/block/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

Unblocking Virtual IBAN

Unblocking a virtual IBAN returns it to an operational state.

When a vIBAN is unblocked, its status is set to created .The vIBAN becomes fully operational, and all incoming and outgoing payment operations function normally.

API users can only unblock vIBANs that they previously blocked themselves. vIBANs blocked by other parties cannot be unblocked via the API.

Unblock a virtual account

post

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

Unblock a virtual account

Authorizations

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

Data required to unblock virtual account.

virtual_account_uuidstring · uuidOptional

The UUID of the virtual account.

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

Responses

200

Unblock virtual account has been initiated.

No content

400

Unprocessable.

application/json

404

Not found

application/json

post/api/v1/customers/{customer_uuid}/accounts/unblock/virtual

POST /api/v1/customers/{customer_uuid}/accounts/unblock/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

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

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

Close virtual account

Authorizations

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

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.

No content

401

Unauthorized.

application/json

422

Unprocessable.

application/json

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

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

Upload virtual IBAN document

post

/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents

Upload virtual IBAN document

Authorizations

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}$

account_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

Data required to upload a document to a virtual account.

typestring · enumRequired

Document type

Example: passportPossible values:

descriptionstringOptional

Description

Example: passport of myself

file_namestringRequired

Original filename

Example: passport.pdf

Responses

200

No content

400

Unprocessable.

application/json

401

Unauthorized.

application/json

404

Virtual IBAN not found.

422

Unprocessable.

application/json

post/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents

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

{
  "type": "passport",
  "description": "passport of myself",
  "file_name": "passport.pdf",
  "attachment": {
    "content": "base64_content",
    "page_type": null
  }
}

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

PreviousStatements

NextDocument Operations

Last updated 3 months ago

Was this helpful?