Nhảy tới nội dung

Remittance

Process Flow

Disburse 1 step

Remittance Disburse_flow

Disburse 2 steps

Remittance Disburse_flow

API Configuration

HTTP Information

Check Exchange Rate

The API supports Partner to retrieve the currency exchange information before initiating the currency conversion process of the Remittance operation. Besides, the API will handle and return for any given base currency (default USD).

HTTP Request

POST /v2/gateway/api/remittance/exchange-rate

ParameterTypeRequiredDescription
partnerCodeStringIntegration information
requestIdStringEach Request’s Identification
baseCurrencyStringPlease indicate which currency (USD, EUR, AUD, etc) Partner wants to check the exchange rate against home currency (as VND).
Note: the supported currency will be processed based on Currency Code of the MoMo currency table as below.
langStringLanguage of returned message (vi or en). Default will be 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&partnerCode=$partnerCode&requestId=$requestId

The MoMo Currency Table (based on ISO 4217)

NoCurrency NameCurrency Code
1US DollarUSD
2EuroEUR
3Australian DollarAUD
4Canadian DollarCAD
5Pound SterlingGBP
6Japanese YenJPY
7South Korean WonKRW
8New Taiwan DollarTWD
9Thai BahtTHB

Example request

{
"partnerCode": "MOMOIOLD20190129",
"lang": "vi",
"requestId": "365656d56sd",
"baseCurrency": "USD",
"signature": "2c46ac1270b38969c08e2dcc2d939c4a2e0485a12a8583a775378fdd11bb890d"
}

HTTP Response

AttributeTypeRequiredDescription
partnerCodeStringIntegration information
requestIdStringEach Request’s Identification
responseTimeLongTime to respond payment results to partner Format: timestamp
resultCodeIntegerOrder status
messageStringRequest result, language is based on lang
rateInfoObjectF(x)rate information
Data of rateInfo :
ParameterTypeRequiredDescription
baseCurrencyStringThe chosen currency (USD, EUR, AUD, etc) has been requested for checking the exchange rate.
exchangeCurrencyStringThe exchangeCurrency will be reflected in VND.
rateLongThe amount value related to the requested exchangeCurrency.

Example response

{
"partnerCode": "MOMOIOLD20190129",
"requestId": "RE1675914157849",
"responseTime": 1675914162783,
"message": "Successful.",
"resultCode": 0,
"rateInfo": {
"baseCurrency": "USD",
"exchangeCurrency": "VND",
"rate": 23000
}
}

Converting the Currency

After the exchange rate process at the desirable rate, the Partner uses this API to request the convertible process from another currency's value to the Vietnam currency’s value.

HTTP Request

POST /v2/gateway/api/remittance/buy

ParameterTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestIdStringEach Request’s Identification
rateInfoObjectF(x)rate information should be attached for the validation process from the API Check exchange rate.
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&
partnerCode=$partnerCode&requestId=$requestId
Data of rateInfo :
ParameterTypeRequiredDescription
baseCurrencyStringPlease indicate which currency (USD, EUR, AUD, etc) Partner wants to check the exchange rate against home currency (as VND).
amountFloatThis field shall be processed with the decimal digits and rounded to the hundredths place (up to two decimal places). Example: USD 1.25.
Note: The valid amount will be followed (apply for the currencies):
- Min: must be higher than 1.00
- Max: up to the remaining amount in the merchant's foreign currency wallet.
exchangeCurrencyStringThe exchange currency will be reflected in VND
rateLongThe amount value related to the requested exchangeCurrency.

Example request

