Create a recipient for domestic payment
Learn how to securely store a beneficiary's local bank account details for future use. This guide helps you understand the process of creating reusable recipient profiles for domestic bank transfers.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to implement a feature that will allow users to withdraw funds to a domestic/local bank account.
- You want to implement a feature that will allow users to define their beneficiary recipient before performing a bank withdrawal.
- You want to implement a feature that will allow users to reuse their previously defined beneficiary recipients for withdrawals.
Prerequisites
- The user must have an
approvedKYC status. - The user profile must be in an
activestatus. - The user profile risk assessment status must not be
risk_flagged(v1). This is not applicable in v2. - The user account or wallet must be in an
activestatus. - The user's virtual account must be in an
activestatus.
API Workflow
1
Retrieve the list of available local banks for transfer
In the domestic recipient creation form on the partner application, we need to let the customer (sender) choose from the selection of available banks that can receive a domestic transfer. If the customer's intended bank is not in the selection, then we should not allow him to proceed with the domestic recipient definition.
Call the List Domestic Payout Transfer Agent Enumerations (GET /users/wallets/payouts/domestic/enumerations/transfer_agents) to retrieve the list of available local banks that can receive a domestic transfer. It is important to filter only the active banks during a particular timeframe, as receiving banks may go on maintenance and be unavailable for certain periods of time.
In the below example, the status=active filter is added to only retrieve currently available banks for transfer.
Please note that the value of the bank code will be agent_code returned in the response.
List Domestic Payout Transfer Agent Enumerations request
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/enumerations/transfer_agents?status=active' \
--header 'Authorization: ••••••'
*Please note that this is a special API that needs to be called in admin scope, without passing X-Auth-User-ID.
List Domestic Payout Transfer Agent Enumerations response
{
"total_records": 37,
"records_per_page": 37,
"total_pages": 1,
"page": 1,
"links": [
{
"rel": "self",
"href": "https://{{server}}/{{program_code}}/v1/users/wallets/payouts/domestic/enumerations/transfer_agents?page=1&records_per_page=10&return_all=true&status=active",
"method": "GET"
}
],
"data": [
{
"agent_code": "ANZBSGS0XXX",
"agent_logo": "https://assets.mmvpay.com/sg/domestic_transfer_agents/ANZ_BANK.png",
"mode": "bank",
"name": "ANZ Bank",
"status": "active",
"bic_code": "ANZBSGS0XXX",
"fees": {
"fixed": "0.000000",
"percentage": "0.000000",
"variable": "",
"fee_calculation_type": ""
},
"transfer_details": [
{
"channel_id": "382dd1f29f9411ec875a02b5044dcedc",
"channel": "FAST",
"min_transfer_amount": "0.01",
"max_transfer_amount": "200000.00",
"transfer_fulfillment_time": "Instant"
}
],
"account_number_regex": "^[0-9]*$",
"account_number_min_length": "5",
"account_number_max_length": "34"
},
{
"agent_code": "BKCHSGS0XXX",
"agent_logo": "https://assets.mmvpay.com/sg/domestic_transfer_agents/BANK_OF_CHINA_CREDIT_CARD.png",
"mode": "bank",
"name": "Bank of China Credit Card",
"status": "active",
"bic_code": "BKCHSGS0XXX",
"fees": {
"fixed": "0.000000",
"percentage": "0.000000",
"variable": "",
"fee_calculation_type": ""
},
"transfer_details": [
{
"channel_id": "382dd1f29f9411ec875a02b5044dcedc",
"channel": "FAST",
"min_transfer_amount": "0.01",
"max_transfer_amount": "200000.00",
"transfer_fulfillment_time": "Instant"
}
],
"account_number_regex": "^[0-9]*$",
"account_number_min_length": "5",
"account_number_max_length": "34"
},
..
]
}
Note:
The available domestic banks (agent_code) list will be different between staging and live environments. Please refrain from hard-coding any agent_code and always pull the updated list from the Domestic Transfer Agents Enumerations API.
2
Define a beneficiary account
Before initiating an outgoing transfer through virtual accounts, a beneficiary account must be defined first.
Call Create Domestic Payout Recipients (POST /users/wallets/payouts/domestic/bank_accounts) passing the beneficiary's local bank account information.
Create Domestic Payout Recipients request
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/bank_accounts' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••'' \
--data-urlencode 'bank_holder_name=Juan Smith' \
--data-urlencode 'bank_code=<agent_code>' \
--data-urlencode 'bank_account_number=5543213122'
Create Domestic Payout Recipients response
{
"id": "9d1a885d-b264-4b73-9057-eec2565a49c3",
"bank_account_number": "5543213122",
"bank_holder_name": "Juan Smith",
"bank_code": "<agent_code>",
"bank_name": "Bank Name",
"mode": "bank",
"entity_type": null,
"status": "active",
"is_active": 1,
"created_at": "2025-08-07T16:14:45+08:00",
"updated_at": "2025-08-07T16:14:45+08:00",
"activated_at": "2025-08-07T16:14:45+08:00"
}
Recipient Cooling-Off Period - Domestic
A cooling-off period is a mandatory waiting timeframe that restricts account functions like withdrawals and transfers. This safeguard prevents system abuse and provides a "buffer" to detect fraudulent activity before funds move.
In the MatchMove platform, this period occurs between a recipient's creation and activation. It acts as a primary fraud prevention layer, ensuring suspicious actions are intercepted before payouts are authorized.
Timing and Logic
- Initial State: Upon creation, the recipient's
user.statusis set toPENDING_ACTIVATION. - Cooling Period: This waiting period runs simultaneously with the risk evaluation. The recipient will remain in the
PENDING_ACTIVATIONstate until the cooling period lapses.
Activation Requirements
- Becoming Active: Both the cooling period and the risk evaluation must independently finish before the recipient's status transitions to
ACTIVE. - Sending Payouts: Domestic payouts can only be sent to
ACTIVErecipients. Any attempt to send funds to a recipient in a different state will be blocked by the platform.
3
Delete a beneficiary account (optional)
Call Delete Domestic Payout Recipients (DELETE /users/wallets/payouts/domestic/bank_accounts) passing the beneficiary's generated beneficiary ID.
Delete Domestic Payout Recipients request
curl --location --request DELETE 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/bank_accounts' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'id=1c255d6e-2f4c-41a6-b380-ac6cb512de70'
Delete Domestic Payout Recipients response
{
"status": "deleted"
}
4
Monitor for domestic beneficiary status
The Virtual Account Advisory webhook category is available for partners who want to get timely feedback on virtual account events.
Listed below are the webhook events available for domestic beneficiary creation and the appropriate action required when they are received.
PAYOUT.RECIPIENT.DOMESTIC.STATUS | A notification is sent when the domestic beneficiary status has changed. | No action required |
Related Links
On this page
- Create a recipient for domestic payment