Virtual Accounts - BETA

These endpoints provide authorized access to an authenticated user's virtual account information, managing settlement rules for virtual accounts and retrieving a list of payouts generated by settlement rules for virtual accounts.

Create a virtual account

The POST /virtual-accounts endpoint creates a virtual account.

SecurityBearer or BasicAuth
Request
Request Body schema: application/json
required
accountNickName
string

The alias name that identifies the virtual account.

Example: "Account Alias"
currency
required
string

The ISO 4217 three letter currency code.

Example: "EUR"
onBehalfOfId
string

The id of the ultimate client on whose behalf the account is created. If the account is created on behalf of a sub-TPP, this field will contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: "c5a863bc-86f2-4418-a26f-25b24c7983c7"
country
required
string = 2 characters

Two-letter country code in upper case (ISO 3166-1 alpha-2).

Example: "GB"
Responses
200

Successful response

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested entity, such as a TPP, was not found

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

post/virtual-accounts
Request samples
application/json
{
  • "accountNickName": "Account Alias",
  • "currency": "EUR",
  • "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
  • "country": "GB"
}
Response samples
application/json
{
  • "virtualAccount": {
    }
}

Get virtual accounts

The GET /virtual-accounts endpoint retrieves information for all virtual accounts.

SecurityBearer or BasicAuth
Request
query Parameters
limit
integer <int32>

The maximum number of records to return.
The maximum allowed limit is 200. If the passed limit is bigger than this, it will be set to 200.

offset
string

The offset for the current page. The offset is not required to fetch the first page. To fetch subsequent pages, use the 'nextOffset' value from the previous page response.
The offset value should not be parsed and/or understood in any way.

currency
string

The ISO 4217 three letter currency code.

Example: currency=EUR
country
string

Two-letter country code in upper case (ISO 3166-1 alpha-2).

Example: country=PL
nickname
string

The alias name that identifies the virtual account.

Example: nickname=Account Alias
onBehalfOfId
string

The id of the ultimate client on whose behalf the account is created. If the account is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
Responses
200

Successful response

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested entity, such as a TPP, was not found

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

get/virtual-accounts
Request samples 
Response samples 
application/json
{
  • "pageInfo": {
    },
  • "virtualAccount": [
    ]
}
Get a virtual account
The GET /virtual-accounts/{accountId} endpoint the information for a specific virtual account.


SecurityBearer or BasicAuth 
Request 
path Parameters
accountId
required
string
The system-generated, unique id which specifies the virtual account.


 
query Parameters
onBehalfOfId
string
Filters payments by the onBehalfOfId value - returns only payments with the onBehalfOfId value specified in this parameter.  This field is mandatory for unregulated TPPs.


 
 Example:  onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as an account, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/virtual-accounts/{accountId}
Request samples 
Response samples 
application/json
{
  • "virtualAccount": {
    }
}
Get virtual account transactions
The GET /virtual-accounts/{accountId}/transactions endpoint retrieves information of transactions in a given virtual account.


SecurityBearer or BasicAuth 
Request 
path Parameters
accountId
required
string
The system-generated, unique id which specifies the virtual account.


 
query Parameters
limit
integer <int32> 
The maximum number of records to return. 
The maximum allowed limit is 200. If the passed limit is bigger than this, it will be set to 200.


 
offset
string
The offset for the current page. The offset is not required to fetch the first page. To fetch subsequent pages, use the 'nextOffset' value from the previous page response. 
The offset value should not be parsed and/or understood in any way.


 
refId
string
Filters transactions by their refId value - returns only transactions with refId mentioned in the reference.


 
startDate
string
Returns transactions created on or after this date, inclusive (in ISO 8601 format).


 
 Example:  startDate=2022-04-05
endDate
string
Returns transactions created on or before this date, inclusive (in ISO 8601 format).


 
 Example:  endDate=2022-04-05
amount
string
Filters transactions by their transaction amount.


 
providerPaymentId
string
Filters transactions by the provider-payment-id.


 
transactionType
string (TransactionType) 
 Default:  "INVALID_TYPE"
Filters transactions by type to include only CREDIT or DEBIT transactions.


 Enum: "INVALID_TYPE" "DEBIT" "CREDIT"  
 Example:  transactionType=CREDIT
onBehalfOfId
string
Filters payments by the onBehalfOfId value - returns only payments with onBehalfOfId specified in this parameter. This field is mandatory for unregulated TPPs.


 
 Example:  onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as an account, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/virtual-accounts/{accountId}/transactions
Request samples 
Response samples 
application/json
{
  • "pageInfo": {
    },
  • "transactions": [
    ]
}
Get a virtual account transaction
The GET /virtual-accounts/{accountId}/transactions/{providerPaymentId} endpoint retrieves information for a specific transaction in a given virtual account.


SecurityBearer or BasicAuth 
Request 
path Parameters
accountId
required
string
The system-generated, unique id which specifies the virtual account.


 
providerPaymentId
required
string
The virtual account provider-assigned unique transaction identifier.


 
query Parameters
onBehalfOfId
string
Filters payments by the onBehalfOfId value - returns only payments with onBehalfOfId specified in this parameter. This field is mandatory for unregulated TPPs.


 
 Example:  onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as an account, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/virtual-accounts/{accountId}/transactions/{providerPaymentId}
Request samples 
Response samples 
application/json
{
  • "transaction": {
    }
}
Create a settlement rule
The POST /virtual-accounts/{account_id}/settlement-rule endpoint creates a settlement rule for virtual account.


SecurityBearer or BasicAuth 
Request 
path Parameters
account_id
required
string
The system-generated, unique id which specifies the virtual account.


 
Request Body schema: application/json
required
accountId
required
string
The system-generated, unique id which specifies the virtual account.


 
 Example:  "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"