{
"partnerCode": "MOMOIOLD20190129",
"orderId": "12545465654656",
"lang": "vi",
"requestId": "365656d56sd",
"rateInfo": {
"baseCurrency": "USD",
"exchangeCurrency": "VND",
"amount": 1.25,
"rate": 23000
},
"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
messageStringRequest result, language is based on lang
rateInfoObjectrate information
Data of rateInfo :
ParameterTypeRequiredDescription
baseCurrencyStringThe chosen currency (USD, EUR, AUD, etc) is based on the Merchant request.
amountFloatThe requested amount of the convertible currency process.
exchangeCurrencyStringThe exchanged currency will be reflected in VND.
rateLongThe amount value related to the requested exchange Currency.
exchangeAmountLongThe exchangeAmount will be calculated and reflected in the convertible result. (Example: exchangeAmount = amount * rate)
Note: The exchangeAmount format can be processed up to 12 digit numbers (example as VND 100.000.000.000) when exchanging other global currencies to VietNam dong.

Example response

{
"partnerCode": "MOMOIOLD20190129",
"orderId": "OD1675914157849",
"requestId": "RE1675914157849",
"responseTime": 1675914162783,
"message": "Successful.",
"resultCode": 0,
"rateInfo": {
"baseCurrency": "USD",
"amount": 1.25,
"exchangeCurrency": "VND",
"rate": 23000,
"exchangeAmount": 28750
}
}

Check Wallet Status

This API provides Merchant an option to check the status of the receiver’s Wallet to receive money based on MoMo policies before implementing a remittance order creation request.

In addtional, to avoid any arising inconvenience during the disbursement process, users are required to comply with the Circular No. 23 of the State Bank of VietnamIn : Wallet is linking bank account (excluded linking ATM Card/ Debit Card/ Credit Card) + verified KYC information + done Face matching process in MoMo App.

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

HTTP Request

POST /v2/gateway/api/remittance/verify

ParameterTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestIdStringEach Request’s Identification
requestTypeStringcheckWallet
receiverStringEncrypt 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&orderId=$orderId&
partnerCode=$partnerCode&
&receiver=receiver&requestId=$requestId&requestType=$requestType

Data of receiver before encrypted:

ParameterTypeRequiredDescription
walletIdStringMoMo's Wallet Number (phone number has registered with MoMo) will be received the remittance money.
Please proceed with format: "0xxxxx" or "+84" xxxx (For Example: 090xx, 0122xx, +84 92xx)
walletNameStringMoMo Wallet Holder's name has registered with MoMo
personalIdLongPersonal ID which is issued by Vietnam government and verified by MoMo.
This field data should be processed with digit numbers and supported up to 12 digit numbers such as:
- Old ID Card No: Example as 025xx (format is in 9 digit numbers)
- New ID Card No: Example as 079xx (format is in 12 digit numbers)

Example request

{
"partnerCode": "MOMOIOLD20190129",
"orderId": "12545465654656",
"lang": "vi",
"requestId": "365656d56sd",
"requestType":"checkWallet",
"receiver": "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
messageStringRequest result, language is based on lang

Example response

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

Get Current Merchant Balance

The balance API allows Partner to see the current balance of Disburse funds in MoMo system before processing the disbursement request.

Access Get Balance to learn more.

Create a Remittance Order

HTTP Request

POST /v2/gateway/api/remittance/create

Body
AttributeTypeRequiredDescription
partnerCodeStringIntegration information
orderIdStringPartner Transaction ID
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestIdString(50)Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
receiverStringEncrypt a object json by RSA using public Key RSA Encryption
requestTypeStringremitToWallet
ipnUrlStringMerchant’s API Endpoint. Used by MoMo to send payment results via IPN method (server-to-server)
orderInfoStringOrder's information
amountLongAmount in VND that the sender wants to transfer.
- Min: 1.000 VND; Max: up to 200.000.000 VND (according to the user's receiving limit of funds).
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.
remittanceInfoObjectremittance information
autoCaptureBooleanIf set to false, the payment will not be automatically captured.
Merchant proceeds autoCapture one of the values based on the Disbursement option such as:
- Disburse 1 step as TRUE
- Disburse 2 steps as FALSE
extraDataStringDefault value is empty ""
Encode base64 follow Jsonformat: {"key": "value"}
Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
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&orderId=$orderId&
orderInfo=$orderInfo&partnerCode=$partnerCode&receiver=receiver&
requestId=$requestId&requestType=requestType
Data of receiver before encrypted:
ParameterTypeRequiredDescription
walletIdStringMoMo's Wallet Number (phone number has registered with MoMo) will be received the remittance money.
Please proceed with format: "0xxxxx" or "+84" xxxx (For Example: 090xx, 0122xx, +84 92xx)
walletNameStringMoMo Wallet Holder's name has registered with MoMo
personalIdLongPersonal ID Number which is issued by Vietnam government and verified by MoMo.
This field data should be processed with digit numbers and supported up to 12 digit numbers such as:
- Old ID Card No: Example as 025xx (format is in 9 digit numbers)
- New ID Card No: Example as 079xx (format is in 12 digit numbers)
Details of remittanceInfo content
AttributeTypeRequiredDescription
nameStringSender's Full Name as registered on partner platform
phoneNumberStringSender's Phone Number as registered on partner platform.
Note: This format data is supported by up to 15-digit numbers.
addressStringSender's Address as registered on partner platform
emailStringSender's Email address as registered on partner platform
partnerNameStringThe name of Merchant or Merchant's Partners who are associated with the remittance service/platform.
Note: Please contact MoMo to get the details.
partnerAccountIdStringThe vendor’s unique identifier for the sender as registered on the partner platform such as User ID.
orderingCountryStringOriginal Country of Ordering Customer where fund transfer initiated
Before processing data, please follow the ISO country codes based on a two-letter combination (according to the worldwide public of iso.org), that stands for a country or a state.
Note: The default data will be processed as VN (VietNam). However, for other international partners please adjust according to the original country/ current operation state.
sourceCurrencyStringSource currency (USD, EUR, AUD, etc). Default: USD
sourceAmountStringThe value of the amount related to sourceCurrency that the sender wants to transfer.
reasonStringDescription for receiving money. Please kindly follow the format data based on MoMo rule from MM01 to MM06.
Before processing data, here is the detailed information of the format.
MM01: Give to family and relatives.
MM02: Charitable sponsorship.
MM03: Business Investment.
MM04: Payment for goods and services.
MM05: Payment of salaries.
MM06: Others.

Example body request

{
"partnerCode": "MOMOIOLD20190129",
"ipnUrl": "abc.com",
"orderId": "12545465654656",
"amount": "12000000",
"lang": "vi",
"extraData": "",
"orderInfo": "Thanh toan MoMo",
"requestId": "365656d56sd",
"orderGroupId": 5423,
"requestType":"remitToWallet",
"remittanceInfo": {
"phoneNumber": "0987654321",
"name": "Stanley Nguyen",
"address": "111 West Broadway,Vancouver",
"email": "123@abc.com",
"partnerAccountId": "12345678",
"partnerName": "AService",
"orderingCountry": "VN",
"sourceCurrency": "USD",
"sourceAmount": 500,
"reason":"MM01"
},
"receiver": "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
messageStringRequest result, language is based on lang
transIdLongMoMo's transaction ID
amountLongAmount as the remittance money in VND that the receiver will receive.
sourceCurrencyStringSource currency such as (USD, EUR, AUD, etc) from merchant request
sourceAmountStringThe value of the amount related to sourceCurrency that the sender wants to transfer.
settledStatusObjectInform the receiving money process of the receiver.
Data of settledStatus:
ParameterTypeRequiredDescription
stateStringThe state of how money is processed to the receiver. There are 3 types of state such as Received, Processing, Failed.
descriptionStringThese additonal information provided the further information regarding state and the recommandations. Please check the details as below:
- Received: Receiver has successfully received the fund.
- Processing: The fund is being delivered to the Receiver. Please check the final status via API Payment Notification or call API Check Transaction Status.
-Failed: Failed to deliver the fund to the Receiver. Please request a new transaction.

Example response

{
"partnerCode": "MOMOIOLD20190129",
"orderId": "1679474322720OD",
"requestId": "1679474333365id",
"resultCode": 0,
"message": "Success",
"responseTime": 1679474335724,
"transId": 123456,
"amount": "12000000",
"sourceCurrency": "USD",
"sourceAmount": 500,
"settledStatus": {
"state": "Received",
"description": "Receiver has successfully received the fund."
}
}

Kindly take note of the service rule: After processing a Remittance Order, please help ensure that the Receiver shall be successfully received the money via MoMo e-Wallet in case Receiver accepts the T&C/ Consent in "Nhận tiền Quốc tế" service in MoMo app (Applied for the Receiver using Remittance service for the 1st time)


Note: Only Apply for Global Merchant processing flow.

Confirm for paying the created order

This API is used in case of autoCapture flat is false when the merchant created the order

Access Confirm Payment to learn more.

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
amountLongAmount as the remittance money in VND that the receiver will receive.
orderInfoStringOrder's information
partnerUserIdStringMoMo's unique identifier for each MoMo e-Wallet account.
orderTypeStringmomo_remittance
transIdLongMoMo's transaction ID
resultCodeIntegerTransaction status of the order Result Code
messageStringTransaction result, 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

Response Codes & Messages: Disbursement Remittance process
These are some response codes which are only used for Disbursement Remittance process:

Response codeDescriptionFinal statusRecommended actions
0Successful.Yes
10System is under maintenance.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 requestType, check if the capture amount match the authorized amount.
41Duplicated orderId.NoPlease inquiry the orderId's transaction status, or retry with a different orderId.
42Invalid orderId or orderId is not found.NoPlease retry with a different orderId.
43Request rejected due to an analogous transaction is being processed.NoBefore retry, please check if another analogous transaction is being processed which restricts this request.
47Request rejected due to inapplicable information in the given set of valuable data.NoPlease review and retry with another request.
99Unknown error.YesPlease contact MoMo for more details.
1002Transaction rejected by the issuers of the payment methods.YesPlease choose other payment methods..
1003Transaction cancelled after successfully authorized.YesThe transaction was canceled by merchant or MoMo system due to timeout handlers. Please mark the transaction as failed.
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.
1500Transaction rejected because the waiting period has expired/passed.Yes
1501The expected exchange rate is invalid or outdated.YesPlease update with the latest currency exchange rate.
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.
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.
9000Transaction is authorized successfully.NoFor 1-step payment, please mark this transaction as success.
For 2-step payment, please proceed with either capture or cancel request. For binding, please proceed to request the recurring token.
9100The transaction is processed and awaiting user acceptance of receiving.NoPlease wait for the transaction to be updated final status. The transaction status will be notified once it's done processing.

See also