Provision virtual accounts
Learn how to issue a dedicated virtual account for a user. Understand how these accounts provide unique details to streamline the process of receiving and sending bank transfers.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to provision a virtual account to a user, which can be used for various collections and payout capabilities offered on the platform.
- You want to provision and attach a virtual account to a user account to facilitate top-ups and payouts (when available).
Prerequisites
- The user profile risk assessment status must not be
risk_flagged. - The user profile must be in an
activestatus. - The user must have an
approvedKYC or KYB status - The user account or wallet must be in an
activestatus. - The virtual account capability must be enabled in the program configuration.
API Workflow
1
Initiate virtual account creation request
Call the Create Virtual Account (POST /users/wallets/cards/types) to initiate the creation of a virtual account for a user.
Create Virtual Account request
curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/virtual_accounts' \
--header 'Content-Type: application/x-www-form-urlencoded' \--header 'X-Auth-user-id: {{user_id}}' \
--header 'Authorization: ••••••'Create Virtual Account response (synchronous creation)
{
"id": "faea7b1d-47bc-4474-a91d-f2c9b6b462b4",
"account_holder_name":"John Doe",
"account_number":"4441234560000123456",
"bank_code": "MAYPSGSGXXX",
"status": "active",
"created_at": "2024-04-29T14:05:49+08:00",
"account_bank_name": "MatchMove Pay Pte Ltd",
}Create Virtual Account response (asynchronous creation)
{
"id": "faea7b1d-47bc-4474-a91d-f2c9b6b462b4",
"account_holder_name":"John Doe",
"account_number":"4441234560000123456",
"bank_code": "DBSSSGSG",
"status": "initialised",
"created_at": "2024-04-29T14:05:49+08:00",
"account_bank_name": "DBS",
"account_bank_address": "12 Marina Boulevard, DBS Asia Central, Marina Bay Financial Centre Tower 3, Singapore 018982",
"account_bank_country": "Singapore"
}You can use this response to display virtual account details in your application. Make sure to display the status clearly to your user:
The virtual account can only accept fund transfers after it has a status active.
Transactions initiated before the status becomes active will be rejected.
Individual Users:
- The virtual account account_holder_name will be based on the registered first_name + middle_name (when available) + last_name of the user.
Business Users:
- The virtual account account_holder_name will be based on the registered business name.
2
Get virtual account details
Call the Get Linked Virtual Account (GET /users/wallets/virtual_accounts) to get the virtual account details of a user.
Get Linked Virtual Account request
curl --location --request GET 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/virtual_accounts' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Get Linked Virtual Account response
{
"total_records": 1,
"records_per_page": 10,
"total_pages": 1,
"page": 1,
"links": [
{
"rel": "self",
"href": "https://beta-api.mmvpay.com/sgmmdemo/v1/users/wallets/virtual_accounts?page=1&records_per_page=10",
"method": "GET"
}
],
"data": [
{
"id": "b98c1bc7-c872-4704-939d-9a37afc0d21a",
"account_holder_name":"John Doe",
"account_number":"4441234560000123456",
"bank_code": "DBSSSGSG",
"status": "pending_activation",
"created_at": "2024-04-29T14:15:38+08:00",
"account_bank_name": "DBS",
"account_bank_address": "12 Marina Boulevard, DBS Asia Central, Marina Bay Financial Centre Tower 3, Singapore 018982",
"account_bank_country": "Singapore"
}
]
}3
[Asynchronous creation] Consume webhooks to be notified of virtual account status updates
Since virtual account creation is asynchronous, you should subscribe to webhooks to be notified of the virtual account status changes.
Virtual Account Advisory webhooks
Partners have the option to subscribe to the webhook events related to virtual account status updates.
INDIVIDUAL_ACCOUNT.VIRTUAL_ACCOUNT.STATUS | A notification is sent in the event that a virtual account of an individual user changes its status. | No action required. |
BUSINESS_ACCOUNT.VIRTUAL_ACCOUNT.STATUS | A notification is sent in the event that a virtual account of a business user changes its status. | No action required. |
Sample virtual account status webhook payload (Individual user)
{
"consumer":
{
"consumer_name":"MatchMove Demo",
"product_code":"sgmmdemo"
},
"account_type": "individual",
"payment_instrument":{
"id":"90eb8e97-cd4f-4c27-a5fe-c136xxxxxxxx",
"payment_instrument_type":"virtual_account",
"status":"active",
"remarks":"created successfully",
"account_number":"4441234560000123456",
"account_holder_name":"John Doe",
"bank_code":"MAYPSGSGXXX"
},
"individual_details":{
"email":"john.doe@acme.com",
"kyc_status":"active",
"mobile":"88888888",
"mobile_country_code":"65",
"id":"547666394dfb916132d0xxxxxxxxxxxx"
},
"webhook_event":"INDIVIDUAL_ACCOUNT.VIRTUAL_ACCOUNT.STATUS"
}Sample virtual account status webhook payload (Business user)
{
"consumer":
{
"consumer_name":"MatchMove Demo",
"product_code":"sgmmdemo"
},
"account_type": "business",
"payment_instrument":{
"id":"90eb8e97-cd4f-4c27-a5fe-c136xxxxxxxx",
"payment_instrument_type":"virtual_account",
"status":"active",
"remarks":"created successfully",
"account_number":"4441234560000123457",
"account_holder_name":"ACME PTE LTD",
"bank_code":"DBSSGSGXXX",
},
"business_details":{
"email":"it@acme.com",
"kyc_status":"active",
"mobile":"88888888",
"mobile_country_code":"65",
"id":"547666394dfb916132d0xxxxxxxxxxxx"
},
"webhook_event":"BUSINESS_ACCOUNT.VIRTUAL_ACCOUNT.STATUS"
}Related Links
On this page
- Provision virtual accounts