Batch Disbursement

Process 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

Attribute	Type	Required	Description
mToken	String		The recieved mToken from Initiate API
partnerCode	String		Integration information
orderId	String		OrderId of partner, this should match the request that has been initiated from Initiate API
requestId	String(50)		Request ID, unique for each request

Body

Attribute	Type	Required	Description
description	String		The description of request
requestType	String		batchWallet
disbursements	List		List of disbursements method
amount	Long		The total amount is used to check the current merchant balance. This total amount must be equal to the sum amount of the ItemId
lang	String		Language of returned message (vi or en)
orderGroupId	Long		The orderGroupId will be provided by MoMo to classify groups of orders for further operational activities. Please contact MoMo to use this field.
signature	String		Signature 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

Attribute	Type	Required	Description
id	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
method	Object		Method subject should be including the Receiver information such as: walletId; walletName; personalId.
amount	Long		amount 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)
description	String		The description of Disbursement request

Details of method content

Parameter	Type	Required	Description
walletId	String		MoMo Wallet Number (phone number) needs to transfer money to. Please proceed with format: 0xxxxx (For Example: 090xx, 0122xx, 034xx)
walletName	String		MoMo Wallet Holder's name
personalId	Long		Personal 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

Attribute	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestId	String		Each Request’s Identification
responseTime	Long		Time to respond payment results to partner Format: timestamp
resultCode	Integer		Order status
message	String		Result description, language is based on lang
totalUploadedAmount	Long		Total uploaded amount
totalUploadedCount	Long		Total 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

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Each Request’s Identification
amount	Long		Amount to Disburse
orderId	String		OrderId of partner, unique for each request
resultCode	Integer		Order status
message	String		description of resultCode based on lang
disbursementBatchInfo	Object		extra info for this batch
requestType	String		batchWallet
signature	String		Signature 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

Parameter	Type	Required	Description
totalUploadedCount	Integer		Total uploaded count
totalUploadedAmount	Long		Total uploaded amount
totalSucceedCount	Integer		Total validated count successfully
totalSucceedAmount	Long		Total validated amount successfully
totalErrorCount	Integer		Total validated count failed
totalErrorAmount	Long		Total 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

Parameter	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$ This should match the request that has been initiated from Initiate API
requestId	String(50)		Request ID, unique for each request
lang	String		Language of returned message (vi or en)
orderGroupId	Long		The orderGroupId will be provided by MoMo to classify groups of orders for further operational activities. Please contact MoMo to use this field.
signature	String		Signature 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

Attribute	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestId	String		Each Request’s Identification
responseTime	Long		Time to respond payment results to partner Format: timestamp
resultCode	Integer		Order status
message	String		Result description, language is based on lang
totalUploadedAmount	Long		Total Uploaded Amount
totalUploadedCount	Long		Total 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

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Each Request’s Identification
amount	Long		Amount to Disburse
orderId	String		OrderId of partner, unique for each request
resultCode	Integer		Order status
message	String		description of resultCode based on lang
disbursementBatchInfo	Object		extra info for this batch
requestType	String		batchWallet
signature	String		Signature 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

Parameter	Type	Required	Description
totalUploadedCount	Integer		Total uploaded count
totalUploadedAmount	Long		Total uploaded amount
totalSucceedCount	Integer		Total disbursed count successfully
totalSucceedAmount	Long		Total disbursed amount successfully
totalErrorCount	Integer		Total validated count failed
totalErrorAmount	Long		Total 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

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Each Request’s Identification
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
pageSize	Long		Max entry count in a page, max value is 50
pageNum	Long		Offset of records to show (Default: 1)
states	Set		Set 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.
lang	String		Language of returned message (vi or en)
signature	String		Signature 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

Attribute	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestId	String		Each Request’s Identification
responseTime	Long		Time to respond payment results to partner Format: timestamp
resultCode	Integer		Order status
message	String		Result description, language is based on lang
totalUploadedCount	Integer		Total uploaded count
totalUploadedAmount	Long		Total uploaded amount
totalSucceedCount	Integer		Total validated/disbursed count successfully
totalSucceedAmount	Long		Total validated/disbursed amount successfully
totalErrorCount	Integer		Total validated/dibursed count failed
totalErrorAmount	Long		Total validated/disbursed amount failed
disbursements	List		List of disbursments method
pageNum	Long		Current page number
pageSize	Long		Max entry count in a page, max value is 50
totalPages	Long		Total 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 code	Description	Final status	Recommended actions
0	Successful.	Yes
1007	Transaction rejected due to inactive or nonexistent user's account.	Yes	Please ensure the account status should be active/ verified before retrying or contact MoMo for support.
1100	Merchant Balance is insufficient fund to proceed the transaction. Please contact MoMo for the support.	Yes	Please contact MoMo to top-up Merchant Balance to continue with the transaction.
2001	Transaction failed due to invalid token.	Yes	The token does not exist or has been deleted, please update accordingly.
2019	Request rejected due to invalid orderGroupId.	Yes	Please contact MoMo for the restriction details.
7002	Transaction is being processed by the provider of the payment instrument selected.	No	Please wait for the transaction to be processed. The transaction status will be notified once it's done processing.
7000	Transaction is being processed.	No	Please wait for the transaction to be fully processed.
8003	Batch Disbursement Creation request has successfully done.	No	Please 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 Result	Description
INELIGIBLE	Restricted Wallet. The Wallet didn't meet MoMo policies for the disbursement process.
ELIGIBLE	Valid Wallet. The Wallet was able to proceed with the disbursement process after validating.
SUCCEEDED	Disbursed Successfully. MoMo has processed the fund transfer to Receiver.
PENDING	Transaction Processing. MoMo is processing the fund.
FAILED	Failed 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

• Check Transaction Status
• Reverse & Refund
• Confirm Payment