Skip to main content

Batch Disbursement

Process Flow

Bulk Disbursement_flow

API Configuration

HTTP Information

Initiate transaction with batch disbursement page

Batch disbursement API provides the ability to implement disbursements to multiple Wallets as per request that supports up to 1000 transactions.

First, it is required to create a initial request returning a mToken for batch-disbursement payments. Access Initiate Transaction to learn more.

Second, Merchant has to create a batch transaction request using the following API:

This API supports Merchant with an option that can check the batch of the Customer’s Wallet status to be able to receive money based on MoMo policies and validate the total amount to the sum amount of the ItemId before implementing a disbursement request.

In addition, to avoid any arising inconvenience during the disbursement process, users are required to comply with the Circular No. 23 of the State Bank of Vietnam: The Wallet must be linked to a bank account and the bank account holder's name must match that of their National ID Card.

For the guideline of Customer Experience with MoMo e-Wallet, click here

HTTP Request

POST /v2/gateway/api/disbursement/batch/create

Header
AttributeTypeRequiredDescription
mTokenStringThe recieved mToken from Initiate API
partnerCodeStringIntegration information
orderIdStringOrderId of partner, this should match the request that has been initiated from Initiate API
requestIdString(50)Request ID, unique for each request

Body
AttributeTypeRequiredDescription
descriptionStringThe description of request
requestTypeStringbatchWallet
disbursementsListList of disbursements method
amountLongThe total amount is used to check the current merchant balance. This total amount must be equal to the sum amount of the ItemId
langStringLanguage of returned message (vi or en)
orderGroupIdLongThe orderGroupId will be provided by MoMo to classify groups of orders for further operational activities. Please contact MoMo to use this field.
signatureStringSignature to confirm information. Secure transaction in Hmac_SHA256 with format: a String sort all key name of data field from a-z:
accessKey=$accessKey&amount=$amount&mToken=$mToken
&orderId=$orderId&partnerCode=$partnerCode
&requestId=$requestId&requestType=$requestType
Details of disbursements content
AttributeTypeRequiredDescription
idStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
methodObjectMethod subject should be including the Receiver information such as: walletId; walletName; personalId.
amountLongamount of the ItemId as specific amount
Currency VND
Min: 1.000 VND; Max: up to 200.000.000 VND (according to the user's receiving limit of funds)
descriptionStringThe description of Disbursement request
Details of method content
ParameterTypeRequiredDescription
walletIdStringMoMo Wallet Number (phone number) needs to transfer money to.
Please proceed with format: 0xxxxx (For Example: 090xx, 0122xx, 034xx)
walletNameStringMoMo Wallet Holder's name
personalIdLongPersonal ID which is issued by Vietnamese government. If this disbursement doesn't require receiver's personal ID to be validated, please leave this field as null.

Example request
{
"lang": "vi",
"ipnUrl": "http://www.example.com",
"requestType": "batchWallet",
"amount": 40000,
"disbursements": [
{
"id": "demo_123_1",
"method": {
"walletId": "0987654321",
"walletName": "Stanley Nguyen",
"personalId": "12345678"
},
"amount": 20000,
"description": "{{description}}"
},
{
"id": "demo_123_2",
"method": {
"walletId": "0987654321",
"walletName": "Stanley Nguyen",
"personalId": "12345678"
},
"amount": 20000,
"description": "{{description}}"
}
],
"description": "Reimbursement for pair of shoes (1)",
"signature": "fd37abbee777e13eaa0d0690d184e4d7e2fb43977281ab0e20701721f07a0e07"
}

HTTP Response

AttributeTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestIdStringEach Request’s Identification
responseTimeLongTime to respond payment results to partner
Format: timestamp
resultCodeIntegerOrder status
messageStringResult description, language is based on lang
totalUploadedAmountLongTotal uploaded amount
totalUploadedCountLongTotal uploaded count

Example response
{
"partnerCode": "MOMOIOLD20190129",
"orderId": "1679474322720OD",
"requestId": "1679474333365id",
"resultCode": 7002,
"message": "Giao dịch đang được xử lý bởi nhà cung cấp loại hình thanh toán.",
"responseTime": 1679474335724,
"totalUploadedCount": 2,
"totalUploadedAmount": 50000
}

Processing payment result

For more information, see Payment Notification.

Parameter description

Description for parameters which are used by MoMo in the body content of ipnUrl

AttributeTypeRequiredDescription
partnerCodeStringIntegration information
requestIdStringEach Request’s Identification
amountLongAmount to Disburse
orderIdStringOrderId of partner, unique for each request
resultCodeIntegerOrder status
messageStringdescription of resultCode based on lang
disbursementBatchInfoObjectextra info for this batch
requestTypeStringbatchWallet
signatureStringSignature to confirm information. Secure transaction in Hmac_SHA256  algorithm with format: a String sort all key name of data field from a-z:
accessKey=$accessKey&amount=$amount&message=$message
&orderId=$orderId&partnerCode=$partnerCode&requestId=
$requestId&requestType=requestType&resultCode=$resultCode
Details of disbursementBatchInfo content
ParameterTypeRequiredDescription
totalUploadedCountIntegerTotal uploaded count
totalUploadedAmountLongTotal uploaded amount
totalSucceedCountIntegerTotal validated count successfully
totalSucceedAmountLongTotal validated amount successfully
totalErrorCountIntegerTotal validated count failed
totalErrorAmountLongTotal validated amount failed

For the resultCode and message fields, partner will handle. Refer to the error code of MoMo to return. MoMo will use these information to give feedback to customers if any error occurs in the payment process from partner side.

Example IPN
{
"amount": 50000,
"partnerCode": "MOMOIOLD20190129",
"requestType": "batchWallet",
"orderId": "1679646807185OD",
"signature": "f5a6d10cb7c3353371f0cb103137d4655761bb91596e0358923a18a0f5f10892",
"requestId": "1679646837530id",
"resultCode": 8003,
"disbursementBatchInfo": {
"totalErrorAmount": 50000,
"totalSucceedAmount": 0,
"totalSucceedCount": 0,
"totalUploadedCount": 2,
"totalUploadedAmount": 50000,
"totalErrorCount": 2
},
"message": "Batch Disbursement Creation request has successfully done."
}

Disburse batch wallet

After get the successful notification from Momo gateway, Merchant must confirm this transaction using the following API. This API is used as trigger step approving created batch disbursement request from previous request.

HTTP Request

POST /v2/gateway/api/disbursement/batch/pay

Body
ParameterTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
This should match the request that has been initiated from Initiate API
requestIdString(50)Request ID, unique for each request
langStringLanguage of returned message (vi or en)
orderGroupIdLongThe orderGroupId will be provided by MoMo to classify groups of orders for further operational activities. Please contact MoMo to use this field.
signatureStringSignature to confirm information. Secure transaction in Hmac_SHA256  algorithm with format, a String sort all key name of data field from a-z:
accessKey=$accessKey&orderId=$orderId&
partnerCode=$partnerCode&requestId=$requestId

Example request
{
"partnerCode": "MOMOIOLD20190129",
"orderId": "12545465654656",
"lang": "vi",
"requestId": "365656d56sd",
"signature": "2c46ac1270b38969c08e2dcc2d939c4a2e0485a12a8583a775378fdd11bb890d"
}

HTTP Response

AttributeTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestIdStringEach Request’s Identification
responseTimeLongTime to respond payment results to partner
Format: timestamp
resultCodeIntegerOrder status
messageStringResult description, language is based on lang
totalUploadedAmountLongTotal Uploaded Amount
totalUploadedCountLongTotal Uploaded Count

Example response
{
"partnerCode": "MOMOIOLD20190129",
"orderId": "1679474322720OD",
"requestId": "1679474333365id",
"resultCode": 7002,
"message": "Giao dịch đang được xử lý bởi nhà cung cấp loại hình thanh toán.",
"responseTime": 1679474335724,
"totalUploadedCount": 2,
"totalUploadedAmount": 50000
}

Processing payment result

For more information, see Payment Notification.

Parameter description

Description for parameters which are used by MoMo in the body content of ipnUrl

AttributeTypeRequiredDescription
partnerCodeStringIntegration information
requestIdStringEach Request’s Identification
amountLongAmount to Disburse
orderIdStringOrderId of partner, unique for each request
resultCodeIntegerOrder status
messageStringdescription of resultCode based on lang
disbursementBatchInfoObjectextra info for this batch
requestTypeStringbatchWallet
signatureStringSignature to confirm information. Secure transaction in Hmac_SHA256  algorithm with format: a String sort all key name of data field from a-z:
accessKey=$accessKey&amount=$amount&message=$message
&orderId=$orderId&partnerCode=$partnerCode&requestId=
$requestId&requestType=requestType&resultCode=$resultCode
Details of method content
ParameterTypeRequiredDescription
totalUploadedCountIntegerTotal uploaded count
totalUploadedAmountLongTotal uploaded amount
totalSucceedCountIntegerTotal disbursed count successfully
totalSucceedAmountLongTotal disbursed amount successfully
totalErrorCountIntegerTotal validated count failed
totalErrorAmountLongTotal validated amount failed

For the resultCode and message fields, partner will handle. Refer to the error code of MoMo to return. MoMo will use these information to give feedback to customers if any error occurs in the payment process from partner side.

Example IPN
{
"amount": 50000,
"partnerCode": "MOMOIOLD20190129",
"requestType": "batchWallet",
"orderId": "1679646807185OD",
"signature": "f5a6d10cb7c3353371f0cb103137d4655761bb91596e0358923a18a0f5f10892",
"requestId": "1679646837530id",
"resultCode": 0,
"disbursementBatchInfo": {
"totalErrorAmount": 50000,
"totalErrorCount": 2,
"totalSucceedAmount": 0,
"totalSucceedCount": 0,
"totalUploadedCount": 2,
"totalUploadedAmount": 50000
},
"message": "success"
}

Query batch disbursements details

After receiving notifications from MOMO through IPN channel, Merchant should query batch disbursement results by using query API

HTTP Request

POST /v2/gateway/api/disbursement/batch/query

Body
AttributeTypeRequiredDescription
partnerCodeStringIntegration information
requestIdStringEach Request’s Identification
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
pageSizeLongMax entry count in a page, max value is 50
pageNumLongOffset of records to show (Default: 1)
statesSetSet of states for filtering. There are several available states regarding each process:
1. After creating the batch disbursement request.
- INELIGIBLE: Disabled to disburse due to restricted wallets.
- ELIGIBLE: Abled to disburse.
2. After paying the batch disbursement.
- INELIGIBLE: Disabled to disburse due to restricted wallets at the creation stage.
- SUCCEEDED: Disbursed successfully
- FAILED: Failed to Disburse.
- PENDING: Transaction is still being processed.
If this field is not specified, filtering will not be applied and the response includes the whole of the items.
langStringLanguage of returned message (vi or en)
signatureStringSignature to confirm information. Secure transaction in Hmac_SHA256  algorithm with format: a String sort all key name of data field from a-z:
accessKey=$accessKey&orderId=$orderId&pageNum=$pageNum&pageSize=
$pageSize&partnerCode=$partnerCode&requestId=$requestId

Example request
{
"partnerCode": "MOMOIOLD20190129",
"orderId": "1679474592682OD",
"lang": "en",
"requestId": "1679474813399id",
"pageSize": "50",
"states": ["SUCCEEDED"],
"pageNum": "2",
"signature": "21fa2be737bbb6619832948d3964da3d1c9422773a5fab9ee26b2b97423b5ac2"
}

HTTP Response

AttributeTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestIdStringEach Request’s Identification
responseTimeLongTime to respond payment results to partner
Format: timestamp
resultCodeIntegerOrder status
messageStringResult description, language is based on lang
totalUploadedCountIntegerTotal uploaded count
totalUploadedAmountLongTotal uploaded amount
totalSucceedCountIntegerTotal validated/disbursed count successfully
totalSucceedAmountLongTotal validated/disbursed amount successfully
totalErrorCountIntegerTotal validated/dibursed count failed
totalErrorAmountLongTotal validated/disbursed amount failed
disbursementsListList of disbursments method
pageNumLongCurrent page number
pageSizeLongMax entry count in a page, max value is 50
totalPagesLongTotal number of pages that contain transaction level data

Example response for querying after checking the batch
{
"partnerCode": "MOMOIOLD20190129",
"orderId": "1679474592682OD",
"requestId": "1679476626944id",
"resultCode": 0,
"message": "Thành công.",
"responseTime": 1679476627432,
"totalUploadedCount": 100,
"totalUploadedAmount": 1000000,
"totalErrorCount": 0,
"totalErrorAmount": 0,
"totalSucceedCount": 100,
"totalSucceedAmount": 1000000,
"pageNum": 1,
"pageSize": 2,
"totalPages": 50,
"disbursements": [
{
"id": "16794746174061",
"method": {
"walletId": "0383786432",
"walletName": "nguyen van a"
},
"amount": 10000,
"description": "Test batch",
"resultCode": 0,
"message": "Thành công.",
"transId": 2955165078,
"state": "SUCCEEDED"
},
{
"id": "16794746174060",
"method": {
"walletId": "0383786432",
"walletName": "nguyen van a"
},
"amount": 10000,
"description": "Test batch",
"resultCode": 0,
"message": "Thành công.",
"transId": 2955165080,
"state": "SUCCEEDED"
}
]
}

Result Codes & Messages

These result codes and messages are exclusively assigned for the Batch Disbursement process. Additionally, kindly locate other result codes and messages in the comprehensive list of result codes provided here.

Result codeDescriptionFinal statusRecommended actions
0Successful.Yes
1007Transaction rejected due to inactive or nonexistent user's account.YesPlease ensure the account status should be active/ verified before retrying or contact MoMo for support.
1100Merchant Balance is insufficient fund to proceed the transaction. Please contact MoMo for the support.YesPlease contact MoMo to top-up Merchant Balance to continue with the transaction.
2001Transaction failed due to invalid token.YesThe token does not exist or has been deleted, please update accordingly.
2019Request rejected due to invalid orderGroupId.YesPlease contact MoMo for the restriction details.
7002Transaction is being processed by the provider of the payment instrument selected.NoPlease wait for the transaction to be processed. The transaction status will be notified once it's done processing.
7000Transaction is being processed.NoPlease wait for the transaction to be fully processed.
8003Batch Disbursement Creation request has successfully done.NoPlease request to implement batch disbursement to complete the process.

For further understanding of the state of each ItemId based on the batch disbursement, please follow the status of batch disbursement has been updated as below.

State ResultDescription
INELIGIBLERestricted Wallet. The Wallet didn't meet MoMo policies for the disbursement process.
ELIGIBLEValid Wallet. The Wallet was able to proceed with the disbursement process after validating.
SUCCEEDEDDisbursed Successfully. MoMo has processed the fund transfer to Receiver.
PENDINGTransaction Processing. MoMo is processing the fund.
FAILEDFailed to Disburse. MoMo couldn’t proceed with the batch disbursed request, rejection due to Bad Format; Invalid Request, or Restricted User Account ...
The detailed status of each ItemId error result, please check link for reference.

See also