Nhảy tới nội dung

Single Disbursement

Process Flow

Disbursement_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. 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/verify

ParameterTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestIdString(50)Request ID, unique for each request
requestTypeStringcheckWallet
disbursementMethodStringEncrypt a object json by RSA using public Key RSA Encryption
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&disbursementMethod=
$disbursementMethod&orderId=$orderId&
partnerCode=$partnerCode&
requestId=$requestId&requestType=$requestType

Data of disbursementMethod before encrypted: API Check Wallet Status

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

{
"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

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

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 codeDescriptionFinal statusRecommended actions
0SuccessfulYes
10Server connection error.NoPlease retry after the maintenance is over.
20Bad format request.NoPlease check the request format or any missing parameters.
99Unknown error.YesPlease contact MoMo for more details.
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.
4001Transaction rejected because the user account is being restricted.YesPlease contact MoMo for the restriction details of this certain user account.
4003Disbursement rejected because the receiver account's info is invalid.YesPlease 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

ParameterTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestIdString(50)Request ID, unique for each request
langStringLanguage of returned message (vi or en)
orderGroupIdLongThe 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.
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",
"orderGroupId": 1000,
"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
amountLongReflect the Merchant's remaining balance in MoMo system.
currencyStringThe 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 codeDescriptionFinal statusRecommended actions
0SuccessfulYes
99Unknown error.YesPlease contact MoMo for more details.
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.

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

ParameterTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
amountLongA 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
requestIdString(50)Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
requestTypeStringdisburseToWallet or disburseToBank
disbursementMethodStringEncrypt a object json by RSA using public Key RSA Encryption
ipnUrlStringMerchant’s API Endpoint. Used by MoMo to send payment results via IPN method (server-to-server)
extraDataStringDefault value is empty ""
Encode base64 follow Jsonformat: {"key": "value"}
Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
orderInfoStringShort information
orderGroupIdLongThe 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.
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&amount=$amount&disbursementMethod=
$disbursementMethod&extraData=$extraData&orderId=$orderId&
orderInfo=$orderInfo&partnerCode=$partnerCode&
requestId=$requestId&requestType=$requestType

Data of disbursementMethod before encrypted

Disburse To Wallet:

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.

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

ParameterTypeRequiredDescription
bankAccountNoStringBank account number of the disbursement receiver.
bankAccountHolderNameStringBank account's holder name of the disbursement receiver.
bankCodeStringPlease follow by BankCode
- Example: VCB; ACB; BIDV etc.

Via Bank Card Number

ParameterTypeRequiredDescription
bankCardNoStringBank Card Number of the disbursement receiver.
(Supported Bank Card Number, please check details with bin/Bin Card of bankCode list)
bankAccountHolderNameStringBank account's holder name of the disbursement receiver.
bankCodeStringPlease 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

AttributeTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestIdStringEach Request’s Identification
amountLongSame as the original amount in the request
Currency: VND.
transIdLongMoMo's transaction ID
responseTimeLongTime to respond payment results to partner Format: timestamp
resultCodeIntegerOrder status
messageStringResult description, language is based on lang
balanceLongCurrent 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.

AttributeTypeRequiredDescription
partnerCodeStringIntegration Information
orderIdStringPartner Transaction ID
requestIdStringPartner's requestId
amountLongSame as the original amount in the request
orderInfoStringOrder's information
partnerUserIdStringMoMo's unique identifier for each MoMo eWallet account.
orderTypeStringmomo_disbursement
transIdLongMoMo's transaction ID
resultCodeIntegerTransaction status of the order Result Code
messageStringError description, languague is based on lang
responseTimeLongTime to respond payment results to partner
Format: timestamp
extraDataStringExtra Data. Default: ""
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&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 codeDescriptionFinal statusRecommended actions
0Successful.Yes
10Server connection error.NoPlease retry after the maintenance is over.
20Bad format request.NoPlease check the request format or any missing parameters.
22The transaction amount is out of range.NoPlease 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.
40Duplicated requestId.NoPlease retry with a different requestID.
42Invalid orderId or orderId is not found.NoPlease retry with a different orderId.
99Unknown error.YesPlease contact MoMo for more details.
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.
1008Transaction failed because the amount exceeds user's receiving limit of funds.YesPlease retry the disbursement request with a lower amount.
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.
1507BankCard/ Bank Account not found or BankCode did not exist. Please check the Bank Information and retry again.YesPlease check and retry another Bank Card/ bank Account info or the list of supported BankCode.
4001Transaction rejected because the user account is being restricted.YesPlease contact MoMo for the restriction details of this certain user account.
4003Disbursement rejected because the receiver account's info is invalid.YesPlease double check if the receiver account's info is correct before retrying.
7000Transaction is being processed.NoPlease wait for the transaction to be fully processed.
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.

See also