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:

API returns 201 Created immediately.
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

/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_idstringOptional

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

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: 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"
    }
  }
}

{
  "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).

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.

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}/upload-document

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:

descriptionstring · nullableOptional

Optional 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}/upload-document

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

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

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 NextCustomers

Last updated 1 day ago

Was this helpful?

hashtagIntroduction

hashtagCore Concepts

hashtagvIBAN Capabilities

hashtagVirtual IBAN Creation

hashtagCreate virtual account

hashtagRetrieve Virtual IBAN Details

hashtagReceiving Payments

hashtagSending Payments

hashtagBlocking Virtual IBAN

hashtagBlock virtual account

hashtagUnblocking Virtual IBAN

hashtagUnblock a virtual account

hashtagClosing Virtual IBAN

hashtagClose virtual account

hashtagUpload virtual IBAN document

hashtagVerification of Payee (VoP) Support

Introduction

Core Concepts

vIBAN Capabilities

Virtual IBAN Creation

Create virtual account

Retrieve Virtual IBAN Details

Receiving Payments

Sending Payments

Blocking Virtual IBAN

Block virtual account

Unblocking Virtual IBAN

Unblock a virtual account

Closing Virtual IBAN

Close virtual account

Upload virtual IBAN document

Verification of Payee (VoP) Support