Virtual IBANs

Virtual IBAN Functionality

Virtual IBANs 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.

Virtual IBAN Creation

Virtual IBANs are created through dedicated API endpoint that require a virtual account information and master account uuid. The API returns a 201 response. Once new virtual account is opened, a webhok will be delivered.

A master account can pnly be opened by contacting [email protected].

Create virtual account

post

Create new virtual account

Authorizations

BearerAuth

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

namestringRequired

Account holder name.

Example: Account holder

person_typestring · enumRequired

Person legal type: legal or natural

Example: legalPossible values:

registration_codestringOptional

Company or person registration code

Example: 123456

citizenshipstringOptional

Country code of citizenship

Example: LT

Responses

201

Virtual account creation has been initiated.

No content

401

Unauthorized.

application/json

422

Unprocessable.

application/json

post

HTTPcURLJavaScriptPython

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

{
  "master_account_uuid": "d8f7b4a0-6e3c-4b5a-8d1e-2f7c9a8b4e1f",
  "name": "Account holder",
  "person_type": "legal",
  "registration_code": "123456",
  "citizenship": "LT",
  "address": {
    "line": "1 Financial Square",
    "city": "London",
    "country": "GB",
    "postal_code": "123456"
  }
}

No content