API Flows

Definition & Flow Dependency

Every API request in the Virtual Account flow (i.e. Create VA, Update VA, and Inquiry VA) is logically connected to maintain consistency of a specific VA lifecycle.

Once you have created a Virtual Account successfully, the referenceNo value obtained in the Create VA API response must be passed as the originalReferenceNovalue when performing an Update VA request. If the reference values do not match, the system will reject the Update VA request, even when the virtualAccountNo and virtualAccountName are correct.

For Inquiry VA, the logic works slightly differently.

Inquiry VA will always return the most recent Virtual Account record for the VA number you provide. If you create a new VA using the same VA number as an older one (that is already expired or paid), the inquiry will always show the newest VA detail, not the oldest one.

Flows

There are 2 main flows and 1 supplemental flow in Ayoconnect’s Virtual Account Solution. Each flow requires a valid B2B token before execution.

No	Flow	Description
1	Create Virtual Account	Generate a new Virtual Account. (1) Supports open-amount or closed-amount configuration. (2) Supports single-use or multi-use behaviour.
2	Update Virtual Account	Modify the details of an existing VA, such as name, expiry, amount, or etc. This flow can also be used to: (1) Reactivate an expired VA (2) Extend expiry (3) Force-expire a VA (4) Update customer information
3	Inquiry Virtual Account (Supplemental Flow)	Retrieve the latest status or details of a previously created VA. Does not modify the VA, but is used for customer-facing checks and internal verification.

Flow

Description

Create Virtual Account

Generate a new Virtual Account.

(1) Supports open-amount or closed-amount configuration.
(2) Supports single-use or multi-use behaviour.

Update Virtual Account

Modify the details of an existing VA, such as name, expiry, amount, or etc. This flow can also be used to:

(1) Reactivate an expired VA
(2) Extend expiry
(3) Force-expire a VA
(4) Update customer information

Inquiry Virtual Account (Supplemental Flow)

Retrieve the latest status or details of a previously created VA. Does not modify the VA, but is used for customer-facing checks and internal verification.

Using Only Create VA

If your system flow only requires generating a VA and waiting for payment (via callback), you can simply rely on the Create VA API. Once the VA becomes Inactive-Paid or Inactive-Expired, you may recreate a new one using the same configuration or number.

However, the Update VA and Inquiry VA APIs are strongly recommended to:

Allow you or your customers to update details such as name, expiry time, or amount;
Enable you to check the latest VA status or confirm whether a VA is active, paid, or expired before initiating a new one.

Idempotency

To perform an idempotent request, you must include:

A unique X-EXTERNAL-ID value in the request header; and
A trxId value in the request body.

Both values work together to uniquely identify the operation, ensuring the request is processed safely without creating duplicate Virtual Accounts.