Skip to main content

API

Flow Endpoints​

virutalIbanFlowpng

Create Virtual IBAN​

This endpoint allows you to create a new Virtual IBAN associated with a main account. It allows you to generate a virtual identifier for collections, reconciliations, and categorizations, with a text description if desired.

Example request:

POST /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans

Request parameters:

  • accountId – required; ID of the account on which to create the Virtual IBAN
  • description – optional; description of the Virtual IBAN in the JSON body

Body example:

{
  "description": "My new virtual IBAN."
}

Example response:

{
  "virtualIban": "IT16L03268223000VR000000042",
  "parentAccountId": "14527670",
  "status": "ACTIVE",
  "activatedDate": "2019-07-04",
  "deactivatedDate": null,
  "description": "My new virtual IBAN."
}

Response parameters:

  • virtualIban – the created Virtual IBAN
  • parentAccountId – ID of the main account
  • status – status of the Virtual IBAN
  • activatedDate – activation date
  • deactivatedDate – deactivation date
  • description – assigned description

Get Virtual IBANs List​

This endpoint returns the list of Virtual IBANs associated with an account, with the option to include inactive ones.

Example request:

GET /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans?showInactive=true

Request parameters:

  • accountId – required; ID of the account
  • showInactive – optional; if true, inactive Virtual IBANs are also included

Example response:

{
  "list": [
    {
      "virtualIban": "IT16L03268223000VR000000042",
      "parentAccountId": "14527670",
      "status": "ACTIVE",
      "activationDate": "2019-07-04",
      "deactivationDate": null,
      "description": "My new virtual IBAN."
    }
  ]
}

Response parameters:

  • list – list of Virtual IBANs
  • virtualIban – virtual IBAN
  • parentAccountId – ID of the main account
  • status – status of the Virtual IBAN
  • activationDate – activation date
  • deactivationDate – deactivation date
  • description – description

Get Virtual IBAN​

This endpoint retrieves information about a single Virtual IBAN identified by its value.

Example request:

GET /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans/{virtualIban}

Request parameters:

  • accountId – required; ID of the account
  • virtualIban – required; virtual IBAN to look up

Example response:

{
  "virtualIban": "IT16L03268223000VR000000042",
  "parentAccountId": "14527670",
  "status": "ACTIVE",
  "activationDate": "2019-07-04",
  "deactivationDate": null,
  "description": "My new virtual IBAN."
}

Response parameters:

  • virtualIban – virtual IBAN
  • parentAccountId – ID of the main account
  • status – status of the Virtual IBAN
  • activationDate – activation date
  • deactivationDate – deactivation date
  • description – description

Deactivate Virtual IBAN​

This endpoint allows you to deactivate an existing Virtual IBAN.

Example request:

PUT /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans/{virtualIban}/inactive

Request parameters:

  • accountId – required; ID of the account
  • virtualIban – required; virtual IBAN to deactivate

Example response:

{
  "result": "OK"
}

Response parameters:

  • result – outcome of the operation

Create Virtual IBAN Money Transfer​

This endpoint supports money transfers using a Virtual IBAN as the source.

Example request:

POST /api/gbs/banking/v4.0/accounts/{accountId}/virtual-ibans/{virtualIban}/money-transfers

Body example:

{
  "amount": 100,
  "currency": "EUR",
  "receiverIban": "IT00A0000000000000000000000",
  "description": "Transfer from virtual IBAN"
}

Request parameters:

  • accountId – required; ID of the account
  • virtualIban – required; source virtual IBAN
  • amount – transfer amount
  • currency – currency
  • receiverIban – recipient IBAN
  • description – transfer description

Example response:

{
  "transferId": "123456789"
}

Response parameters:

  • transferId – transaction ID

Get Parent Account​

Returns the information of the main account associated with a Virtual IBAN.

Example request:

GET /api/gbs/banking/v4.0/accounts/{accountId}/parent

Request parameters:

  • accountId – required; ID of the account

Example response:

{
  "accountId": "14527670",
  "iban": "IT00A0000000000000000000000",
  "status": "ACTIVE"
}

Response parameters:

  • accountId – ID of the main account
  • iban – IBAN of the account
  • status – account status

Get Parent Account Transactions​

Returns the list of transactions for the main account.

Example request:

GET /api/gbs/banking/v4.0/accounts/{accountId}/parent/transactions

Request parameters:

  • accountId – required; ID of the account

Example response:

{
  "transactions": [
    {
      "transactionId": "987654321",
      "amount": 150,
      "currency": "EUR",
      "date": "2024-02-01",
      "description": "Payment received"
    }
  ]
}

Response parameters:

  • transactions – list of transactions
  • transactionId – transaction identifier
  • amount – amount
  • currency – currency
  • date – transaction date
  • description – description