Important Terminologies

There are a few terminologies within Virtual Accounts that you should familiarize yourself with below

Virtual Account Types

Ayoconnect’s Virtual Account solution supports two main types. Each serves a different payment pattern, depending on your payment behavior needs.

1. Multi-Payment Virtual Account

A Multi-Payment VA allows customers to make multiple payments using the same Virtual Account number until it reaches the expiry time. Even after a successful payment, the VA remains active and can continue receiving additional payments.
This type is useful when you expect customers to make more than one payment through the same VA, such as billing cycles, top-ups, recurring deposits, flexible billing, or similar use cases.
You can create a multi-payment VA by setting isSingleUse = "N" in the Create VA request.

2. Single-Payment Virtual Account

A Single-Payment VA becomes inactive immediately after it receives a successful payment, ensuring the VA cannot be reused and preventing accidental duplicate payments.
This type is suitable when each payment must stand alone, such as invoice settlement, one-time charges, or any scenario where only a single payment should be allowed.
You can create a single-payment VA by setting isSingleUse = "N" in the Create VA request.

Virtual Account Amount Types

Virtual accounts provided through Ayoconnect's Virtual Account solution support 2 amount types, depending on your use case:

1. Closed Amount

A Closed Amount VA requires the customer to pay the exact amount stated. It is commonly used for invoices, bills, order payments, subscription billing, or any transaction with a fixed price.
For Indonesia IDR use cases, the decimal portion must always be .00, and the ideal minimum valid amount is IDR 10,000.
You can create a closed amount VA by setting the totalAmount.value to a non-zero value (e.g., "10000.00").

2. Open Amount

An Open Amount VA lets the customer input the payment or bill amount themselves. This is useful for top-up flows, flexible billing, or any situation where the amount depends on the customer.
When Open Amount is used, the VA will accept any paid amount until it expires or becomes inactive.
To create an Open Amount VA, you should either:
1. set totalAmount.value = "0.00"; or
2. exclude the totalAmount field from the Create VA request.

Virtual Account Status

Ayoconnect's Virtual Account solution goes through several lifecycle states based on payment activity and expiry time. Understanding these states helps you manage and interpret VA behavior correctly.

1. Active

The virtual account has been successfully created and is still within its valid period, allowing it to receive payments.

For Multi-Payment VA, the status remains Active even after a payment is made. Each successful payment will be reflected through the fields:

latestPaidAmount
latestPaidTime

Note: Those fields update every time a new payment is received.

2. Inactive-Paid

This state indicates that the Virtual Account has received a successful payment.

This state applies only to single-payment VAs, which become Inactive-Paid immediately after the payment is completed.

Once in this state, the VA is closed and cannot receive additional payments. This behavior ensures that customers cannot accidentally pay twice using the same VA number.

3. Inactive-Expired

This state indicates that the Virtual Account has passed its expiry date and time.

This state applies to both single-payment and multi-payment VAs, and once the VA expire, it will no longer accept payments.

If merchants need to reactivate the VA (e.g., to extend billing or continue payment collection), they must create a new VA or use the Update VA API to adjust the expiry.