Single Disbursement
Process Flow
API Configuration
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
| 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",
"oderGroupId": 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. | |
| validatePersonalId | Boolean | Default = false : do transfer without validate personal id = True : validate personal id corresponding wallet |
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",
"partnerName": "Test",
"storeId": "MoMo test store",
"ipnUrl": "abc.com",
"redirectUrl": "abc.com",
"orderId": "12545465654656",
"amount": "500000",
"lang": "vi",
"autoCapture": true,
"orderInfo": "Thanh toan MoMo",
"requestId": "365656d56sd",
"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 | |
| 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. |
| 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. |