Remittance

Process Flow

Disburse 1 step

Disburse 2 steps

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

Parameter	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Each Request’s Identification
baseCurrency	String		Please 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.
lang	String		Language of returned message (vi or en). Default will be 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&partnerCode=$partnerCode&requestId=$requestId

The MoMo Currency Table (based on ISO 4217)

No	Currency Name	Currency Code
1	US Dollar	USD
2	Euro	EUR
3	Australian Dollar	AUD
4	Canadian Dollar	CAD
5	Pound Sterling	GBP
6	Japanese Yen	JPY
7	South Korean Won	KRW
8	New Taiwan Dollar	TWD
9	Thai Baht	THB

Example request

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

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Each Request’s Identification
responseTime	Long		Time to respond payment results to partner Format: timestamp
resultCode	Integer		Order status
message	String		Request result, language is based on lang
rateInfo	Object		F(x)rate information

Data of rateInfo :

Parameter	Type	Required	Description
baseCurrency	String		The chosen currency (USD, EUR, AUD, etc) has been requested for checking the exchange rate.
exchangeCurrency	String		The exchangeCurrency will be reflected in VND.
rate	Long		The 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

Parameter	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestId	String		Each Request’s Identification
rateInfo	Object		F(x)rate information should be attached for the validation process from the API Check exchange rate.
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& partnerCode=$partnerCode&requestId=$requestId

Data of rateInfo :

Parameter	Type	Required	Description
baseCurrency	String		Please indicate which currency (USD, EUR, AUD, etc) Partner wants to check the exchange rate against home currency (as VND).
amount	Float		This 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.
exchangeCurrency	String		The exchange currency will be reflected in VND
rate	Long		The 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

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		Request result, language is based on lang
rateInfo	Object		rate information

Data of rateInfo :

Parameter	Type	Required	Description
baseCurrency	String		The chosen currency (USD, EUR, AUD, etc) is based on the Merchant request.
amount	Float		The requested amount of the convertible currency process.
exchangeCurrency	String		The exchanged currency will be reflected in VND.
rate	Long		The amount value related to the requested exchange Currency.
exchangeAmount	Long		The 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

Parameter	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestId	String		Each Request’s Identification
requestType	String		checkWallet
receiver	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&orderId=$orderId& partnerCode=$partnerCode& &receiver=receiver&requestId=$requestId&requestType=$requestType

Data of receiver before encrypted:

Parameter	Type	Required	Description
walletId	String		MoMo'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)
walletName	String		MoMo Wallet Holder's name has registered with MoMo
personalId	Long		Personal 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

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		Request 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

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(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
receiver	String		Encrypt a object json by RSA using public Key RSA Encryption
requestType	String		remitToWallet
ipnUrl	String		Merchant’s API Endpoint. Used by MoMo to send payment results via IPN method (server-to-server)
orderInfo	String		Order's information
amount	Long		Amount 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).
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.
remittanceInfo	Object		remittance information
autoCapture	Boolean		If 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
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key": "value"} Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
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&orderId=$orderId& orderInfo=$orderInfo&partnerCode=$partnerCode&receiver=receiver& requestId=$requestId&requestType=requestType

Data of receiver before encrypted:

Parameter	Type	Required	Description
walletId	String		MoMo'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)
walletName	String		MoMo Wallet Holder's name has registered with MoMo
personalId	Long		Personal 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

Attribute	Type	Required	Description
name	String		Sender's Full Name as registered on partner platform
phoneNumber	String		Sender's Phone Number as registered on partner platform. Note: This format data is supported by up to 15-digit numbers.
address	String		Sender's Address as registered on partner platform
email	String		Sender's Email address as registered on partner platform
partnerName	String		The name of Merchant or Merchant's Partners who are associated with the remittance service/platform. Note: Please contact MoMo to get the details.
partnerAccountId	String		The vendor’s unique identifier for the sender as registered on the partner platform such as User ID.
orderingCountry	String		Original 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.
sourceCurrency	String		Please use the three-letter ISO 4217 code for the sourceCurrency format in this field For example, source currency as (USD, EUR, AUD, etc). Default: USD
sourceAmount	String		The value of the amount related to sourceCurrency that the sender wants to transfer.
reason	String		Description 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

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		Request result, language is based on lang
transId	Long		MoMo's transaction ID
amount	Long		Amount as the remittance money in VND that the receiver will receive.
sourceCurrency	String		Source currency such as (USD, EUR, AUD, etc) from merchant request
sourceAmount	String		The value of the amount related to sourceCurrency that the sender wants to transfer.
settledStatus	Object		Inform the receiving money process of the receiver.

Data of settledStatus:

Parameter	Type	Required	Description
state	String		The state of how money is processed to the receiver. There are 3 types of state such as Received, Processing, Failed.
description	String		These 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.

Attribute	Type	Required	Description
partnerCode	String		Integration Information
orderId	String		Partner Transaction ID
requestId	String		Partner's requestId
amount	Long		Amount as the remittance money in VND that the receiver will receive.
orderInfo	String		Order's information
partnerUserId	String		MoMo's unique identifier for each MoMo e-Wallet account.
orderType	String		momo_remittance
transId	Long		MoMo's transaction ID
resultCode	Integer		Transaction status of the order Result Code
message	String		Transaction result, 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

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

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

See also

• Check Transaction Status
• Reverse & Refund
• Confirm Payment