Single Disbursement

Process Flow

API Configuration

HTTP Information

Check Wallet Status

This API provides Merchant an option that can check the status of the Customer’s Wallet to be able to receive money based on MoMo policies 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. 40 of the State Bank of Vietnam as the conditions below:

1. MoMo User must be at least 18 years old to use the account (calculated from their date of birth to the current date). In cases where the user is under 18 years old, they must have a verified signature on the account opening form at the bank.
   
2. The MoMo user's account must have completed verification via NFC C06.
   
3. The MoMo user's account must be linked to a bank account or NAPAS card at the time of receiving money. (The account 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/verify

Parameter	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestId	String(50)		Request ID, unique for each request
requestType	String		checkWallet
disbursementMethod	String		Encrypt a object json by RSA using public Key RSA Encryption
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&disbursementMethod= $disbursementMethod&orderId=$orderId& partnerCode=$partnerCode& requestId=$requestId&requestType=$requestType

Data of disbursementMethod before encrypted: API Check Wallet Status

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

{
  "partnerCode": "MOMOIOLD20190129",
  "orderId": "12545465654656",
  "lang": "vi",
  "requestId": "365656d56sd",
  "requestType": "checkWallet",
  "disbursementMethod": "mo6dgtb5nz7W91O3MQNr1cuR8rnggp4J23dNEn8K0PTIWQcZtd/Zu/fGXpNkTJoZvPcwb9awqi8ZxHEIZu/fByS6vqirlqjpAbsNlXA5OsfxbDKjtkbbcz6Xi7ryI8Rlx8X4LrjshCcvnyHlCFQNBZrBHdjQXm/gfDli/1nfg2IjrBqW2o9Msc5VWRh5vGQdSGfsoo3CCJPFL3/jPEw2J3032pUPbD7zbpsFkYbYKGfszXa4Eyff1XuBWBu0zvtPTfpWS3pl238pgw0ObBWua0SDYPNtXv41sZuadURpDr/Mj9/WNL/lGuPWs2ILShr/9OOHB+l9uuS/J+50hqDLDIWcTS5ir2640eDcoq8HOpvu/hU7jiDGsRzSFO7iYUgehzDSheaGjvRlmtuhGJ3josHKhHIrAS2kckIBTNw7EjuATDlf2a4yOZLLsniXbSB2r/IvfPe0ZRPAD8euzIFpXasxlr4bj1VUEMuHP6ep0UrGfHrCfoWDbIbbmpuMVqhXWI1kmS9YD59hxSaJvwqkaWDkjIY2s6uWgbKno4YAv4uzxexAbIe8Z4UfILPrKhxh3pcxbnPXIZNzgslxAPEvgg2dtodjIUlUYSHg32A/gPCGXdvEVZOPBsuiGe5QkDS0uXdTNyCaNsiWUwxB74yikfCxrCNN1IOH2XZJRJfTjbc=",
  "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

Example response

{
   "partnerCode": "MOMOIOLD20190129",
   "orderId": "OD1675914157849",
   "requestId": "RE1675914157849",
   "responseTime": 1675914162783,
   "message": "Successful.",
   "resultCode": 0
}

Response Codes and Messages: API Check Wallet Status

These are some response codes which are only used for Check Wallet Status process:

Response code	Description	Final status	Recommended actions
0	Successful	Yes
10	Server connection error.	No	Please retry after the maintenance is over.
20	Bad format request.	No	Please check the request format or any missing parameters.
99	Unknown error.	Yes	Please contact MoMo for more details.
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.
4001	Transaction rejected because the user account is being restricted.	Yes	Please contact MoMo for the restriction details of this certain user account.
4003	Disbursement rejected because the receiver account's info is invalid.	Yes	Please double check if the receiver account's info is correct before retrying.

Get Current Merchant Balance

The balance API allows Partner to check the Disbursement fund in MoMo system of the following Disbursement models:
-Domestic Disbursement: only checks local currency VND.
-Disbursement Remittance: check local currency VND and other global currencies such as: USD, EUR, AUD, etc.

HTTP Request

POST /v2/gateway/api/disbursement/balance

Parameter	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestId	String(50)		Request ID, unique for each request
lang	String		Language of returned message (vi or en)
orderGroupId	Long		The orderGroupId is provided by MoMo & is used to distinguish groups of the Merchant balance (in accordance with the currency). If you want to use this field, please contact MoMo to get data information.
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",
    "orderGroupId": 1000,
    "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
amount	Long		Reflect the Merchant's remaining balance in MoMo system.
currency	String		The currency (regrarding the amount as the Merchant's remaining balance): VND, USD, EUR, AUD, etc

Example response

{
   "partnerCode": "MOMOIOLD20190129",
   "orderId": "1678855132446:0123456778",
   "requestId": "1678855132446id",
   "amount": 0,
   "currency": "VND",
   "responseTime": 1678855132481,
   "message": "Successful.",
   "resultCode": 0
}

Response Codes and Messages: API Get Current Merchant Balance

These are some response codes which are only used for Get Current Merchant Balance process:

Response code	Description	Final status	Recommended actions
0	Successful	Yes
99	Unknown error.	Yes	Please contact MoMo for more details.
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.

Payment Processing

Allow partner to request MoMo pay specific amount of money to corresponding user's wallet

Minimum timeout when call this API must be 30s to ensure receive response from MoMo.

HTTP Request

POST /v2/gateway/api/disbursement/pay

Parameter	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
amount	Long		A specific amount Currency: VND - Disburse to wallet: Min: 1.000 VND; Max: up to 200.000.000 VND (according to the user's receiving limit of funds) - Disburse to bank: Min: 20.000 VND ; Max: 20.000.000 VND
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
requestType	String		disburseToWallet or disburseToBank
disbursementMethod	String		Encrypt a object json by RSA using public Key RSA Encryption
ipnUrl	String		Merchant’s API Endpoint. Used by MoMo to send payment results via IPN method (server-to-server)
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key": "value"} Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
orderInfo	String		Short information
orderGroupId	Long		The orderGroupId is provided by MoMo & is used to distinguish groups of the Merchant balance (in accordance with the currency). If you want to use this field, please contact MoMo to get data information.
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&amount=$amount&disbursementMethod= $disbursementMethod&extraData=$extraData&orderId=$orderId& orderInfo=$orderInfo&partnerCode=$partnerCode& requestId=$requestId&requestType=$requestType

Data of disbursementMethod before encrypted

Disburse To Wallet:

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.

Disburse To Bank: There are 2 options for Merchant disbursing to bankAccountNo OR bankCardNo in a request. Please check the detailed request for each option below.

Via Bank Account Number

Parameter	Type	Required	Description
bankAccountNo	String		Bank account number of the disbursement receiver.
bankAccountHolderName	String		Bank account's holder name of the disbursement receiver.
bankCode	String		Please follow by BankCode - Example: VCB; ACB; BIDV etc.

Via Bank Card Number

Parameter	Type	Required	Description
bankCardNo	String		Bank Card Number of the disbursement receiver. (Supported Bank Card Number, please check details with bin/Bin Card of bankCode list)
bankAccountHolderName	String		Bank account's holder name of the disbursement receiver.
bankCode	String		Please follow by BankCode - Example: VCB; ACB; BIDV etc.

Example request

{
    "partnerCode": "MOMOIOLD20190129",
    "ipnUrl": "abc.com",
    "redirectUrl": "abc.com",
    "orderId": "12545465654656",
    "amount": "500000",
    "lang": "vi",
    "autoCapture": true,
    "orderInfo": "Thanh toan MoMo",
    "requestId": "365656d56sd",
    "orderGroupId": 1000,
    "extraData": "",
    "requestType": "disburseToWallet",
    "partnerClientId": "test@momo.vn",
    "disbursementMethod": "mo6dgtb5nz7W91O3MQNr1cuR8rnggp4J23dNEn8K0PTIWQcZtd/Zu/fGXpNkTJoZvPcwb9awqi8ZxHEIZu/fByS6vqirlqjpAbsNlXA5OsfxbDKjtkbbcz6Xi7ryI8Rlx8X4LrjshCcvnyHlCFQNBZrBHdjQXm/gfDli/1nfg2IjrBqW2o9Msc5VWRh5vGQdSGfsoo3CCJPFL3/jPEw2J3032pUPbD7zbpsFkYbYKGfszXa4Eyff1XuBWBu0zvtPTfpWS3pl238pgw0ObBWua0SDYPNtXv41sZuadURpDr/Mj9/WNL/lGuPWs2ILShr/9OOHB+l9uuS/J+50hqDLDIWcTS5ir2640eDcoq8HOpvu/hU7jiDGsRzSFO7iYUgehzDSheaGjvRlmtuhGJ3josHKhHIrAS2kckIBTNw7EjuATDlf2a4yOZLLsniXbSB2r/IvfPe0ZRPAD8euzIFpXasxlr4bj1VUEMuHP6ep0UrGfHrCfoWDbIbbmpuMVqhXWI1kmS9YD59hxSaJvwqkaWDkjIY2s6uWgbKno4YAv4uzxexAbIe8Z4UfILPrKhxh3pcxbnPXIZNzgslxAPEvgg2dtodjIUlUYSHg32A/gPCGXdvEVZOPBsuiGe5QkDS0uXdTNyCaNsiWUwxB74yikfCxrCNN1IOH2XZJRJfTjbc=",
    "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
amount	Long		Same as the original amount in the request Currency: VND.
transId	Long		MoMo's transaction ID
responseTime	Long		Time to respond payment results to partner Format: timestamp
resultCode	Integer		Order status
message	String		Result description, language is based on lang
balance	Long		Current Merchant balance after disbursing Note: just in case the response data is null - to be updated. Please proceed to use API Get Current Merchant Balance to get the details.

Example response

{
  "partnerCode": "MOMOIOLD20190129",
  "orderId": "OD1675914157849",
  "requestId": "RE1675914157849",
  "amount": 20000,
  "responseTime": 1675914162783,
  "message": "Successful.",
  "resultCode": 0,
  "transId": 2847016267,
  "balance": 27560046505
}

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
orderId	String		Partner Transaction ID
requestId	String		Partner's requestId
amount	Long		Same as the original amount in the request
orderInfo	String		Order's information
partnerUserId	String		MoMo's unique identifier for each MoMo eWallet account.
orderType	String		momo_disbursement
transId	Long		MoMo's transaction ID
resultCode	Integer		Transaction status of the order Result Code
message	String		Error description, languague is based on lang
responseTime	Long		Time to respond payment results to partner Format: timestamp
extraData	String		Extra Data. Default: ""
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&extraData=$extraData &message=$message&orderId=$orderId&orderInfo=$orderInfo &orderType=$orderType&partnerCode=$partnerCode &requestId=$requestId&responseTime=$responseTime &resultCode=$resultCode&transId=$transId

Result Codes & Messages

These result codes and messages are exclusively assigned for the 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
10	Server connection error.	No	Please retry after the maintenance is over.
20	Bad format request.	No	Please check the request format or any missing parameters.
22	The transaction amount is out of range.	No	Please check if the amount is within the allowed range of each payment method. For capture request, check if the capture amount matches the authorized amount.
40	Duplicated requestId.	No	Please retry with a different requestID.
42	Invalid orderId or orderId is not found.	No	Please retry with a different orderId.
99	Unknown error.	Yes	Please contact MoMo for more details.
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.
1008	Transaction failed because the amount exceeds user's receiving limit of funds.	Yes	Please retry the disbursement request with a lower amount.
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.
1507	BankCard/ Bank Account not found or BankCode did not exist. Please check the Bank Information and retry again.	Yes	Please check and retry another Bank Card/ bank Account info or the list of supported BankCode.
4001	Transaction rejected because the user account is being restricted.	Yes	Please contact MoMo for the restriction details of this certain user account.
4002	Transaction rejected because the user account has not been verified by C06.	Yes	Users must update their biometrics via NFC to be authorized for the transaction.
4003	Disbursement rejected because the receiver account's info is invalid.	Yes	Please double check if the receiver account's info is correct before retrying.
7000	Transaction is being processed.	No	Please wait for the transaction to be fully processed.
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.

See also

• Check Transaction Status
• Reverse & Refund
• Confirm Payment