required
object (Creditor) 
 
amountType
required
string (AmountType) 
The type of the amount.


 Enum: "FIXED_VALUE" "PERCENTAGE"  
amountValue
required
string
The value of the amount.


 
 Example:  10
timeInterval
required
string (TimeInterval) 
The time interval.


 Enum: "INTRADAY" "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "HALF_YEARLY" "YEARLY"  
effectiveFrom
string
The start date of the settlement rule is formatted as YYYY-MM-DDTHH:MM:SSZ.


 
 Example:  "2024-01-01T12:34:56Z"
effectiveTo
string
The end date of the settlement rule is formatted as YYYY-MM-DDTHH:MM:SSZ.


 
 Example:  "2024-12-01T12:34:56Z"
intradayIntervalHours
required
integer <int32> 
The intraday interval hours.


 
 Example:  2
intradayIntervalMinutes
integer <int32> 
The intraday interval minutes.


 
 Example:  10
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as an account, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


post/virtual-accounts/{account_id}/settlement-rule
Request samples 
application/json
{
  • "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
  • "payeeAccountDetails": {
    },
  • "amountType": "FIXED_VALUE",
  • "amountValue": 10,
  • "timeInterval": "INTRADAY",
  • "effectiveFrom": "2024-01-01T12:34:56Z",
  • "effectiveTo": "2024-12-01T12:34:56Z",
  • "intradayIntervalHours": 2,
  • "intradayIntervalMinutes": 10
}
Response samples 
application/json
{
  • "settlementRuleId": "123e4567-e89b-12d3-a456-426614174000"
}
Get a settlement rule
The GET /virtual-accounts/{account_id}/settlement-rules/{settlement_rule_id} endpoint retrieves information of a settlement rule for virtual account.


SecurityBearer or BasicAuth 
Request 
path Parameters
account_id
required
string
The system-generated, unique id which specifies the virtual account.


 
settlement_rule_id
required
string
The id of the settlement rule.


 
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a settlement rule, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/virtual-accounts/{account_id}/settlement-rules/{settlement_rule_id}
Request samples 
Response samples 
application/json
{
  • "settlementRule": {
    }
}
Delete a settlement rule
The  DELETE /virtual-accounts/{account_id}/settlement-rules/{settlement_rule_id} endpoint delete an active settlement rule for virtual account.


SecurityBearer or BasicAuth 
Request 
path Parameters
account_id
required
string
The system-generated, unique id which specifies the virtual account.


 
settlement_rule_id
required
string
The id of the settlement rule.


 
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a settlement rule, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


delete/virtual-accounts/{account_id}/settlement-rules/{settlement_rule_id}
Request samples 
Response samples 
application/json
{ }
Get settlement rules
The GET /virtual-accounts/{account_id}/settlement-rules endpoint retrieves information about settlement rules for the virtual account according to the given settlement rule status in the request. If no status is provided, the endpoint retrieves all settlement rules for the virtual account.


SecurityBearer or BasicAuth 
Request 
path Parameters
account_id
required
string
The system-generated, unique id which specifies the virtual account.


 
Request Body schema: application/json
required
accountId
string
Virtual account id.


 
 Example:  "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"
status
string (SettlementRuleStatus) 
The status of the settlement rule.


 Enum: "ACTIVE" "INACTIVE"  
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/virtual-accounts/{account_id}/settlement-rules
Request samples 
application/json
{
  • "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
  • "status": "ACTIVE"
}
Response samples 
application/json
{
  • "settlementRule": [
    ]
}
Get virtual account settlement payouts
The GET /virtual-accounts/{account_id}/settlement-rule-payouts endpoint retrieves information about payouts created by a settlement rule.


SecurityBearer or BasicAuth 
Request 
path Parameters
account_id
required
string
The system-generated, unique id which specifies the virtual account.


 
Request Body schema: application/json
required
accountId
string
The virtual account id.


 
 Example:  "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"
limit
integer <int32> 
The maximum number of items to return in the response.


 
 Example:  10
offset
string
The offset of the first item to return in the response.


 
 Example:  "LerV6Jmex"
settlementRuleId
string
The id of the settlement rule.


 
 Example:  "123e4567-e89b-12d3-a456-426614174000"
startDate
string
The start date of the settlement rule payout.


 
 Example:  "2024-01-01"
endDate
string
The end date of the settlement rule payout.


 
 Example:  "2024-12-01"
ids
Array of strings
The list of payout ids.


 
 Example:  ["123e4567-e89b-12d3-a456-426614174000"]
invertIds
boolean
If true, the response will contain all settlement rule payouts except those specified in the ids field.


 
 Example:  false
statuses
Array of strings
The list of payout statuses.


 
 Example:  ["INITIATION_PENDING","INITIATION_PROCESSING"]
invertStatuses
boolean
If true, the response will contain all settlement rule payouts except those specified in the statuses field.


 
 Example:  false
refIds
Array of strings
The list of settlement payout reference ids.


 
 Example:  ["ShBdcTeqFabqJJhUF"]
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/virtual-accounts/{account_id}/settlement-rule-payouts
Request samples 
application/json
{
  • "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
  • "limit": 10,
  • "offset": "LerV6Jmex",
  • "settlementRuleId": "123e4567-e89b-12d3-a456-426614174000",
  • "startDate": "2024-01-01",
  • "endDate": "2024-12-01",
  • "ids": [
    ],
  • "invertIds": false,
  • "statuses": [
    ],
  • "invertStatuses": false,
  • "refIds": [
    ]
}
Response samples 
application/json
{
  • "pageInfo": {
    },
  • "payouts": [
    ]
}
➔ Next to Accounts