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 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 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 Get Domestic Transfer Agents 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.
Get Domestic Transfer Agents 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.
Get Domestic Transfer Agents 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 New Beneficiary Bank Account (POST /users/wallets/payouts/domestic/bank_accounts) passing the beneficiary's local bank account information.
Create New Beneficiary Bank Account 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 New Beneficiary Bank Account 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.
The newly created recipient will remain in the PENDING_ACTIVATION status until the cooling period has been completed.
A recipient can only be used for a domestic payout transaction when its status is already ACTIVE.
3
Delete a beneficiary account (optional)
Call Delete Beneficiary Bank Account (DELETE /users/wallets/payouts/domestic/bank_accounts) passing the beneficiary's generated beneficiary ID.
Delete Beneficiary Bank Account 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 Beneficiary Bank Account response
{
"status": "deleted"
}Related Links
On this page
- Create a recipient for domestic payment