Request virtual account

post

https://api.sandbox.ibanq.com/v1/virtual-accounts

Requests one more virtual IBAN for the declared client: a client this credential may act for, or one of its active sub-accounts. The request is validated and recorded, then handed to onboarding, which creates the virtual IBAN, reviews it and allocates the account details; the response is 202 with the request resource, whose status moves from Pending through Accepted to Allocated, Rejected or Failed. Follow it with GET /virtual-account-requests/{id} or the virtual-account-request webhook events. Retries with the same idempotencyKey and the same details return 200 with the original request; a key reused with different details is rejected with 409. An identical request under a new idempotencyKey is a new request for a further virtual IBAN.

Body Params

clientId

string

required

length ≥ 1

Required; the client the virtual IBAN is for: a client this credential may act for, or one of its active sub-accounts

friendlyName

string | null

Name for the virtual IBAN; at most 100 characters

transactionActivitySubTypes

array of int32s

required

Required; at least one transaction activity sub-type code from GET /reference/transaction-activity-sub-types; no duplicates

transactionActivitySubTypes*

idempotencyKey

string

required

length between 0 and 100

Caller-generated key that makes the request retry-safe; at most 100 characters. Retrying with the same key and the same details returns 200 with the original request. Reusing a key with different details is rejected with 409 whose body carries existingRequestId

Headers

DPoP

string

required

Fresh RFC 9449 proof JWT (ES256) signed with the client's DPoP key, binding this request's method and URL to the access token; generate a new proof per request

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Identical retry replayed; the request originally made under this idempotencyKey is returned

202Request accepted for processing; the request resource is returned and its URL is in the Location header

400Invalid request parameters

401Missing or invalid access token / DPoP proof

403clientId does not match a client this credential may act for

404Client not found, or virtual account requests are not enabled in this environment

409The idempotency key was reused with different details; existingRequestId names the request made under it

422Business rule validation failed: the client is not active

500Internal server error

504The request timed out before a response could be produced.