Virtual accounts are unique account numbers assigned within traditional, physical bank accounts, which are also known as settlement accounts. They can be used to send and receive money on behalf of the settlement account, where the funds are ultimately held. Payments made to Virtual Accounts are faster, more accessible, and easier to be identified, whilst compared to bank transfer, where customers have to provide proof of payment after the bank transfer is made. This service allows merchants to accept payments from their customers using Virtual Accounts. ## Overview Currently, this service can be accessed via APIs only and provides Virtual Accounts for the following banks: | Bank | Bank Code | Dynamic Virtual Accounts
(single use) | Static Virtual Accounts
(multiple use) | |-------------|-----------|-------------------------------------------|--------------------------------------------| | __BNI__ | 009 |

| | __BRI__ | 002 |

| | __Mandiri__ | 008 |

| ## Flows A flow is a set of API calls for a Virtual Account, and all the calls related to a Virtual Account are part of one flow.

Flows are an important part in the Virtual Account APIs as there are some limitations in the values of 'A-Correlation-ID' header. Currently, there are 3 flows defined (create, check status, and update Virtual Account). Here you can see how to perform each flow: | _Flow_ | _API_ | _API Operations_ | |------------------|-------|------------------| | __Create__ |

| Create a Virtual Account | | __Check Status__ |

| Check the status of created Virtual Account | | __Update__ |

| Update, Cancel, Expire or re-use a created Virtual Account | Each of these flows contains some endpoints that require a unique 'A-Correlation-ID' header (you can't share the same header with more than one flow).
For example, if you have a 'Create Virtual Account' flow with a 'A-Correlation-ID' header of '12345', you can't use the same 'A-Correlation-ID' header again in the 'Create Virtual Account' flow. ## Callbacks A callback to the merchant will be sent: - After merchant's customer makes a successful payment on a created Virtual Account number As a merchant, you need to provide callback URLs to the Ayoconnect Virtual Account team during the onboarding process. Only POST requests are allowed and a 201 HTTP response code is expected for all the callbacks. If a 40X or 50X HTTP response code is returned, the process won't continue. In case of any other error, Ayoconnect will try to send the callback 3 more times after 5, 10, and 30 seconds. After this, no further attempt will be made. ### Callbacks authentication Currently, only 2 authentication methods are supported for the callbacks received from Ayoconnect: | Type | Description | |-------|--------------------------------------------------------------| | None | No authorization/authentication (default) | | Basic | The token provided by Ayoconnect is unique for each merchant | ### Callback URL for the status of a created Virtual Account The callback URL will be used to notify the merchant about status of a created Virtual Account. On successful payment on a Virtual Account number, a callback will be sent immediately. #### Callback headers The following headers are included in all the callbacks received from Ayoconnect: | Header | Value | Description | |---------------|------------------|----------------------------------| | Accept | application/json | Accept type of response body | | Content-Type | application/json | Content type of the request body | | Authorization | Basic {token} | The authorization token can be used by the merchant to verify the authenticity of the callback.
This header is optional: it won't be sent unless the merchant requires it from Ayoconnect | #### Callback fields The following parameters are included in the callbacks received from Ayoconnect: | Name | Type | Required | Example | Description | |---------------------|-------------|----------|----------------------------------|---------------------------------------------------------------------| | code | int | Y | 200 | Product response code | | message | string | Y | ok | Response message | | virtualAccountData | JSON Object | Y | {} | Details of a Virtual Account | Contents of the 'virtualAccountData' fields: | Name | Type | Required | Value | Description | |----------------------|-------------|----------|------------------------------------------|---------------------------------------------------------------------------------------------------| | virtualAccountId | string | Y | cwr4gmbiihdh2yk7cveah1p7loe | Unique identifier (27 alphanumeric characters) to identify the associated Virtual Account. | | virtualAccountNumber | string | Y | 8888800145536217 | Unique identifier (16 numeric characters) to do transactions on a Virtual Account. | | virtualAccountStatus | string | Y | PAID | Status of the Virtual Account number | | virtualAccountName | string | Y | Ayoconnect | Returned by Create Virtual Account API. Name of the customer. | | virtualAccountPhone | string | Y | 62796335646 | Returned by Create Virtual Account API. Phone Number of the customer. | | correlationId | string | Y | 1j7grzo76qx7lnihy5fctk563petjk45 | Unique identifier used while generating the Virtual Account | | customerId | string | Y | AYOAPP-559PAC23 | Ayoconnect's CustomerId. AlphaNumeric. | | totalAmount | JSON Object | Y | {"value": "25000.00", "currency": "IDR"} | Total amount the customer has paid successfully historically through this Virtual Account number. | | billAmount | JSON Object | Y | {"value": "12500.00", "currency": "IDR"} | The amount received by the client from this transaction after the fees. | | adminFee | JSON Object | Y | {"value": "2500.00", "currency": "IDR"} | The total fees charged to the client for this transaction. | | billDetails | array | Y | [] | The breakdown of the transaction details including item name, item value, and description given to Ayoconnect by the client. A list with one item only. | | paymentDetails | JSON Object | Y | {"value": "12500.00", "currency": "IDR"} | The amount paid by the customer for this transaction. | List of 'billDetails' contains JSON Object with fields: | Name | Type | Required | Value | Description | |-----------------|--------------|----------|-------------------------------------------------------|------------------------------------------------| | billName | string | Y | API Product | Returned by the 'Create a Virtual Account' API | | billAmount | JSON Object | Y | {"value": "12500.00", "currency": "IDR"} | Returned by the 'Create a Virtual Account' API | | billDescription | JSON Object | N | {"english": "Va trx", "indonesia": "Transaksi va"} | Returned by the 'Create a Virtual Account' API | ##### Callback URL sample request ```json { "code": 200, "message": "ok", "virtualAccountData": { "virtualAccountId": "2405121557574135743HROOUVXY", "virtualAccountNumber": "1896520138004558", "virtualAccountStatus": "PAID", "virtualAccountName": "AyoconnectTest", "virtualAccountPhone": "62988484815", "correlationId": "1237000000001000123456789024475k", "customerId": "AYOPOP-GCINRJ2946", "totalAmount": { "value": "25000.00", "currency": "IDR" }, "billAmount": { "value": "12500.00", "currency": "IDR" }, "adminFee": { "value": "2500.00", "currency": "IDR" }, "billDetails": [ { "billName": "API Product", "billAmount": { "value": "12500.00", "currency": "IDR" }, "billDescription": { "english": "Virtual account transaction", "indonesia": "Transaksi akun virtual" } } ], "paymentDetails": { "trxRefID": "2362", "amount": "12500.00" } } } ```