Create Virtual Account

The Create Virtual Account feature allows merchants to generate Virtual Account (VA) numbers that customers can use to make payments. This is the entry point of the Virtual Account lifecycle.

Through this API, merchants can configure the VA according to the operational needs:

1. Generate a Virtual Account Number

You may provide your own custom VA number (by following each bank’s digit-length rules), or Ayoconnect generate a unique VA number automatically by leaving virtualAccountNo empty.

2. Define the payment amount behavior (Amount Type)

Set how the VA handles payment amounts:

Closed Amount: set totalAmount.value > 0
Open Amount: set totalAmount.value = "0.00" or leave totalAmount out of the request.

3. Define the payment usage behavior (Virtual Account Type)

Choose whether the VA can be paid once or multiple times:

Multi-Payment VA: additionalInfo.isSingleUse = "N" - allows multiple payments until expiry.
Single-Payment VA: additionalInfo.isSingleUse = "Y" - deactivates immediately after one successful payment.

4. Set the VA expiration date

Configure the VA's validity by setting the expiredDate field in ISO 8601 format.
If the merchant does not provide an expiry value, Ayoconnect will apply a default expiry of 10 minutes.

Note: Once the VA reaches its expiry time, it can no longer receive payments unless it is updated or recreated.

Supported VA Configurations

VA Banks	Single Payment VA - Closed Amount	Multiple Payment VA - Closed Amount	Single Payment VA - Open Amount	Multiple Payment VA - Open Amount	Max VA Numbers Input In M-Banking	Min. Length in custom VA number Creation	Max. Length in custom VA number Creation
Bank BRI	✅	✅	✅	✅	18 digits	11 digits	13 digits
Bank BNI	✅	❌	✅	✅	16 digits	12 digits	12 digits
Bank BCA	✅	✅	✅	✅	23 digits	11 digits	18 digits
Bank Mandiri	✅	✅	✅	✅	19 digits	11 digits	14 digits

Custom Virtual Account Number Rules

When creating a custom Virtual Account number:

You only need to provide the remaining digits (based on the minimum and maximum length listed in the table above) in the virtualAccountNo field.
Ayoconnect will automatically add the correct bank prefix based on the selected additionalInfo.bankCode.
The final Virtual Account number returned in the Create VA response will always be: prefix + your custom digits.

Example:

If the BRI prefix is 14629 and you send:
"virtualAccountNo": "12345678901"

Then the Create VA response will return the complete VA number: 1462912345678901

Limitations

Please note that only the following combinations are supported when creating a virtual account:

In VA Number creation request, if a merchant would like to create a custom VA numbers after bank prefix, just send the remaining numbers (excluding prefix) in the field of virtualAccountNumber. Ayoconnect will return the complete VA numbers (Including bank prefix) in the response of Create Virtual Account API.