DashboardSandbox Dashboard

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.

In order to subscribe to Virtual IBAN produxt please contact GuruPay client care team at [email protected].

Virtual IBAN Creation

Virtual IBANs are created through dedicated API endpoint that require a virtual account information and master account uuid.

SInce new account creation is asynchronous, GuruPay API will return an empty 201 response. A webhook will be sent to your application once account is created and opened:

Account Event

Create virtual account

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

Create new virtual account

Authorizations
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:
Responses
201

Virtual account creation has been initiated.

No content
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: 456

{
  "master_account_uuid": "d8f7b4a0-6e3c-4b5a-8d1e-2f7c9a8b4e1f",
  "person_type": "legal",
  "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

Close virtual account

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

Close virtual account

Authorizations
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
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
PreviousAccountsNextCustomers

Last updated

Was this helpful?