Receive funds from a bank account

1

Retrieve and display the customer's Virtual Account (VA) details

Call Get Linked Virtual Accounts (GET /users/wallets/virtual_accounts) to get the virtual account details that have been provisioned to the customer.

Get Linked Virtual Accounts request

 
curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/virtual_accounts' \
--header 'X-Auth-User-ID: <user_id>' \
--header 'Authorization: ••••••'

Get Linked Virtual Accounts response

 
{
    "total_records": 1,
    "records_per_page": 10,
    "total_pages": 1,
    "page": 1,
    "links": [
        {
            "rel": "self",
            "href": "https://beta-api.mmvpay.com/<program_code>/v1/users/wallets/virtual_accounts?page=1&records_per_page=10",
            "method": "GET"
        }
    ],
    "data": [
        {
            "id": "24aae1c1-d382-45d6-b8eb-b1b69bb1be9c",
            "account_id": "a574bd62-6bf1-458e-7b51-3b95c2dbefb2",
            "account_no": "685395021205085935",
            "account_holder_name": "John Smith",
            "account_number": "885395021205085135",
            "bank_code": "DBSSSGSG",
            "status": "active",
            "created_at": "2025-07-15T12:20:07+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"
        }
    ]
}

Before the customer can initiate a bank transfer to the virtual account, they will need a reference to the virtual account details. These details are required as input to the external bank online fund transfer form:

• "account_holder_name": "John Smith",
• "account_number": "885395021205085135",
• "bank_code": "DBSSSGSG",
• "account_bank_name": "DBS"

These virtual account details will need to be displayed on the app's frontend and made accessible to customers.

2

Initiate a bank transfer/deposit from the external bank

The “incoming fund” transfer will be initiated from the external bank's online application. The external bank's beneficiary details must be filled with the MatchMove virtual account details.

With the increasing prevalence of online fraud and digital scams, MatchMove has instituted a new security measure. A 'Fuzzy Name Matching' validation has been added for all funds being received through the Virtual Account network

This validation will be applied to the beneficiary name from the external depository bank and the bank holder name of the MatchMove virtual account. This would ensure that the fund beneficiary is really the intended recipient of the depositor.

Once the account number and name match are validated, the deposit transaction will be received. Otherwise, the transaction will be rejected.

Fuzzy Name Matching Logic

This is a probabilistic matching technique that identifies word matches using linguistic and statistical analysis, accepting only those that meet a set threshold.

4

Monitor for events happening on virtual accounts

Once the bank transfer/deposit transaction is executed from the external bank, the funds will arrive on MatchMove after the bank network has processed the transfer instruction. This transfer instruction processing time will depend on the external bank SLA with the bank network.

The Virtual Account Advisory webhook category is available for partners who want to get timely feedback on virtual account events. If a failure or rejection happens, the webhook payload will contain a reason for rejection.

Go to the Leveraging Webhooks section to learn more about setting up the webhooks.

Virtual Account Advisory webhooks

Partners have the option to subscribe to the webhook events related to bank collections.

These webhooks are prefixed and classified per the account type of the virtual account owner:

• CONSUMER_ - Individual customer
• BUSINESS_ - Business customer
• CORPORATE_ - Main partner or program owner

Sample webhook payload

 
{
    "consumer":
    {
        "consumer_name": "CLIENT NAME",
        "prefund_balance": "1349581.800000"
    },
    "debit_credit_indicator": "C",
    "deducted_amount": "1.950000",
    "fee_charged": "0.000000",
    "payment_instrument":
    {
        "status": "active",
        "transaction_instrument_id": "hashidofcard",
        "virtual_account_number": "6377022712345678",
        "wallet_number": "6377022712345678"
    },
    "time_stamp": "2023-07-27T14:27:45+08:00",
    "total_amount": "1.950000",
    "total_currency": "SGD",
    "transaction":
    {
        "client_ref_id": "CLIENREF001",
        "purpose_of_transfer": "OTHR",
        "transaction_message": "Transfer from 6377022712345678 success",
        "transaction_ref": "CREDIT-generatedtransactionref",
        "transaction_status": "success",
        "transfer_in":
        {
            "destination_account":
            {
                "bank_account_number": "6377022712345678",
                "bank_code": "MAYPSGS0XXX",
                "bank_holder_name": "MM HOLDER NAME"
            },
            "source_account":
            {
                "bank_account_number": "12345678",
                "bank_code": "DBSSSGS0XXX",
                "bank_holder_name": "BANK HOLDER NAME"
            }
        }
    },
    "user":
    {
        "email": "mmuser@matchmove.com",
        "kyc_status": "active",
        "mobile": "12345678",
        "mobile_country_code": "65",
        "user_hash": "hashidofuser"
    },
    "webhook_event": "CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS"
}